Greita pradžia: bet kuri OIDC biblioteka

Usher yra standartinis OpenID Connect teikėjas. Jei jūsų kalba turi sertifikuotą OIDC klientą, jau turite viską, ko reikia: nukreipkite jį į savo aplinkos aptikimo dokumentą ir naudokite autorizacijos kodo srautą su PKCE.

Nustatymai

Nustatymas	Reikšmė
Išdavėjas	`https://<handle>.usherid.com`
Aptikimo URL	`https://<handle>.usherid.com/.well-known/openid-configuration`
Srautas	Autorizacijos kodas (`response_type=code`)
PKCE	Privaloma, `code_challenge_method=S256`
Aprėptys	`openid profile email offline_access`
Kliento autentifikavimas	Kaip nurodyta `token_endpoint_auth_methods_supported`

Jūsų aplinkos identifikatorius rodomas Usher Console, šalia jos išdavėjo. Kūrimo aplinkos gauna atsitiktinį, pavyzdžiui, wise-otter-42; produkcinės aplinkos turi jūsų pasirinktą identifikatorių. Produkcinė aplinka vietoj to gali veikti jūsų pačių domene, pavyzdžiui, login.acme.com: tada jis ir yra jos išdavėjas, kai CNAME įrašu nukreipiate domeną į Usher.

Perskaitykite aptikimo dokumentą

Čia išvardyti visi galiniai taškai ir raktai, kurių reikia jūsų klientui. Leiskite bibliotekai jį perskaityti, užuot kopijavę URL į savo kodą.

Terminalas

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

Atsakymas (sutrumpintas)

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

Srautas

Nusiųskite žmogų į autorizacijos galinį tašką

Sukurkite atsitiktinį PKCE tikrintuvą ir išsaugokite jį kartu su atsitiktine state reikšme ten, kur gali pasiekti tik šios naršyklės sesija (puikiai tinka trumpalaikis httpOnly slapukas). Tada nukreipkite su response_type=code, savo client_id ir redirect_uri, aukščiau nurodytomis aprėptimis, state ir savo tikrintuvo S256 code_challenge.

Leiskite žmogui prisijungti

Toliau darbą perima Lobby: jis nurodo jūsų programą, siūlo jūsų aplinkos leidžiamus prisijungimo būdus ir pirmą kartą paprašo sutikimo.

Patikrinkite grįžtamąjį iškvietimą

Usher nukreipia į jūsų redirect_uri su code ir state. Atmeskite atsakymą, jei state nesutampa su išsaugotąja. Kodas vienkartinis ir galioja penkias minutes.

Iškeiskite kodą į žetonus

Iš savo serverio nusiųskite kodą ir PKCE tikrintuvą į žetonų galinį tašką:

Žetono užklausa

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"

Patikrinkite ID žetoną

Patikrinkite jo parašą pagal raktus, esančius jwks_uri, ir ar iss yra jūsų išdavėjas, aud – jūsų kliento ID, o exp – ateityje. Jūsų biblioteka tai padaro už jus; įsitikinkite, kad tai neišjungta.

Node.js

openid-client atlieka visa tai, kas aprašyta aukščiau, įskaitant patikrinimą:

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

Kitomis kalbomis

Šios plačiai naudojamos bibliotekos kalba standartiniu OpenID Connect ir veikia su Usher be jokių specifinių Usher dalykų:

Kalba	Biblioteka
Python	Authlib
Go	`coreos/go-oidc` su `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`

Likti prisijungusiam

Su aprėptimi offline_access žetonų atsakyme yra atnaujinimo žetonas. Naudokite jį su grant_type=refresh_token, kad gautumėte naują prieigos žetoną, kai senasis nustoja galioti. Atnaujinimo žetonai keičiami: kiekvienas panaudojimas grąžina naują, o senasis nustoja veikti.

Atsijungimas

Pirmiausia išvalykite savo sesiją, tada nukreipkite į end_session_endpoint su post_logout_redirect_uri (ir id_token_hint, jei jį turite), kad Lobby taip pat pamirštų žmogų.