Panduan cepat: pustaka OIDC apa pun

Usher adalah penyedia OpenID Connect standar. Jika bahasa Anda memiliki klien OIDC bersertifikasi, Anda sudah punya semua yang dibutuhkan: arahkan klien itu ke dokumen discovery lingkungan Anda dan gunakan alur kode otorisasi dengan PKCE.

Pengaturannya

Pengaturan	Nilai
Penerbit	`https://<handle>.usherid.com`
URL discovery	`https://<handle>.usherid.com/.well-known/openid-configuration`
Alur	Kode otorisasi (`response_type=code`)
PKCE	Wajib, `code_challenge_method=S256`
Cakupan	`openid profile email offline_access`
Autentikasi klien	Sesuai daftar di `token_endpoint_auth_methods_supported`

Handle lingkungan Anda ada di Usher Console, di samping penerbitnya. Lingkungan pengembangan mendapat handle acak, seperti wise-otter-42; lingkungan produksi memiliki handle yang Anda pilih. Lingkungan produksi juga bisa berada di domain Anda sendiri, seperti login.acme.com: domain itulah yang menjadi penerbitnya, setelah Anda mengarahkan domain tersebut ke Usher dengan catatan CNAME.

Baca dokumen discovery

Setiap endpoint dan kunci yang dibutuhkan klien Anda tercantum di sini. Biarkan pustaka Anda membacanya, daripada menyalin URL ke dalam kode.

Terminal

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

Respons (diringkas)

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

Alurnya

Arahkan orang ke endpoint otorisasi

Buat verifier PKCE acak dan simpan, bersama state acak, di tempat yang hanya dapat dijangkau sesi browser ini (cookie httpOnly berumur pendek cocok untuk ini). Lalu alihkan dengan response_type=code, client_id dan redirect_uri Anda, cakupan di atas, state, dan code_challenge S256 dari verifier Anda.

Biarkan mereka masuk

Lobby mengambil alih dari sini: Lobby menyebutkan aplikasi Anda, menawarkan metode masuk yang diizinkan lingkungan Anda, dan meminta izin pada kali pertama.

Periksa callback

Usher mengalihkan ke redirect_uri Anda dengan code dan state. Tolak respons kecuali state cocok dengan yang Anda simpan. Kode ini sekali pakai dan berlaku lima menit.

Tukar kode dengan token

Dari server Anda, kirim kode dan verifier PKCE ke endpoint 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"

Validasi token ID

Periksa tanda tangannya terhadap kunci di jwks_uri, dan pastikan iss adalah penerbit Anda, aud adalah ID klien Anda, dan exp belum lewat. Pustaka Anda melakukannya untuk Anda; pastikan pemeriksaan itu tidak dimatikan.

Di Node.js

openid-client mengerjakan semua hal di atas, termasuk validasi:

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

Di bahasa lain

Pustaka populer berikut semuanya menggunakan OpenID Connect standar dan bekerja dengan Usher tanpa apa pun yang khusus 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`

Tetap masuk

Dengan cakupan offline_access, respons token menyertakan token refresh. Gunakan token itu dengan grant_type=refresh_token untuk mendapatkan token akses baru saat yang lama kedaluwarsa. Token refresh dirotasi: setiap pemakaian mengembalikan token baru, dan yang lama berhenti berfungsi.

Keluar

Hapus sesi Anda sendiri terlebih dahulu, lalu alihkan ke end_session_endpoint dengan post_logout_redirect_uri (dan id_token_hint jika ada), agar Lobby juga melupakan orang tersebut.