Ghid rapid: orice bibliotecă OIDC

Usher este un furnizor OpenID Connect standard. Dacă limbajul dvs. are un client OIDC certificat, aveți deja tot ce vă trebuie: îndreptați-l spre documentul de descoperire al mediului și folosiți fluxul cu cod de autorizare și PKCE.

Setările

Setare	Valoare
Emitent	`https://<handle>.usherid.com`
URL de descoperire	`https://<handle>.usherid.com/.well-known/openid-configuration`
Flux	Cod de autorizare (`response_type=code`)
PKCE	Obligatoriu, `code_challenge_method=S256`
Scope-uri	`openid profile email offline_access`
Autentificarea clientului	Conform listei din `token_endpoint_auth_methods_supported`

Identificatorul mediului se află în Usher Console, lângă emitentul său. Mediile de dezvoltare primesc unul aleatoriu, cum ar fi wise-otter-42; mediile de producție au identificatorul ales de dvs. Un mediu de producție poate locui în schimb pe propriul dvs. domeniu, cum ar fi login.acme.com: atunci acesta este emitentul său, după ce ați îndreptat domeniul spre Usher cu o înregistrare CNAME.

Citiți documentul de descoperire

Aici sunt listate toate endpointurile și cheile de care are nevoie clientul dvs. Lăsați biblioteca să-l citească, în loc să copiați URL-uri în cod.

Terminal

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

Răspuns (prescurtat)

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

Fluxul

Trimiteți persoana la endpointul de autorizare

Generați un verificator PKCE aleatoriu și păstrați-l, împreună cu o valoare state aleatorie, într-un loc la care are acces doar sesiunea acestui browser (un cookie httpOnly de scurtă durată merge bine). Apoi redirecționați cu response_type=code, client_id și redirect_uri, scope-urile de mai sus, state și code_challenge S256 al verificatorului.

Lăsați-o să se conecteze

De aici preia Lobby-ul: numește aplicația dvs., oferă metodele de conectare permise de mediu și cere consimțământul prima dată.

Verificați callbackul

Usher redirecționează către redirect_uri cu code și state. Refuzați răspunsul dacă state nu se potrivește cu cel pe care l-ați stocat. Codul este de unică folosință și valabil cinci minute.

Schimbați codul pe tokenuri

De pe server, trimiteți codul și verificatorul PKCE la endpointul de tokenuri:

Cerere de token

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"

Validați tokenul ID

Verificați-i semnătura cu cheile de la jwks_uri, apoi că iss este emitentul dvs., aud este ID-ul clientului dvs. și exp este în viitor. Biblioteca face asta pentru dvs.; asigurați-vă că verificarea nu este dezactivată.

În Node.js

openid-client face tot ce este descris mai sus, inclusiv validarea:

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

În alte limbaje

Aceste biblioteci larg folosite vorbesc toate OpenID Connect standard și funcționează cu Usher fără nimic specific Usher:

Limbaj	Bibliotecă
Python	Authlib
Go	`coreos/go-oidc` cu `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`

Menținerea conectării

Cu scope-ul offline_access, răspunsul cu tokenuri include un token de reîmprospătare. Folosiți-l cu grant_type=refresh_token ca să obțineți un token de acces nou când cel vechi expiră. Tokenurile de reîmprospătare se rotesc: fiecare utilizare întoarce unul nou, iar cel vechi nu mai funcționează.

Deconectarea

Ștergeți mai întâi propria sesiune, apoi redirecționați către end_session_endpoint cu post_logout_redirect_uri (și id_token_hint, dacă îl aveți), ca Lobby-ul să uite și el persoana.