Snabbstart: valfritt OIDC-bibliotek

Usher är en vanlig OpenID Connect-leverantör. Om ditt språk har en certifierad OIDC-klient har du redan allt du behöver: peka den mot din miljös discovery-dokument och använd auktoriseringskodflödet med PKCE.

Inställningarna

Inställning	Värde
Utfärdare	`https://<handle>.usherid.com`
Discovery-URL	`https://<handle>.usherid.com/.well-known/openid-configuration`
Flöde	Auktoriseringskod (`response_type=code`)
PKCE	Krävs, `code_challenge_method=S256`
Scopes	`openid profile email offline_access`
Klientautentisering	Enligt `token_endpoint_auth_methods_supported`

Din miljös handle finns i Usher Console, bredvid dess utfärdare. Utvecklingsmiljöer får en slumpmässig handle, till exempel wise-otter-42; produktionsmiljöer har den handle du valde. En produktionsmiljö kan i stället finnas på din egen domän, till exempel login.acme.com: då är det dess utfärdare, när du har pekat domänen mot Usher med en CNAME-post.

Läs discovery-dokumentet

Alla slutpunkter och nycklar som din klient behöver finns här. Låt ditt bibliotek läsa dokumentet i stället för att kopiera URL:er in i koden.

Terminal

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

Svar (förkortat)

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

Flödet

Skicka personen till auktoriseringsslutpunkten

Skapa en slumpmässig PKCE-verifierare och spara den, tillsammans med ett slumpmässigt state, någonstans som bara den här webbläsarens session når (en kortlivad httpOnly-cookie fungerar bra). Omdirigera sedan med response_type=code, ditt client_id och din redirect_uri, scopes enligt ovan, state och S256-code_challenge för din verifierare.

Låt personen logga in

Lobbyn tar över härifrån: den nämner din app, erbjuder de inloggningsmetoder som din miljö tillåter och ber om samtycke första gången.

Kontrollera återanropet

Usher omdirigerar till din redirect_uri med code och state. Avvisa svaret om inte state stämmer med det du sparade. Koden kan bara användas en gång och gäller i fem minuter.

Byt koden mot tokens

Skicka koden och PKCE-verifieraren från din server till tokenslutpunkten:

Tokenförfrågan

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"

Validera ID-tokenen

Kontrollera dess signatur mot nycklarna på jwks_uri, och att iss är din utfärdare, att aud är ditt klient-ID och att exp ligger i framtiden. Ditt bibliotek gör detta åt dig; se till att det inte är avstängt.

I Node.js

openid-client gör allt ovan, inklusive 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 andra språk

Alla de här välanvända biblioteken talar vanlig OpenID Connect och fungerar med Usher utan något Usher-specifikt:

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`

Förbli inloggad

Med scopet offline_access innehåller tokensvaret en uppdateringstoken. Använd den med grant_type=refresh_token för att hämta en ny åtkomsttoken när den gamla går ut. Uppdateringstokens roteras: varje användning ger en ny, och den gamla slutar fungera.

Logga ut

Rensa först din egen session och omdirigera sedan till end_session_endpoint med post_logout_redirect_uri (och id_token_hint om du har den), så att Lobbyn också glömmer bort personen.