Mula pantas: mana-mana pustaka OIDC

Usher ialah penyedia OpenID Connect standard. Jika bahasa anda mempunyai klien OIDC yang diperakui, anda sudah mempunyai semua yang diperlukan: halakan ia ke dokumen penemuan persekitaran anda dan gunakan aliran kod kebenaran dengan PKCE.

Seting

Seting	Nilai
Pengeluar	`https://<handle>.usherid.com`
URL penemuan	`https://<handle>.usherid.com/.well-known/openid-configuration`
Aliran	Kod kebenaran (`response_type=code`)
PKCE	Wajib, `code_challenge_method=S256`
Skop	`openid profile email offline_access`
Pengesahan klien	Seperti yang disenaraikan dalam `token_endpoint_auth_methods_supported`

Handle persekitaran anda ada dalam Usher Console, di sebelah pengeluarnya. Persekitaran pembangunan mendapat handle rawak, seperti wise-otter-42; persekitaran produksi mempunyai handle yang anda pilih. Persekitaran produksi boleh berada di domain anda sendiri sebaliknya, seperti login.acme.com: kemudian itulah pengeluarnya, setelah anda menghalakan domain itu ke Usher dengan rekod CNAME.

Baca dokumen penemuan

Setiap titik akhir dan kunci yang diperlukan oleh klien anda disenaraikan di sini. Biarkan pustaka anda membacanya, dan bukannya menyalin URL ke dalam kod anda.

Terminal

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

Respons (diringkaskan)

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

Alirannya

Hantar orang itu ke titik akhir kebenaran

Buat pengesah PKCE rawak dan simpan, bersama state rawak, di tempat yang hanya boleh dicapai oleh sesi pelayar ini (kuki httpOnly berjangka hayat singkat sesuai digunakan). Kemudian ubah hala dengan response_type=code, client_id dan redirect_uri anda, skop di atas, state, dan code_challenge S256 bagi pengesah anda.

Biarkan mereka daftar masuk

Lobby mengambil alih dari sini: ia menamakan aplikasi anda, menawarkan kaedah daftar masuk yang dibenarkan oleh persekitaran anda, dan meminta persetujuan pada kali pertama.

Semak panggilan balik

Usher mengubah hala ke redirect_uri anda dengan code dan state. Tolak respons itu melainkan state sepadan dengan yang anda simpan. Kod itu sekali guna dan sah selama lima minit.

Tukar kod dengan token

Dari pelayan anda, hantar kod dan pengesah PKCE ke titik akhir token:

Permintaan 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"

Sahkan token ID

Semak tandatangannya terhadap kunci di jwks_uri, dan pastikan iss ialah pengeluar anda, aud ialah ID klien anda dan exp berada pada masa hadapan. Pustaka anda melakukan ini untuk anda; pastikan ia tidak dimatikan.

Dalam Node.js

openid-client melakukan semua perkara di atas, termasuk pengesahan:

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

Dalam bahasa lain

Pustaka yang digunakan secara meluas ini semuanya menggunakan OpenID Connect standard dan berfungsi dengan Usher tanpa apa-apa yang khusus untuk Usher:

Bahasa	Pustaka
Python	Authlib
Go	`coreos/go-oidc` dengan `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`

Kekal didaftar masuk

Dengan skop offline_access, respons token termasuk token muat semula. Gunakannya dengan grant_type=refresh_token untuk mendapatkan token akses baharu apabila token lama luput. Token muat semula berputar: setiap penggunaan memulangkan token baharu, dan token lama berhenti berfungsi.

Daftar keluar

Kosongkan sesi anda sendiri dahulu, kemudian ubah hala ke end_session_endpoint dengan post_logout_redirect_uri (dan id_token_hint jika ada), supaya Lobby juga melupakan orang itu.