Authorization Code Flow
Authorization Code Flow je nejbezpečnější a doporučené flow pro serverové aplikace, které mohou bezpečně ukládat client secret.
Diagram flow
┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ │ │ │ │
│ Uživatel │ │ Vaše │ │ Klubero │
│ │ │ Appka │ │ SSO │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ 1. Klikne na "Přihlásit" │ │
│ ─────────────────────────────────────► │ │
│ │ │
│ 2. Redirect na /connect/authorize │ │
│ ◄───────────────────────────────────── │ │
│ │ │
│ 3. Přesměrování na SSO │ │
│ ──────────────────────────────────────────────────────────────────────────────► │
│ │ │
│ 4. Uživatel se autentizuje & odsouhlasí│ │
│ ◄────────────────────────────────────────────────────────────────────────────── │
│ │ │
│ 5. Redirect na callback s kódem │ │
│ ──────────────────────────────────────────────────────────────────────────────► │
│ │ │
│ │ 6. POST /connect/token (code + secret) │
│ │ ──────────────────────────────────────► │
│ │ │
│ │ 7. Vrácení tokenů │
│ │ ◄────────────────────────────────────── │
│ │ │
│ 8. Uživatel přihlášen │ │
│ ◄───────────────────────────────────── │ │
Krok 1: Sestavení autorizační URL
Sestavte URL s následujícími parametry a přesměrujte uživatele:
Base URL: https://your-sso-domain.com/connect/authorize
| Parametr | Povinný | Popis |
|---|---|---|
client_id | Ano | Client ID vaší aplikace |
redirect_uri | Ano | Kam přesměrovat po autentizaci (musí být registrované) |
response_type | Ano | Musí být code pro toto flow |
scope | Ano | Seznam požadovaných scopes oddělených mezerou (minimum: openid) |
state | Ano | Náhodný řetězec pro prevenci CSRF útoků (uložte si ho, ověřte při callbacku) |
nonce | Ne | Náhodný řetězec zahrnutý v ID tokenu (ochrana proti opakování) |
prompt | Ne | login (vynutit přihlášení), none (tiché), consent (vynutit souhlas) |
login_hint | Ne | Předvyplnění emailového pole (např. user@example.com) |
response_mode | Ne | query (výchozí), fragment, nebo form_post |
Příklad autorizační URL:
https://your-sso-domain.com/connect/authorize?\
client_id=my-app&\
redirect_uri=https%3A%2F%2Fmyapp.com%2Fcallback&\
response_type=code&\
scope=openid%20profile%20email%20offline_access&\
state=abc123xyz&\
nonce=nonce789
Krok 2: Uživatel se autentizuje
Uživateli je zobrazena přihlašovací stránka Klubero SSO, kde může:
- Zadat email a heslo
- Použít Magic Link (bez hesla)
- Přihlásit se přes externího poskytovatele (Google, Facebook, Seznam.cz)
- Dokončit dvoufaktorovou autentizaci (pokud je povolena)
Krok 3: Zpracování obrazovky souhlasu
Pokud uživatel používá vaši aplikaci poprvé (nebo je vyžadován explicitní souhlas), uvidí obrazovku souhlasu zobrazující:
- Název a logo vaší aplikace
- Požadovaná oprávnění (scopes)
- Tlačítka Povolit / Zamítnout
Pro důvěryhodné first-party aplikace může být souhlas nakonfigurován jako "implicitní" (automatický).
Krok 4: Zpracování callbacku
Po úspěšné autentizaci je uživatel přesměrován na vaši redirect_uri:
https://myapp.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=abc123xyz
Důležité
Ověřte, že parametr state odpovídá tomu, co jste odeslali v Kroku 1, abyste předešli CSRF útokům.
Chybová odpověď:
Pokud uživatel odmítne souhlas nebo nastane chyba:
https://myapp.com/callback?error=access_denied&error_description=User%20denied%20access&state=abc123xyz
Krok 5: Výměna kódu za tokeny
Odešlete POST požadavek na token endpoint:
curl -X POST https://your-sso-domain.com/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=my-app" \
-d "client_secret=my-secret" \
-d "code=SplxlOBeZQQYbYS6WxSbIA" \
-d "redirect_uri=https://myapp.com/callback"
Parametry token požadavku:
| Parametr | Povinný | Popis |
|---|---|---|
grant_type | Ano | Musí být authorization_code |
client_id | Ano | Client ID vaší aplikace |
client_secret | Ano | Client secret vaší aplikace |
code | Ano | Authorization code z callbacku |
redirect_uri | Ano | Musí přesně odpovídat původnímu požadavku |
Úspěšná odpověď:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6InJ0K2p3dCJ9...",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"scope": "openid profile email offline_access"
}
Pole odpovědi:
| Pole | Popis |
|---|---|
access_token | JWT pro autentizaci API. Vyprší za 30 minut. |
token_type | Vždy Bearer |
expires_in | Životnost tokenu v sekundách (1800 = 30 minut) |
refresh_token | Token pro získání nových access tokenů (pouze pokud byl požadován scope offline_access) |
id_token | JWT obsahující claims o identitě uživatele |
scope | Scopes, které byly uděleny (mohou se lišit od požadovaných) |
Krok 6: Použití access tokenu
Zahrňte access token v Authorization header pro API požadavky:
curl https://your-sso-domain.com/connect/userinfo \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
Zpracování chyb
Běžné chyby token endpointu:
| Chyba | HTTP Status | Příčina | Řešení |
|---|---|---|---|
invalid_request | 400 | Chybí povinný parametr | Zkontrolujte všechny povinné parametry |
invalid_client | 401 | Neplatný client_id nebo secret | Ověřte přihlašovací údaje |
invalid_grant | 400 | Kód vypršel, byl již použit nebo je neplatný | Vyžádejte si nový authorization code |
invalid_scope | 400 | Požadovaný scope není povolen | Požadujte pouze povolené scopes |