Бързо начало: всяка OIDC библиотека

Usher е стандартен доставчик на OpenID Connect. Ако за вашия език има сертифициран OIDC клиент, вече разполагате с всичко необходимо: насочете го към документа за откриване на средата си и използвайте потока с код за оторизация и PKCE.

Настройките

Настройка	Стойност
Издател	`https://<handle>.usherid.com`
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`

Краткото име (handle) на средата ви е в Usher Console, до нейния издател. Средите за разработка получават случайно кратко име, например wise-otter-42; продукционните среди имат краткото име, което сте избрали. Продукционна среда може да се намира и на ваш собствен домейн, например login.acme.com: тогава той е неин издател, след като насочите домейна към Usher с CNAME запис.

Прочетете документа за откриване

Тук са изброени всички крайни точки и ключове, от които има нужда клиентът ви. Оставете библиотеката си да го прочете, вместо да копирате 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 бисквитка върши добра работа). След това пренасочете с response_type=code, вашите client_id и redirect_uri, обхватите по-горе, state и S256 code_challenge на верификатора.

Оставете го да влезе

Оттук нататък поема Lobby: назовава приложението ви, предлага методите за вход, които средата ви позволява, и първия път иска съгласие.

Проверете обратното извикване

Usher пренасочва към вашия redirect_uri с code и state. Отхвърлете отговора, освен ако 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, за да получите нов токен за достъп, когато старият изтече. Токените за опресняване се сменят: при всяко използване получавате нов, а старият спира да работи.

Изход

Първо изчистете собствената си сесия, след това пренасочете към end_session_endpoint с post_logout_redirect_uri (и id_token_hint, ако го имате), за да забрави човека и Lobby.