AuthService.hu
Fejlesztői Dokumentáció

Áttekintés

Az AuthService központi Identity Providerként az alkalmazásod helyett végzi a felhasználó hitelesítését. Az alkalmazás nem kapja meg a felhasználó jelszavát: a böngésző az AuthService hitelesítési felületére kerül, majd sikeres azonosítás után egy rövid életű authorization code-dal tér vissza a regisztrált callback URL-re.

Gyors kezdés

1. Regisztráld a szervezetedet és az alkalmazásodat. A Console-ban létrejön a kliensazonosító és megadhatók a redirect URI-k.
2. Állíts be pontos redirect URI-t. Az AuthService csak regisztrált URI-ra ad vissza authorization code-ot.
3. Generálj PKCE verifier/challenge párt. Használj S256 módszert.
4. Irányítsd a böngészőt az authorization endpointra.
5. A callbackben ellenőrizd a state-et, majd szerveroldalon cseréld a code-ot tokenekre.
6. Ellenőrizd az ID Token aláírását és claim-jeit a JWKS alapján.

Kliens regisztráció

A partnerfiók és az első OIDC kliens az AuthService partnerregisztrációján hozható létre. A klienshez külön szabályozható a redirect URI, az engedélyezett scope-k, a kliens típusa és a végfelhasználói önregisztráció.

Discovery és JWKS

Az integráció során ne hardcode-old feleslegesen az endpointokat: az OIDC Discovery dokumentum géppel olvasható módon közli az aktuális szolgáltatói metaadatokat.

Authorization endpoint

A böngészőt erre az endpointra kell irányítani. Az AuthService jelenleg a code response type-ot támogatja.

GET /oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.hu%2Fauth%2Fcallback&
  response_type=code&
  scope=openid%20profile%20email&
  state=RANDOM_STATE&
  nonce=RANDOM_NONCE&
  code_challenge=PKCE_CHALLENGE&
  code_challenge_method=S256

PKCE – S256

A kliens minden új authorization kéréshez generáljon egy nagy entrópiájú code_verifier értéket. Ebből SHA-256 hash + base64url kódolással készül a code_challenge. A verifier csak a token kérésben kerül elküldésre.

code_challenge = BASE64URL(
    SHA256(code_verifier)
)

Authorization code → tokenek

A callbackben kapott code egyszer használható. A token endpoint application/x-www-form-urlencoded kérést vár.

curl -X POST 'https://oidc.authservice.hu/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://app.example.hu/auth/callback' \
  --data-urlencode 'code_verifier=ORIGINAL_CODE_VERIFIER'

Válasz

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid profile email",
  "id_token": "eyJ..."
}

Az expires_in tényleges értékét mindig a tokenválaszból kezeld; ne építs fix TTL-re.

UserInfo

curl 'https://oidc.authservice.hu/oauth2/userinfo' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

A visszaadott mezők a jóváhagyott scope-októl függenek. A sub az AuthService által kiadott felhasználói subject.

Refresh token és offline_access

Refresh token csak akkor kerül kiadásra az authorization code cseréjekor, ha a kérés tartalmazta az offline_access scope-ot. Az AuthService refresh-token rotációt alkalmaz.

curl -X POST 'https://oidc.authservice.hu/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=REFRESH_TOKEN'

Kijelentkezés

Az AuthService OIDC logout folyamatot biztosít, és a Discovery dokumentumban end_session_endpoint értékként publikálja. Az alkalmazás a kijelentkezési folyamatot ezen az endpointon indítsa.

Token visszavonás

Ha egy hozzáférést vagy refresh tokent már nem kívánsz használni, a kliens a revocation endpointon kezdeményezheti a visszavonást.

Endpoint referencia

Scope-ok és UserInfo claim-ek

Hibakezelés

Az OAuth/OIDC hibákat a protokoll szerinti error mező alapján kezeld. A felhasználónak ne jeleníts meg nyers tokeneket, secretet vagy belső stack trace-t.

Biztonsági követelmények