OAuth2 Dokumentace pro vývojáře

Komplexní návod pro integraci OAuth2 autentizace kdo.je do vaší aplikace

Úvod

kdo.je poskytuje OAuth 2.0 autentizační server, který umožňuje uživatelům přihlásit se do vaší aplikace pomocí jejich kdo.je účtu. Podporujeme standardní OAuth 2.0 Authorization Code Flow s volitelnou podporou PKCE.

Základní URL: https://www.kdo.je

Registrace aplikace

Před začátkem integrace musíte zaregistrovat vaši aplikaci v kdo.je systému.

  1. Přihlaste se do svého kdo.je účtu
  2. Přejděte do sekce "Moje OAuth aplikace" (/MyApps)
  3. Klikněte na "Vytvořit novou aplikaci"
  4. Vyplňte informace o aplikaci:
    • Název aplikace - zobrazí se uživatelům při autorizaci
    • Popis - krátký popis vaší aplikace
    • Logo URL - odkaz na logo (volitelné)
    • URLs - webová stránka, zásady ochrany, podmínky použití (volitelné)
    • Redirect URIs - URL(s), kam bude uživatel přesměrován po autorizaci
    • Scopes - požadovaná oprávnění (openid je povinné, můžete přidat profile, email, offline_access)
    • Typ klienta - Confidential (pro server aplikace s client secret) nebo Public (pro SPA/mobilní s PKCE)
  5. Po vytvoření obdržíte client_id a případně client_secret (pro Confidential)
DŮLEŽITÉ: client_secret se zobrazí pouze jednou při vytvoření aplikace! Uložte si ho na bezpečné místo. Pokud ho ztratíte, musíte vytvořit novou aplikaci. Nikdy nesdílejte client secret veřejně nebo v klientském kódu!
Správa aplikací: Své OAuth aplikace můžete spravovat na stránce /MyApps, kde můžete upravovat nastavení, zobrazit Client ID a deaktivovat aplikace.

API Endpointy

Authorization Endpoint

GET https://www.kdo.je/oauth/authorize

Endpoint pro zahájení autorizačního procesu. Uživatel bude přesměrován na přihlašovací stránku kdo.je.

Token Endpoint

POST https://www.kdo.je/oauth/token

Endpoint pro výměnu authorization code za access token nebo obnovení tokenu pomocí refresh token.

UserInfo Endpoint

GET https://www.kdo.je/oauth/userinfo

Endpoint pro získání informací o uživateli (vyžaduje platný access token).

Revoke Endpoint

POST https://www.kdo.je/oauth/revoke

Endpoint pro zneplatnění access nebo refresh tokenu.

OpenID Connect Discovery Endpoint

GET https://www.kdo.je/.well-known/openid-configuration

Endpoint pro automatické zjištění konfigurace OAuth serveru. Vrací metadata o všech dostupných endpointech a podporovaných funkcích.

JSON Web Key Set (JWKS) Endpoint

GET https://www.kdo.je/.well-known/jwks.json

Endpoint pro získání veřejných RSA klíčů pro validaci JWT tokenů. Server používá RS256 (asymetrické podepisování) pro maximální bezpečnost.

Tip: Použitím discovery endpointu můžete zjednodušit konfiguraci OAuth knihoven. Více informací naleznete na stránce OAuth2 Knihovny a SDK.

Authorization Code Flow

Standardní OAuth 2.0 flow pro webové aplikace s backend serverem.

Krok 1: Přesměrování na authorization endpoint

Přesměrujte uživatele na authorization endpoint s následujícími parametry:

Parametr Povinný Popis
response_type Ano Musí být code
client_id Ano Vaše Client ID z registrace
redirect_uri Ano URL pro přesměrování po autorizaci (musí odpovídat registraci)
scope Ne Mezerou oddělený seznam scope (výchozí: openid profile)
state Ne Náhodný řetězec pro prevenci CSRF útoků (doporučeno)
code_challenge Ne PKCE challenge (viz sekce PKCE)
code_challenge_method Ne Metoda PKCE: S256 nebo plain
Příklad URL:
GET https://www.kdo.je/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://vase-aplikace.cz/callback&scope=openid%20profile%20email&state=random_state_string

Krok 2: Uživatel autorizuje aplikaci

Uživatel se přihlásí (pokud ještě není) a potvrdí, že vaší aplikaci uděluje přístup k požadovaným údajům.

Krok 3: Přesměrování zpět s authorization code

Po úspěšné autorizaci bude uživatel přesměrován zpět na vaši redirect_uri s parametry:

GET https://vase-aplikace.cz/callback?code=AUTHORIZATION_CODE&state=random_state_string

Krok 4: Výměna code za access token

Na serveru proveďte POST request na token endpoint:

POST https://www.kdo.je/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://vase-aplikace.cz/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Odpověď:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_string",
  "scope": "openid profile email"
}

PKCE (Proof Key for Code Exchange)

PKCE je doporučené bezpečnostní rozšíření OAuth 2.0, které chrání před interceptem authorization code. Je povinné pro public clients (mobilní/SPA aplikace) a doporučené pro všechny typy aplikací.

Implementace PKCE:

1. Vygenerujte code_verifier

Náhodný řetězec o délce 43-128 znaků (doporučeno 128):

// C# příklad
var codeVerifier = Convert.ToBase64String(
  RandomNumberGenerator.GetBytes(96)
).TrimEnd('=').Replace('+', '-').Replace('/', '_');
2. Vypočítejte code_challenge

SHA256 hash code_verifier, zakódovaný jako base64url:

// C# příklad
using var sha256 = SHA256.Create();
var challengeBytes = sha256.ComputeHash(
  Encoding.UTF8.GetBytes(codeVerifier)
);
var codeChallenge = Convert.ToBase64String(challengeBytes)
  .TrimEnd('=').Replace('+', '-').Replace('/', '_');
3. Přidejte PKCE parametry do authorization request
GET https://www.kdo.je/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://vase-aplikace.cz/callback
  &scope=openid%20profile
  &state=random_state
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
4. Pošlete code_verifier při výměně tokenu
POST https://www.kdo.je/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://vase-aplikace.cz/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=CODE_VERIFIER
Public clients: Při registraci aplikace jako "Public" (SPA, mobilní aplikace) není generován client_secret. V tomto případě MUSÍTE použít PKCE pro zabezpečení. Pro "Confidential" klienty (server aplikace) je PKCE volitelné, ale doporučené.

Refresh Token

Když access token vyprší, můžete použít refresh token k získání nového access tokenu bez nutnosti opětovného přihlášení uživatele.

POST https://www.kdo.je/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Odpověď:

{
  "access_token": "new_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "new_refresh_token"
}

Získání informací o uživateli

S platným access tokenem můžete získat informace o uživateli podle udělených scopes:

GET https://www.kdo.je/oauth/userinfo
Authorization: Bearer YOUR_ACCESS_TOKEN

Odpověď (závisí na udělených scopes):

{
  "sub": "123",
  "name": "Jan Novák",             // pokud scope obsahuje "profile"
  "given_name": "Jan",           // pokud scope obsahuje "profile"
  "family_name": "Novák",         // pokud scope obsahuje "profile"
  "picture": "https://...",      // pokud scope obsahuje "profile"
  "email": "jan.novak@example.com", // pokud scope obsahuje "email"
  "email_verified": true,        // pokud scope obsahuje "email"
  "phone_number": "+420 123 456 789", // pokud scope obsahuje "phone"
  "phone_number_verified": false    // pokud scope obsahuje "phone"
}
Poznámka: Endpoint vrací pouze data podle scopes, které uživatel schválil při autorizaci. Pokud nezahrnete určitý scope v požadavku, odpovídající data nebudou vrácena.

Dostupné Scopes

Scope Povinný Popis Vrácené údaje (UserInfo)
openid Ano Základní OpenID Connect identifikace sub (user ID)
profile Ne Základní profilové informace name, given_name, family_name, picture
email Ne E-mailová adresa uživatele email, email_verified
phone Ne Telefonní číslo uživatele phone_number, phone_number_verified
offline_access Ne Přístup k refresh tokenu pro obnovení bez přihlášení Vrací refresh_token v token response
Poznámka: Scope openid je vždy povinný a automaticky zahrnut. Další scopes můžete zvolit při registraci aplikace v sekci /MyApps.

Příklady kódu

Doporučení: Pro snadnější integraci doporučujeme použít standardní OAuth 2.0/OpenID Connect knihovny. Podrobný přehled doporučených knihoven pro různé platformy naleznete na stránce OAuth2 Knihovny a SDK.

ASP.NET Core (C#)

// Program.cs nebo Startup.cs
builder.Services.AddAuthentication(options =>
{
  options.DefaultScheme = "Cookies";
  options.DefaultChallengeScheme = "KdoJe";
})
.AddCookie("Cookies")
.AddOpenIdConnect("KdoJe", options =>
{
  options.Authority = "https://www.kdo.je";
  options.ClientId = "YOUR_CLIENT_ID";
  options.ClientSecret = "YOUR_CLIENT_SECRET";
  options.ResponseType = "code";
  options.SaveTokens = true;
  options.GetClaimsFromUserInfoEndpoint = true;
  options.Scope.Add("openid");
  options.Scope.Add("profile");
  options.Scope.Add("email");
  options.UsePkce = true; // Zapnout PKCE
});

Node.js (Passport.js)

const passport = require('passport');
const OAuth2Strategy = require('passport-oauth2');

passport.use('kdoje', new OAuth2Strategy({
  authorizationURL: 'https://www.kdo.je/oauth/authorize',
  tokenURL: 'https://www.kdo.je/oauth/token',
  clientID: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  callbackURL: 'https://vase-aplikace.cz/auth/callback'
},
function(accessToken, refreshToken, profile, cb) {
  // Získání uživatelských dat
  return cb(null, profile);
}));

Python (Authlib)

from authlib.integrations.flask_client import OAuth

oauth = OAuth(app)
oauth.register(
  name='kdoje',
  client_id='YOUR_CLIENT_ID',
  client_secret='YOUR_CLIENT_SECRET',
  authorize_url='https://www.kdo.je/oauth/authorize',
  access_token_url='https://www.kdo.je/oauth/token',
  api_base_url='https://www.kdo.je',
  client_kwargs={'scope': 'openid profile email'}
)

PHP

use League\OAuth2\Client\Provider\GenericProvider;

$provider = new GenericProvider([
  'clientId' => 'YOUR_CLIENT_ID',
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'redirectUri' => 'https://vase-aplikace.cz/callback',
  'urlAuthorize' => 'https://www.kdo.je/oauth/authorize',
  'urlAccessToken' => 'https://www.kdo.je/oauth/token',
  'urlResourceOwnerDetails' => 'https://www.kdo.je/api/auth/userinfo'
]);

Chybové stavy

API vrací standardní OAuth 2.0 chybové kódy:

Error kód Popis
invalid_request Chybějící nebo neplatný parametr
invalid_client Neplatné nebo chybějící client credentials
invalid_grant Neplatný authorization code nebo refresh token
unauthorized_client Client nemá oprávnění k tomuto grant typu
unsupported_grant_type Nepodporovaný grant type
invalid_scope Neplatný nebo nepodporovaný scope
access_denied Uživatel zamítl autorizaci

Příklad chybové odpovědi:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: redirect_uri"
}

Správa oprávnění a aplikací

Pro vývojáře - Správa OAuth aplikací

Své OAuth aplikace můžete spravovat na stránce /MyApps:

  • Zobrazení seznamu všech vašich aplikací
  • Úprava nastavení aplikace (název, popis, redirect URIs, scopes)
  • Deaktivace/aktivace aplikace
  • Zobrazení Client ID (Client Secret se zobrazí pouze při vytvoření)
  • Smazání aplikace (pozor: zruší všechny aktivní tokeny!)

Pro uživatele - Správa autorizovaných aplikací

Uživatelé mohou spravovat aplikace s přístupem k jejich účtu na /Account/AuthorizedApps:

  • Zobrazení seznamu všech aplikací, kterým byl udělen přístup
  • Přehled udělených oprávnění (scopes) pro každou aplikaci
  • Datum autorizace a posledního použití
  • Počet aktivních tokenů
  • Možnost odebrat přístup jakékoliv aplikaci (revokuje všechny tokeny)
Bezpečnost: Uživatelé mají plnou kontrolu nad tím, které aplikace mají přístup k jejich účtu. Kdykoliv mohou odebrat přístup jakékoliv aplikaci bez nutnosti kontaktovat vývojáře.
Potřebujete pomoc?

Užitečné odkazy:

Pokud máte jakékoli dotazy nebo problémy s integrací, kontaktujte nás na support@kdoje.cz