Vícefaktorové ověření ve Web API

Vícefaktorové ověřování (MFA) se vztahuje také na integrace, e-shopy, reportovací nástroje, mobilní aplikace a vlastní skripty, které se do Web API přihlašují jménem uživatele. Jednorázový ověřovací kód dokáže zpracovat pouze vícekrokové přihlášení autentizačního API.

Obecný popis MFA, jeho nastavení a registrace autentizační aplikace naleznete v kapitole Vícefaktorové ověřování (MFA).

Pokud uživatel musí při přístupu do Web API použít MFA, nelze jej přihlásit pomocí HTTP Basic, endpointů logintoken ani createsession. Takové přihlášení skončí odpovědí 401 insufficient_user_authentication. Použijte přihlašovací bránu nebo níže popsané vícekrokové přihlášení.

Příprava klientské aplikace

V agendě Definice JWT založte nebo upravte definici používanou integrací:

  1. Vyplňte jedinečný Kód aplikace. V požadavcích se používá jako parametr client_id.
  2. Nastavte účel Vydávání tokenů aplikacím a druh aplikace Vlastní integrace.
  3. Pro aplikaci spuštěnou u uživatele zvolte typ Veřejná aplikace (bez tajemství, s PKCE). Pro serverovou službu lze použít typ Důvěrná aplikace (s tajemstvím).
  4. Zapněte Nosič Bearer token. Má-li aplikace pracovat s cookie relací, zapněte místo něj nebo současně Nosič cookie relace.
  5. Má-li aplikace obnovovat přihlášení bez nového zadání hesla, zapněte Vydávat obnovovací token. Veřejná aplikace s obnovovacími tokeny musí používat neprůhledný obnovovací token.
  6. Ověřte, že je definice aktivní a uživatel má k této definici právo Použít.

Doporučený způsob přihlášení

Pro přihlášení uživatele s povinným MFA doporučujeme použít přihlašovací bránu Web API serveru. Klientská aplikace přesměruje prohlížeč uživatele na standardní autorizační endpoint:

GET https://<adresa_API_serveru>/<spojení>/oauth/authorize

Web API server poté sám otevře přihlašovací stránku /<spojení>/oauth/logingate. Uživatel na ní zadá přihlašovací údaje a provede všechny další požadované kroky. Při prvním přihlášení zaregistruje autentizační aplikaci, při dalších přihlášeních zadá aktuální jednorázový kód.

Dobu, ve které musí uživatel přihlášení dokončit, lze změnit parametrem server.auth.authorizationRequestTtlMs.

Přihlášení probíhá v těchto krocích:

  1. Klientská aplikace vytvoří dvojici PKCE a přesměruje prohlížeč na /oauth/authorize. V adrese předá zejména client_id, redirect_uri, code_challenge, code_challenge_method=S256 a state.
  2. Web API server ověří aplikaci a návratovou adresu a zobrazí přihlašovací stránku brány.
  3. Po úspěšném přihlášení vrátí server prohlížeč na návratovou adresu aplikace s autorizačním kódem.
  4. Aplikace smění autorizační kód a svůj code_verifier za tokeny na endpointu POST /<spojení>/oauth/token.

Klientská aplikace nemusí vytvářet vlastní přihlašovací formulář ani sama zpracovávat jednotlivé výzvy MFA. Uživatelské jméno, heslo ani ověřovací kód přes ni neprocházejí. Postup odpovídá Authorization Code Flow a umí jej každá běžná knihovna OAuth 2.1.

Příklad zahájení přihlášení:

GET https://api.example.cz/demo/oauth/authorize
    ?response_type=code
    &client_id=REPORTY
    &redirect_uri=https%3A%2F%2Freporty.example.cz%2Fcallback
    &code_challenge=59O02hXRZijQXugbVcdgoT7tNHR5fOqeSYsjf4KA-uI
    &code_challenge_method=S256
    &state=af0ifjsldkj

Adresa je v příkladu zalomena pouze kvůli přehlednosti. Ve skutečném požadavku musí tvořit jeden řádek.

Vlastní přihlašovací rozhraní

Pokud nechcete použít přihlašovací bránu, musí vaše aplikace sama zpracovat jednotlivé kroky vícefaktorového přihlášení. Klient musí vždy reagovat na typ výzvy vrácený serverem. Podporované typy se mohou v budoucnu rozšířit.

1. Připravte PKCE

Pro každé přihlášení vytvořte novou náhodnou hodnotu code_verifier. Její otisk code_challenge vznikne použitím algoritmu SHA-256 a kódováním Base64 URL bez koncových znaků =. Server podporuje pouze metodu S256.

Příklad dvojice PKCE:

code_verifier  = dBjftJeZ4CVP-mJ92K9qzBDxHsVsHLq_ptiGTIk-ZfzAHzz_pBs
code_challenge = 59O02hXRZijQXugbVcdgoT7tNHR5fOqeSYsjf4KA-uI

2. Odešlete přihlašovací údaje

Na endpoint POST /<spojení>/oauth/authorization-challenge odešlete kód aplikace, údaje PKCE, přihlašovací jméno a heslo. Tělo požadavku musí mít formát application/x-www-form-urlencoded.

První krok přihlášení:

POST https://api.example.cz/demo/oauth/authorization-challenge HTTP/1.1
Host: api.example.cz
Content-Type: application/x-www-form-urlencoded
client_id=REPORTY&response_type=code&code_challenge_method=S256&code_challenge=59O02hXRZijQXugbVcdgoT7tNHR5fOqeSYsjf4KA-uI&abra_login_name=Novak&abra_password=heslo

Server čte parametry výhradně z formulářového těla požadavku. Neposílejte je v adrese ani ve formátu JSON. Hodnoty musí být zapsané v URL kódování a každý parametr smí být uveden pouze jednou.

Pokud uživatel MFA nepotřebuje, server rovnou vrátí autorizační kód. Pokud je nutný další krok, odpoví stavem 403 insufficient_authorization. Tato odpověď neznamená neúspěšné přihlášení. Klient pokračuje podle vrácené výzvy a ve všech dalších krocích používá stejnou hodnotu auth_session.

Příklad výzvy k zadání jednorázového kódu:

{
  "error": "insufficient_authorization",
  "error_description": "Zadejte ověřovací kód z autentizační aplikace.",
  "abra_error_code": 22551,
  "auth_session": "4f0a…",
  "abra_challenge": {
    "type": "totp_verification",
    "remaining_attempts": 5,
    "expires_in": 300
  }
}
Typ výzvy Význam a zpracování
totp_enrollment Uživatel dosud nemá zaregistrovanou autentizační aplikaci. Z hodnoty abra_challenge.otpauth_uri zobrazte QR kód a jako náhradní možnost hodnotu abra_challenge.manual_key. Uživatel přidá účet do autentizační aplikace a opíše první kód. Registrační údaje neukládejte ani nezapisujte do logu.
totp_verification Uživatel již autentizační aplikaci zaregistroval. Vyžádejte aktuální kód z této aplikace.
password_change_required Uživatel musí změnit heslo. Vyžádejte nové heslo podle pravidel v položce abra_password_policy a odešlete je v parametru abra_new_password.

Příklad výzvy k první registraci autentizační aplikace:

{
  "error": "insufficient_authorization",
  "abra_error_code": 22551,
  "auth_session": "4f0a…",
  "abra_challenge": {
    "type": "totp_enrollment",
    "otpauth_uri": "otpauth://totp/ABRA%3ANovak?secret=JBSWY3DPEHPK3PXP&issuer=ABRA",
    "manual_key": "JBSW Y3DP EHPK 3PXP",
    "remaining_attempts": 5,
    "expires_in": 300
  }
}

3. Odešlete požadovaný údaj

Při registraci autentizační aplikace odešlete kód parametrem abra_totp_enrollment_code. Při běžném ověření použijte parametr abra_totp_code. V obou případech odešlete také hodnotu auth_session z předchozí odpovědi, ale znovu již neposílejte jméno ani heslo.

Odeslání jednorázového kódu při běžném ověření:

POST https://api.example.cz/demo/oauth/authorization-challenge HTTP/1.1
Host: api.example.cz
Content-Type: application/x-www-form-urlencoded
auth_session=4f0a…&abra_totp_code=123456

Chybný kód vrátí znovu stav 403 s toutéž výzvou a sníženou hodnotou remaining_attempts. Po vyčerpání povoleného počtu pokusů nebo po skončení platnosti výzvy vrátí server chybu invalid_session a klient musí zahájit přihlášení znovu.

4. Přijměte autorizační kód

Po dokončení všech požadovaných kroků vrátí server stav 200 a jednorázový autorizační kód:

{
  "authorization_code": "KCR8…"
}

Autorizační kód platí 60 sekund a lze jej použít pouze jednou.

5. Směňte kód za token

Autorizační kód odešlete společně s původní hodnotou code_verifier na endpoint POST /<spojení>/oauth/token. Důvěrná aplikace přidá také client_secret. Veřejná aplikace tajemství poslat nesmí.

Směna autorizačního kódu za token:

POST https://api.example.cz/demo/oauth/token HTTP/1.1
Host: api.example.cz
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=REPORTY&code=KCR8…&code_verifier=dBjftJeZ4CVP-mJ92K9qzBDxHsVsHLq_ptiGTIk-ZfzAHzz_pBs

Příklad odpovědi:

{
  "token_type": "Bearer",
  "access_token": "…",
  "expires_in": 3600,
  "scope": "api",
  "refresh_token": "…",
  "refresh_token_expires_in": 604800
}

Doby platnosti jsou v odpovědi uvedené v sekundách a odpovídají nastavení Definice JWT. Obnovovací token server vrátí pouze v případě, že jej použitá definice vydává.

Webová aplikace, která nechce uchovávat tokeny v prohlížeči, může autorizační kód místo toho odeslat na endpoint POST /<spojení>/oauth/session. Výsledkem je přihlášení uložené v zabezpečené cookie relaci.

6. Volejte Web API

Přístupový token posílejte v hlavičce Authorization: Bearer <access_token>. Jednorázový kód se při jednotlivých požadavcích znovu nezadává.

GET https://api.example.cz/demo/companies HTTP/1.1
Host: api.example.cz
Authorization: Bearer <access_token>

Před vypršením přístupového tokenu může aplikace použít obnovovací token:

POST https://api.example.cz/demo/oauth/token HTTP/1.1
Host: api.example.cz
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&client_id=REPORTY&refresh_token=<refresh_token>

Neprůhledný obnovovací token se při každé obnově nahradí novým a předchozí token se spotřebuje. Obnova po skončení nejdelšího trvání relace skončí chybou invalid_grant s kódem 18164. Aplikace potom musí zahájit nové přihlášení se všemi požadovanými faktory.

Chyby při přihlašování

Chyba Význam
insufficient_authorization Přihlášení vyžaduje další krok. Pokračujte podle vrácené výzvy se stejnou hodnotou auth_session.
insufficient_user_authentication Uživatel s povinným MFA se pokusil přihlásit způsobem, který nedokáže zpracovat druhý faktor.
access_denied Server odmítl přihlašovací údaje. Důvodem může být chybné jméno nebo heslo, neznámý uživatel nebo zakázané přihlášení heslem.
invalid_request V požadavku chybí povinný parametr, je neplatný nebo neodpovídá aktuálnímu kroku přihlášení. Zkontrolujte také, zda jsou parametry ve formulářovém těle požadavku.
invalid_session Rozpracované přihlášení vypršelo nebo byl vyčerpán povolený počet pokusů. Zahajte přihlášení znovu.
abra_too_many_attempts Byla aktivována ochrana proti opakovaným neúspěšným pokusům. Vyčkejte dobu uvedenou v hlavičce Retry-After.
invalid_grant Autorizační kód nebo obnovovací token je neplatný, již použitý nebo vypršel. Chybu způsobí také nesprávný code_verifier.
unauthorized_client Definice JWT nepovoluje požadovaný způsob přihlášení nebo klient nesplňuje její nastavení.
invalid_client Kód aplikace je neznámý, definice není aktivní nebo důvěrná aplikace předala chybné tajemství. U kódu aplikace se rozlišuje velikost písmen.
409 abra_session_replaced Definice povoluje pouze jednu relaci na uživatele a uživatel je již přihlášen. Po jeho potvrzení lze přihlášení zopakovat s parametrem abra_force_login=true.
temporarily_unavailable Autentizační API není momentálně dostupné. Tato situace může nastat při provozu API serveru v synchronním režimu.

Platnost přihlášení

Délku přihlášení určuje nastavení použité Definice JWT:

  • Platnost přístupového tokenu určuje, jak dlouho lze vydaný přístupový token používat.
  • Platnost obnovovacího tokenu určuje, jak dlouho lze pomocí obnovovacího tokenu získávat nové přístupové tokeny.
  • Nejdelší trvání relace představuje pevný konec celého přihlášení. Obnovení tokenů tuto dobu neprodlouží. Po jejím uplynutí se uživatel musí znovu přihlásit a při povinném MFA také zadat jednorázový ověřovací kód.
  • Odhlásit po nečinnosti se vztahuje pouze na cookie relaci. Každý požadavek s cookie začátek této doby posune. Tokeny Bearer limit nečinnosti nemají.

Zapnutí pravidla MFA automaticky neruší již vydané tokeny. Vydané tokeny a jednotlivá přihlášení lze kontrolovat v agendě Přehled vydaných tokenů API. Správce zde může zneplatnit konkrétní token nebo ukončit celé přihlášení. Všechny tokeny vydané určitou Definicí JWT lze zneplatnit funkcí Zneplatnit tokeny.

Pokud současně potřebujete odstranit uživatelův zaregistrovaný autentizátor, použijte v agendě Uživatelé funkci Resetovat zabezpečení. Uživatel si při příštím přihlášení autentizační aplikaci zaregistruje znovu.

Servisní a integrační účty

Před zapnutím MFA pro všechny uživatele zjistěte, pod kterými účty běží dávkové procesy, OLE integrace, pokladní operace nebo jiná neinteraktivní přihlášení. Na těchto místech nelze jednorázový ověřovací kód zadat.

Pokud proces nelze upravit pro podporované vícekrokové přihlášení, nastavte jeho uživateli výjimku:

  1. Na hlavním spojení otevřete agendu Parametry firmy, záložku Bezpečnostní nastavení a subzáložku Nastavení MFA.
  2. Na záložce Pravidla MFA přidejte pravidlo.
  3. Jako typ pravidla vyberte Uživatel a zvolte uživatele, pod kterým proces nebo integrace běží.
  4. Vyberte rozhraní Desktop nebo Web API podle způsobu přihlášení.
  5. Nastavte Vyžadování MFA na hodnotu Vypnuto.
  6. Používá-li účet obě rozhraní, založte výjimku pro každé z nich samostatně.

Výjimku přidělujte pouze účtům, u kterých je nezbytná. Integrace používající HTTP Basic, logintoken nebo createsession se po zapnutí povinného MFA pro svůj účet nepřihlásí a obdrží odpověď 401 insufficient_user_authentication. Integraci upravte pro vícekrokové přihlášení nebo jejímu technickému uživateli nastavte popsanou výjimku.