Швидкий старт: будь-яка бібліотека 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`

Піддомен вашого середовища видно в 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 там, куди має доступ лише сеанс цього браузера (добре підходить короткочасний файл cookie з httpOnly). Потім виконайте переспрямування з response_type=code, вашими client_id і redirect_uri, областями доступу, наведеними вище, state і code_challenge вашого верифікатора за S256.

Дайте їй увійти

Далі все бере на себе 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 теж забуло людину.