Požadavek login

Účel a dopady

Založí (nebo znovupoužije) session na straně serveru a vrátí její identifikátor. Skutečné ověření uživatelského jména a hesla probíhá už na úrovni HTTP autentizace před zpracováním XML požadavku – uzel <login> už jen session zakládá/vrací a u dvoufázové (SMS) autentizace zahajuje druhé kolo přihlášení.

Dostupnost, kontext, oprávnění apod.

• Vyžaduje platně autentizovaného uživatele na HTTP úrovni (jinak se zpracování XML těla vůbec nedostane); samotný uzel <login> žádná vlastní oprávnění nekontroluje.
• Je-li <login> prvním uzlem v obálce <request>, zpracuje se speciální větví ještě před obecným rozřazovačem požadavků – nepodléhá tedy standardnímu transakčnímu zpracování ani kontrole rozjednané session platné pro ostatní uzly.
• Vyžaduje-li uživatel SMS dvoufázovou autentizaci (atribut sms uživatele roven "Y", nebo "P" a připojení z veřejné IP adresy – viz get-user), nově založená session zůstává ve stavu „justlogin“, dokud handshake nedoběhne; do té doby server zamítá všechny ostatní uzly v rámci session chybou „Vase prihlaseni nebylo dokonceno“.

XML požadavek (syntax + popis)

  <request>
   <login/>
  </request>

Parametry a pravidla (atributy, potomci)

Požadavek login nemá žádné atributy ani potomky – server je u tohoto uzlu vůbec nečte.

Příklady požadavku

(Zatím bez ověřeného příkladu.)

Zpracování a vedlejší účinky

• Server založí (nebo, existuje-li už session, obnoví) záznam session a vrátí jeho identifikátor jako atribut session – vždy přesně 16 znaků malých hexadecimálních číslic, zleva doplněných nulami.
• Používá-li session tzv. digest autentizaci, přidá se do odpovědi i salt (materiál, který klient potřebuje pro výpočet hashe v dalších požadavcích).
• Vyžaduje-li session SMS dvoufázovou autentizaci, přidá se auth="sms" a server se pokusí odeslat SMS s autentizačním kódem na mobilní číslo uživatele; nepodaří-li se to (viz čtyři důvody v „Chyby a reakce“), server nově založenou session rovnou zase zruší a odpověď se dodatečně změní z type="ok" na type="error" – vrácené session/salt jsou v takovém případě už neplatné.
• Není-li SMS vyžadována, auth je vždy přítomen jako prázdný řetězec.

XML odpověď (syntax + popis)

  <response>
   <login
    type="ok|error"
    session="{string}"
    salt="{string}"
    lang="{string}"
    auth="{string}"
    detail="{string}"
    />
  </response>

Parametry a pravidla (atributy, potomci) – odpověď

• type - Výsledek - "ok"/"error". (typ: enum; povolené hodnoty: ok, error)
• session - Identifikátor session - 16 hexadecimálních znaků (malá písmena, zleva doplněno nulami). (typ: string)
• salt - Materiál pro digest autentizaci - Přítomen, jen používá-li session digest autentizaci. (typ: string)
• lang - Jazyk uživatele - Dvouznakový jazykový kód. (typ: string)
• auth - Druh dalšího kroku autentizace - Prázdný řetězec (žádný další krok), nebo "sms" (čeká se na zadání kódu zaslaného SMS). (typ: enum; povolené hodnoty: prázdný řetězec, sms)
• detail - Popis chyby - Přítomen jen při selhání odeslání SMS (viz „Chyby a reakce“); požadavek login v ostatních ohledech chybu negeneruje. (typ: string)

Příklady odpovědi

(Zatím bez ověřeného příkladu.)

Chyby a reakce

Ke všem níže uvedeným chybám dochází výhradně ve SMS větvi (auth="sms"), kdy se odeslání autentizačního kódu nepodaří; ve všech případech je nově založená session rovnou zrušena:

• detail="Nemate definovany mobilni telefon" – uživatel nemá v profilu vyplněné mobilní číslo.
• detail="SMS sluzba neni spustena" – server nemá spuštěnou SMS službu.
• detail="SMS sluzba nebezi spravne" – SMS služba běží, ale její spooler není otevřený.
• detail="Telefonni cislo neni kodovatelne do ASCII" – mobilní číslo nelze převést do ASCII/UTF-8.
• detail="Zpravu se nepodarilo odeslat" – odeslání SMS selhalo na úrovni spooleru.
• Výraz pro identifikaci chyb v odpovědi serveru: login[@type='error'].

Související požadavky

• logout – ukončení a výmaz session založené tímto požadavkem.