Szybki start: dowolna biblioteka OIDC

Usher to standardowy dostawca OpenID Connect. Jeśli w Twoim języku jest certyfikowany klient OIDC, masz już wszystko, czego potrzebujesz: wskaż mu dokument wykrywania swojego środowiska i użyj przepływu kodu autoryzacji z PKCE.

Ustawienia

Ustawienie	Wartość
Wystawca	`https://<handle>.usherid.com`
Adres URL wykrywania	`https://<handle>.usherid.com/.well-known/openid-configuration`
Przepływ	Kod autoryzacji (`response_type=code`)
PKCE	Wymagane, `code_challenge_method=S256`
Zakresy	`openid profile email offline_access`
Uwierzytelnianie klienta	Zgodnie z listą w `token_endpoint_auth_methods_supported`

Uchwyt środowiska znajdziesz w Usher Console, obok jego wystawcy. Środowiska deweloperskie dostają losowy uchwyt, taki jak wise-otter-42; środowiska produkcyjne mają uchwyt wybrany przez Ciebie. Środowisko produkcyjne może też działać w Twojej własnej domenie, takiej jak login.acme.com: wtedy to ona jest jego wystawcą, gdy już skierujesz domenę na Usher rekordem CNAME.

Odczytaj dokument wykrywania

Znajdziesz tu każdy punkt końcowy i klucz, których potrzebuje Twój klient. Pozwól bibliotece go odczytać, zamiast kopiować adresy URL do kodu.

Terminal

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

Odpowiedź (skrócona)

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

Przepływ

Skieruj daną osobę do punktu końcowego autoryzacji

Wygeneruj losowy weryfikator PKCE i przechowaj go razem z losową wartością state w miejscu dostępnym tylko dla sesji tej przeglądarki (dobrze sprawdza się krótkotrwały plik cookie z flagą httpOnly). Następnie przekieruj z parametrami response_type=code, swoimi client_id i redirect_uri, powyższymi zakresami, wartością state oraz wyzwaniem code_challenge S256 wyliczonym z weryfikatora.

Pozwól się zalogować

Od tego momentu wszystkim zajmuje się Lobby: podaje nazwę Twojej aplikacji, oferuje metody logowania, na które pozwala Twoje środowisko, i za pierwszym razem prosi o zgodę.

Sprawdź wywołanie zwrotne

Usher przekierowuje do Twojego redirect_uri z parametrami code i state. Odrzuć odpowiedź, jeśli state nie zgadza się z zapisaną wartością. Kod jest jednorazowy i ważny przez pięć minut.

Wymień kod na tokeny

Ze swojego serwera wyślij metodą POST kod i weryfikator PKCE do punktu końcowego tokenu:

Żądanie tokenu

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"

Zweryfikuj token ID

Sprawdź jego podpis kluczami spod jwks_uri oraz to, czy iss jest Twoim wystawcą, aud Twoim identyfikatorem klienta, a exp wskazuje czas w przyszłości. Twoja biblioteka robi to za Ciebie; upewnij się, że ta weryfikacja nie jest wyłączona.

W Node.js

openid-client robi wszystko powyższe, łącznie z walidacją:

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

W innych językach

Te popularne biblioteki obsługują standardowy OpenID Connect i działają z Usher bez żadnych dodatków specyficznych dla Usher:

Język	Biblioteka
Python	Authlib
Go	`coreos/go-oidc` z `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`

Utrzymanie sesji

Z zakresem offline_access odpowiedź z tokenami zawiera token odświeżania. Użyj go z grant_type=refresh_token, aby uzyskać nowy token dostępu, gdy stary wygaśnie. Tokeny odświeżania są rotowane: każde użycie zwraca nowy token, a stary przestaje działać.

Wylogowanie

Najpierw wyczyść własną sesję, a potem przekieruj do end_session_endpoint z post_logout_redirect_uri (oraz id_token_hint, jeśli go masz), aby Lobby również zapomniało o tej osobie.