Hitri začetek: katera koli knjižnica OIDC

Usher je standardni ponudnik OpenID Connect. Če ima vaš jezik certificiranega odjemalca OIDC, že imate vse, kar potrebujete: usmerite ga na dokument za odkrivanje svojega okolja in uporabite potek z avtorizacijsko kodo in PKCE.

Nastavitve

Nastavitev	Vrednost
Izdajatelj	`https://<handle>.usherid.com`
URL za odkrivanje	`https://<handle>.usherid.com/.well-known/openid-configuration`
Potek	Avtorizacijska koda (`response_type=code`)
PKCE	Obvezno, `code_challenge_method=S256`
Obsegi	`openid profile email offline_access`
Preverjanje pristnosti odjemalca	Kot je navedeno v `token_endpoint_auth_methods_supported`

Oznaka vašega okolja je v Usher Console, ob njegovem izdajatelju. Razvojna okolja dobijo naključno, na primer wise-otter-42; produkcijska okolja imajo oznako, ki ste jo izbrali. Produkcijsko okolje je lahko namesto tega na vaši lastni domeni, na primer login.acme.com: ta je potem njegov izdajatelj, ko domeno z zapisom CNAME usmerite na Usher.

Preberite dokument za odkrivanje

Tukaj je navedena vsaka končna točka in vsak ključ, ki ga potrebuje vaš odjemalec. Naj ga prebere vaša knjižnica, namesto da URL-je kopirate v svojo kodo.

Terminal

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

Odgovor (skrajšano)

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

Potek

Pošljite osebo na avtorizacijsko končno točko

Ustvarite naključni preverjevalnik PKCE in ga skupaj z naključnim state shranite tam, kamor seže samo seja tega brskalnika (dobro deluje kratkotrajen piškotek httpOnly). Nato preusmerite z response_type=code, svojim client_id in redirect_uri, zgornjimi obsegi, state in code_challenge S256 svojega preverjevalnika.

Naj se prijavi

Od tu naprej prevzame Lobby: imenuje vašo aplikacijo, ponudi načine prijave, ki jih vaše okolje dovoljuje, in prvič zaprosi za privolitev.

Preverite povratni klic

Usher preusmeri na vaš redirect_uri s code in state. Odgovor zavrnite, razen če se state ujema s tistim, ki ste ga shranili. Koda je za enkratno uporabo in velja pet minut.

Zamenjajte kodo za žetone

S svojega strežnika pošljite kodo in preverjevalnik PKCE na končno točko za žetone:

Zahteva za žeton

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"

Preverite žeton ID

Preverite njegov podpis s ključi na jwks_uri ter da je iss vaš izdajatelj, aud vaš ID odjemalca in exp v prihodnosti. Vaša knjižnica to naredi namesto vas; prepričajte se, da ni izklopljeno.

V Node.js

openid-client naredi vse zgoraj navedeno, vključno s preverjanjem:

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 drugih jezikih

Vse te razširjene knjižnice govorijo standardni OpenID Connect in delujejo z Usherjem brez česar koli, kar bi bilo značilno za Usher:

Jezik	Knjižnica
Python	Authlib
Go	`coreos/go-oidc` z `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`

Ohranjanje prijave

Z obsegom offline_access odgovor z žetoni vključuje žeton za osvežitev. Uporabite ga z grant_type=refresh_token, da dobite nov žeton za dostop, ko staremu poteče veljavnost. Žetoni za osvežitev se menjajo: vsaka uporaba vrne novega, stari pa preneha delovati.

Odjava

Najprej počistite svojo sejo, nato preusmerite na end_session_endpoint s post_logout_redirect_uri (in id_token_hint, če ga imate), da osebo pozabi tudi Lobby.