Rýchly štart: akákoľvek knižnica OIDC

Usher je štandardný poskytovateľ OpenID Connect. Ak má váš jazyk certifikovaného klienta OIDC, máte všetko, čo potrebujete: nasmerujte ho na dokument zisťovania svojho prostredia a použite tok s autorizačným kódom a PKCE.

Nastavenia

Nastavenie	Hodnota
Vydavateľ	`https://<handle>.usherid.com`
URL zisťovania	`https://<handle>.usherid.com/.well-known/openid-configuration`
Tok	Autorizačný kód (`response_type=code`)
PKCE	Povinné, `code_challenge_method=S256`
Rozsahy	`openid profile email offline_access`
Overenie klienta	Podľa `token_endpoint_auth_methods_supported`

Označenie svojho prostredia nájdete v Usher Console vedľa jeho vydavateľa. Vývojové prostredia dostanú náhodné označenie, napríklad wise-otter-42; produkčné prostredia majú označenie, ktoré ste si zvolili. Produkčné prostredie môže namiesto toho sídliť na vašej vlastnej doméne, napríklad login.acme.com: tá je potom jeho vydavateľom, keď doménu nasmerujete na Usher záznamom CNAME.

Prečítajte si dokument zisťovania

Je v ňom uvedený každý koncový bod a kľúč, ktorý váš klient potrebuje. Nechajte ho prečítať knižnicu, namiesto toho, aby ste URL kopírovali do kódu.

Terminál

curl -s https://acme.usherid.com/.well-known/openid-configuration | jq

Odpoveď (skrátená)

{
  "issuer": "https://acme.usherid.com",
  "authorization_endpoint": "https://acme.usherid.com/api/auth/oauth2/authorize",
  "token_endpoint": "https://acme.usherid.com/api/auth/oauth2/token",
  "userinfo_endpoint": "https://acme.usherid.com/api/auth/oauth2/userinfo",
  "jwks_uri": "https://acme.usherid.com/api/auth/jwks",
  "introspection_endpoint": "https://acme.usherid.com/api/auth/oauth2/introspect",
  "revocation_endpoint": "https://acme.usherid.com/api/auth/oauth2/revoke",
  "end_session_endpoint": "https://acme.usherid.com/api/auth/oauth2/end-session",
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "code_challenge_methods_supported": ["S256"]
}

Priebeh

Pošlite človeka na autorizačný koncový bod

Vytvorte náhodný overovač PKCE a uložte ho spolu s náhodnou hodnotou state tam, kam má prístup len relácia tohto prehliadača (dobre poslúži krátko platný súbor cookie httpOnly). Potom presmerujte s response_type=code, svojím client_id a redirect_uri, rozsahmi uvedenými vyššie, hodnotou state a hodnotou code_challenge S256 vášho overovača.

Nechajte ho prihlásiť sa

Odtiaľto preberá prácu Lobby: uvedie vašu aplikáciu, ponúkne metódy prihlásenia, ktoré vaše prostredie povoľuje, a pri prvom prihlásení požiada o súhlas.

Skontrolujte návrat (callback)

Usher presmeruje na vaše redirect_uri s code a state. Odpoveď odmietnite, ak sa state nezhoduje s hodnotou, ktorú ste uložili. Kód je na jedno použitie a platí päť minút.

Vymeňte kód za tokeny

Zo svojho servera pošlite kód a overovač PKCE na koncový bod tokenu:

Požiadavka na token

curl -s -X POST https://acme.usherid.com/api/auth/oauth2/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code="$CODE" \
-d redirect_uri=https://app.acme.example/callback \
-d code_verifier="$CODE_VERIFIER"

Overte token ID

Skontrolujte jeho podpis voči kľúčom na jwks_uri a to, že iss je váš vydavateľ, aud je ID vášho klienta a exp je v budúcnosti. Vaša knižnica to urobí za vás; uistite sa, že to nemá vypnuté.

V Node.js

openid-client urobí všetko uvedené vyššie vrátane overenia:

openid-client

import * as client from 'openid-client'

// discovery: every endpoint and key comes from the issuer
const config = await client.discovery(
  new URL('https://acme.usherid.com'),
  process.env.USHER_CLIENT_ID!,
  process.env.USHER_CLIENT_SECRET!,
)

// 1. send them to the Lobby, with PKCE (S256) and a state to check later
const codeVerifier = client.randomPKCECodeVerifier()
const state = client.randomState()
const url = client.buildAuthorizationUrl(config, {
  redirect_uri: 'https://app.acme.example/callback',
  scope: 'openid profile email offline_access',
  code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),
  code_challenge_method: 'S256',
  state,
})
// keep codeVerifier and state in a short-lived httpOnly cookie, then redirect to url

// 2. back at /callback: swap the code for tokens
const tokens = await client.authorizationCodeGrant(config, new URL(request.url), {
  pkceCodeVerifier: codeVerifier,
  expectedState: state,
})
const { sub, email, name } = tokens.claims()!

V iných jazykoch

Všetky tieto rozšírené knižnice hovoria štandardným OpenID Connect a fungujú s Usher bez čohokoľvek špecifického pre Usher:

Jazyk	Knižnica
Python	Authlib
Go	`coreos/go-oidc` s `golang.org/x/oauth2`
Java	Spring Security OAuth 2.0 Client
.NET	`Microsoft.AspNetCore.Authentication.OpenIdConnect`
Ruby	`omniauth_openid_connect`
PHP	`jumbojett/openid-connect-php`

Trvalé prihlásenie

S rozsahom offline_access obsahuje odpoveď s tokenmi aj obnovovací token. Použite ho s grant_type=refresh_token na získanie nového prístupového tokenu, keď starý vyprší. Obnovovacie tokeny sa vymieňajú: každé použitie vráti nový a starý prestane fungovať.

Odhlásenie

Najprv vymažte vlastnú reláciu a potom presmerujte na end_session_endpoint s post_logout_redirect_uri (a id_token_hint, ak ho máte), aby na človeka zabudlo aj Lobby.