Hurtigstart: alle OIDC-biblioteker

Usher er en standard OpenID Connect-leverandør. Har språket ditt en sertifisert OIDC-klient, har du allerede alt du trenger: pek den mot miljøets discovery-dokument og bruk autorisasjonskodeflyten med PKCE.

Innstillingene

Innstilling	Verdi
Utsteder	`https://<handle>.usherid.com`
Discovery-URL	`https://<handle>.usherid.com/.well-known/openid-configuration`
Flyt	Autorisasjonskode (`response_type=code`)
PKCE	Påkrevd, `code_challenge_method=S256`
Omfang	`openid profile email offline_access`
Klientautentisering	Som oppført i `token_endpoint_auth_methods_supported`

Miljøets kortnavn står i Usher Console, ved siden av utstederen. Utviklingsmiljøer får et tilfeldig et, som wise-otter-42; produksjonsmiljøer har kortnavnet du valgte. Et produksjonsmiljø kan i stedet ligge på ditt eget domene, som login.acme.com: da er det utstederen, når du har pekt domenet mot Usher med en CNAME-post.

Les discovery-dokumentet

Alle endepunktene og nøklene klienten din trenger, står her. La biblioteket ditt lese det i stedet for å kopiere URL-er inn i koden.

Terminal

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

Svar (forkortet)

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

Flyten

Send personen til autorisasjonsendepunktet

Lag en tilfeldig PKCE-verifikator og ta vare på den, sammen med en tilfeldig state, et sted bare denne nettleserens økt når (en kortlivet httpOnly-informasjonskapsel fungerer godt). Send deretter videre med response_type=code, din client_id og redirect_uri, omfangene ovenfor, state og S256-code_challenge for verifikatoren din.

La dem logge på

Lobbyen tar det herfra: den viser navnet på appen din, tilbyr påloggingsmetodene miljøet ditt tillater, og ber om samtykke første gang.

Sjekk callback-en

Usher sender videre til din redirect_uri med code og state. Avvis svaret med mindre state stemmer med den du lagret. Koden er til engangsbruk og varer i fem minutter.

Bytt koden mot tokener

Fra serveren din sender du koden og PKCE-verifikatoren til token-endepunktet:

Tokenforespørsel

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"

Valider ID-tokenet

Sjekk signaturen mot nøklene på jwks_uri, og at iss er utstederen din, aud er klient-ID-en din og exp ligger fram i tid. Biblioteket ditt gjør dette for deg; sørg for at det ikke er slått av.

I Node.js

openid-client gjør alt dette, også valideringen:

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

I andre språk

Disse mye brukte bibliotekene snakker alle standard OpenID Connect og fungerer med Usher uten noe Usher-spesifikt:

Språk	Bibliotek
Python	Authlib
Go	`coreos/go-oidc` med `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`

Forbli pålogget

Med omfanget offline_access inneholder tokensvaret et oppdateringstoken. Bruk det med grant_type=refresh_token for å få et nytt tilgangstoken når det gamle utløper. Oppdateringstokener roteres: hver bruk gir et nytt, og det gamle slutter å virke.

Logge ut

Tøm din egen økt først, og send deretter videre til end_session_endpoint med post_logout_redirect_uri (og id_token_hint hvis du har det), så Lobbyen også glemmer personen.