Pika-aloitus: mikä tahansa OIDC-kirjasto

Usher on standardi OpenID Connect -palveluntarjoaja. Jos kielelläsi on sertifioitu OIDC-asiakas, sinulla on jo kaikki tarvittava: osoita se ympäristösi discovery-dokumenttiin ja käytä valtuutuskoodikulkua PKCE:llä.

Asetukset

Asetus	Arvo
Myöntäjä	`https://<handle>.usherid.com`
Discovery-URL	`https://<handle>.usherid.com/.well-known/openid-configuration`
Kulku	Valtuutuskoodi (`response_type=code`)
PKCE	Pakollinen, `code_challenge_method=S256`
Käyttöalueet	`openid profile email offline_access`
Asiakkaan todennus	Kuten `token_endpoint_auth_methods_supported` luettelee

Ympäristösi lyhytnimi näkyy Usher Consolessa sen myöntäjän vieressä. Kehitysympäristöt saavat satunnaisen lyhytnimen, kuten wise-otter-42; tuotantoympäristöillä on valitsemasi lyhytnimi. Tuotantoympäristö voi myös toimia omassa verkkotunnuksessasi, kuten login.acme.com: silloin se on ympäristön myöntäjä, kun olet ohjannut verkkotunnuksen Usheriin CNAME-tietueella.

Lue discovery-dokumentti

Siihen on lueteltu kaikki päätepisteet ja avaimet, joita asiakkaasi tarvitsee. Anna kirjastosi lukea se sen sijaan, että kopioisit URL-osoitteita koodiisi.

Pääte

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

Vastaus (lyhennetty)

{
  "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"]
}

Kulku

Lähetä ihminen valtuutuspäätepisteeseen

Luo satunnainen PKCE-todentaja ja säilytä se satunnaisen state-arvon kanssa paikassa, johon vain tämän selaimen istunto pääsee (lyhytikäinen httpOnly-eväste toimii hyvin). Ohjaa sitten eteenpäin: mukaan response_type=code, oma client_id ja redirect_uri, yllä mainitut käyttöalueet, state ja todentajasi S256-muotoinen code_challenge.

Anna hänen kirjautua

Lobby hoitaa asian tästä eteenpäin: se nimeää sovelluksesi, tarjoaa ympäristösi sallimat kirjautumistavat ja pyytää suostumusta ensimmäisellä kerralla.

Tarkista takaisinkutsu

Usher ohjaa redirect_uri-osoitteeseesi parametrein code ja state. Hylkää vastaus, ellei state vastaa tallentamaasi arvoa. Koodi on kertakäyttöinen ja voimassa viisi minuuttia.

Vaihda koodi tunnuksiin

Lähetä palvelimeltasi koodi ja PKCE-todentaja tunnuspäätepisteeseen:

Tunnuspyyntö

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"

Validoi ID-tunnus

Tarkista sen allekirjoitus jwks_uri-osoitteen avaimia vasten sekä se, että iss on myöntäjäsi, aud on asiakastunnuksesi ja exp on tulevaisuudessa. Kirjastosi tekee tämän puolestasi; varmista, ettei sitä ole kytketty pois päältä.

Node.js:ssä

Kirjasto openid-client tekee kaiken yllä olevan, validointi mukaan lukien:

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()!

Muilla kielillä

Nämä laajasti käytetyt kirjastot puhuvat kaikki standardia OpenID Connectia ja toimivat Usherin kanssa ilman mitään Usher-kohtaista:

Kieli	Kirjasto
Python	Authlib
Go	`coreos/go-oidc` ja `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`

Kirjautuneena pysyminen

Kun käyttöalue offline_access on mukana, tunnusvastaus sisältää päivitystunnuksen. Hae sillä grant_type=refresh_token-pyynnöllä uusi käyttöoikeustunnus, kun vanha vanhenee. Päivitystunnukset vaihtuvat: jokainen käyttö palauttaa uuden, ja vanha lakkaa toimimasta.

Uloskirjautuminen

Tyhjennä ensin oma istuntosi ja ohjaa sitten end_session_endpoint-päätepisteeseen parametrilla post_logout_redirect_uri (ja id_token_hint, jos se on sinulla), jotta Lobbykin unohtaa ihmisen.