Gyorsindítás: bármely OIDC-könyvtár

Az Usher szabványos OpenID Connect-szolgáltató. Ha a nyelvedhez van tanúsított OIDC-kliens, már mindened megvan: irányítsd a környezeted felderítési dokumentumára, és használd az engedélyezési kódos folyamatot PKCE-vel.

A beállítások

Beállítás	Érték
Kibocsátó	`https://<handle>.usherid.com`
Felderítési URL	`https://<handle>.usherid.com/.well-known/openid-configuration`
Folyamat	Engedélyezési kód (`response_type=code`)
PKCE	Kötelező, `code_challenge_method=S256`
Hatókörök	`openid profile email offline_access`
Kliens-hitelesítés	A `token_endpoint_auth_methods_supported` listája szerint

A környezeted rövid nevét az Usher Console-ban találod, a kibocsátója mellett. A fejlesztői környezetek véletlenszerű rövid nevet kapnak, például wise-otter-42; az éles környezeteké az, amelyet te választottál. Egy éles környezet a saját domaineden is élhet, például login.acme.com címen: ekkor ez a kibocsátója, miután egy CNAME rekorddal az Usherre irányítottad a domaint.

Olvasd be a felderítési dokumentumot

Itt szerepel minden végpont és kulcs, amelyre a kliensednek szüksége van. Hagyd, hogy a könyvtárad olvassa be, ahelyett hogy URL-eket másolnál a kódodba.

Terminál

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

Válasz (rövidítve)

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

A folyamat

Küldd az illetőt az engedélyezési végpontra

Hozz létre egy véletlenszerű PKCE-ellenőrzőt, és tárold egy véletlenszerű state értékkel együtt olyan helyen, amelyhez csak ennek a böngészőnek a munkamenete fér hozzá (egy rövid életű, httpOnly cookie jól bevált). Ezután irányíts át a response_type=code paraméterrel, a client_id és a redirect_uri értékeddel, a fenti hatókörökkel, a state értékkel és az ellenőrződ S256 code_challenge értékével.

Hagyd, hogy bejelentkezzen

Innen a Lobby veszi át: megnevezi az appodat, felkínálja a környezeted által engedélyezett bejelentkezési módszereket, és első alkalommal hozzájárulást kér.

Ellenőrizd a visszahívást

Az Usher a code és a state paraméterrel irányít át a redirect_uri címedre. Utasítsd el a választ, ha a state nem egyezik a tárolttal. A kód egyszer használható, és öt percig érvényes.

Cseréld a kódot tokenekre

A szerveredről küldd el a kódot és a PKCE-ellenőrzőt a token-végpontra:

Tokenkérés

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"

Ellenőrizd az ID-tokent

Ellenőrizd az aláírását a jwks_uri címen elérhető kulcsokkal, valamint azt, hogy az iss a te kibocsátód, az aud az ügyfél-azonosítód, és az exp a jövőben van. Ezt a könyvtárad elvégzi helyetted; győződj meg róla, hogy nincs kikapcsolva.

Node.js-ben

Az openid-client mindezt elvégzi, az ellenőrzést is beleértve:

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

Más nyelveken

Ezek a széles körben használt könyvtárak mind szabványos OpenID Connectet beszélnek, és bármilyen Usher-specifikus kiegészítés nélkül működnek az Usherrel:

Nyelv	Könyvtár
Python	Authlib
Go	`coreos/go-oidc` és `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`

Bejelentkezve maradás

Az offline_access hatókörrel a tokenválasz egy frissítési tokent is tartalmaz. Használd a grant_type=refresh_token paraméterrel, hogy új hozzáférési tokent kapj, amikor a régi lejár. A frissítési tokenek cserélődnek: minden használat újat ad vissza, a régi pedig érvényét veszti.

Kijelentkezés

Először zárd le a saját munkamenetedet, majd irányíts át az end_session_endpoint címre a post_logout_redirect_uri paraméterrel (és az id_token_hint paraméterrel, ha megvan), hogy a Lobby is elfelejtse az illetőt.