Жылдам бастау: кез келген OIDC кітапханасы

Usher — стандартты OpenID Connect провайдері. Егер тіліңізде сертификатталған OIDC клиенті болса, сізде қажеттінің бәрі бар: оны ортаңыздың discovery құжатына бағыттап, PKCE бар авторизация коды ағынын пайдаланыңыз.

Параметрлер

Параметр	Мәні
Эмитент	`https://<handle>.usherid.com`
Discovery URL	`https://<handle>.usherid.com/.well-known/openid-configuration`
Ағын	Авторизация коды (`response_type=code`)
PKCE	Міндетті, `code_challenge_method=S256`
Ауқымдар	`openid profile email offline_access`
Клиент аутентификациясы	`token_endpoint_auth_methods_supported` тізімінде көрсетілгендей

Ортаңыздың идентификаторы Usher Console ішінде, оның эмитентінің қасында тұр. Әзірлеу орталары wise-otter-42 сияқты кездейсоқ идентификатор алады; өндірістік орталарда сіз таңдаған идентификатор болады. Өндірістік орта оның орнына login.acme.com сияқты өз доменіңізде орналаса алады: доменді CNAME жазбасымен Usher-ге бағыттағаннан кейін, оның эмитенті сол болады.

Discovery құжатын оқыңыз

Клиентіңізге қажет әр нүкте мен кілт осында көрсетілген. URL-дарды кодыңызға көшірудің орнына, оны кітапханаңызға оқытыңыз.

Терминал

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

Жауап (қысқартылған)

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

Ағын

Адамды авторизация нүктесіне жіберіңіз

Кездейсоқ PKCE верификаторын жасап, оны кездейсоқ state мәнімен бірге тек осы браузердің сеансы қол жеткізе алатын жерде сақтаңыз (қысқа мерзімді httpOnly cookie файлы жақсы жарайды). Содан кейін response_type=code, client_id пен redirect_uri, жоғарыдағы ауқымдар, state және верификаторыңыздың S256 code_challenge мәнімен қайта бағыттаңыз.

Оған кіруге мүмкіндік беріңіз

Бұдан әрі Lobby жалғастырады: ол қолданбаңызды атайды, ортаңыз рұқсат ететін кіру тәсілдерін ұсынады және алғаш рет келісім сұрайды.

Кері шақыруды тексеріңіз

Usher code және state мәндерімен redirect_uri мекенжайыңызға қайта бағыттайды. state сіз сақтаған мәнмен сәйкес келмесе, жауапты қабылдамаңыз. Код бір реттік және бес минут жарамды.

Кодты токендерге айырбастаңыз

Серверіңізден кодты және PKCE верификаторын токен нүктесіне жіберіңіз:

Токен сұрауы

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"

ID токенін тексеріңіз

Оның қолтаңбасын jwks_uri мекенжайындағы кілттер бойынша тексеріңіз, сондай-ақ iss сіздің эмитентіңіз, aud клиент ID-ыңыз екенін және exp болашақта екенін тексеріңіз. Мұны кітапханаңыз сіз үшін жасайды; оның өшірілмегеніне көз жеткізіңіз.

Node.js ортасында

openid-client жоғарыдағының бәрін, тексеруді қоса, орындайды:

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

Басқа тілдерде

Бұл кең қолданылатын кітапханалардың бәрі стандартты OpenID Connect тілінде сөйлейді және Usher-ге тән ештеңесіз Usher-мен жұмыс істейді:

Тіл	Кітапхана
Python	Authlib
Go	`coreos/go-oidc` және `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`

Кірген күйде қалу

offline_access ауқымымен токен жауабына жаңарту токені кіреді. Ескі қатынас токенінің мерзімі біткенде жаңасын алу үшін оны grant_type=refresh_token арқылы пайдаланыңыз. Жаңарту токендері ауысып отырады: әр пайдалану жаңасын қайтарады, ал ескісі жұмыс істеуін тоқтатады.

Шығу

Алдымен өз сеансыңызды тазалап, содан кейін Lobby де адамды ұмытуы үшін post_logout_redirect_uri (және бар болса, id_token_hint) мәнімен end_session_endpoint нүктесіне қайта бағыттаңыз.