Brzi početak: bilo koja OIDC biblioteka

Usher je standardni pružatelj usluge OpenID Connect. Ako za vaš jezik postoji certificirani OIDC klijent, već imate sve što vam treba: usmjerite ga na dokument za otkrivanje svojeg okruženja i koristite tok autorizacijskog kôda uz PKCE.

Postavke

Postavka	Vrijednost
Izdavatelj	`https://<handle>.usherid.com`
URL za otkrivanje	`https://<handle>.usherid.com/.well-known/openid-configuration`
Tok	Autorizacijski kôd (`response_type=code`)
PKCE	Obavezno, `code_challenge_method=S256`
Opsezi	`openid profile email offline_access`
Autentifikacija klijenta	Kako je navedeno u `token_endpoint_auth_methods_supported`

Oznaku svojeg okruženja naći ćete u sučelju Usher Console, pokraj njegova izdavatelja. Razvojna okruženja dobivaju nasumičnu oznaku, kao što je wise-otter-42; produkcijska okruženja imaju oznaku koju ste odabrali. Produkcijsko okruženje može se umjesto toga nalaziti na vašoj vlastitoj domeni, kao što je login.acme.com: tada je to njegov izdavatelj, nakon što domenu CNAME zapisom usmjerite na Usher.

Pročitajte dokument za otkrivanje

Ovdje su navedene sve krajnje točke i ključevi koje vaš klijent treba. Neka ga vaša biblioteka čita umjesto da URL-ove kopirate u kôd.

Terminal

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

Odgovor (skraćeno)

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

Tok

Pošaljite osobu na autorizacijsku krajnju točku

Izradite nasumični PKCE verifikator i spremite ga, zajedno s nasumičnom vrijednošću state, negdje kamo može doći samo sesija ovog preglednika (dobro služi kratkotrajni httpOnly kolačić). Zatim preusmjerite s response_type=code, svojim client_id i redirect_uri, gore navedenim opsezima, vrijednošću state i S256 vrijednošću code_challenge svojeg verifikatora.

Pustite ih da se prijave

Odavde preuzima Lobby: navodi vašu aplikaciju, nudi načine prijave koje vaše okruženje dopušta i prvi put traži pristanak.

Provjerite povratni poziv

Usher preusmjerava na vaš redirect_uri s parametrima code i state. Odbijte odgovor ako se state ne podudara s onim koji ste spremili. Kôd je jednokratan i vrijedi pet minuta.

Zamijenite kôd za tokene

Sa svojeg poslužitelja pošaljite kôd i PKCE verifikator krajnjoj točki za tokene:

Zahtjev za 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"

Provjerite ID token

Provjerite njegov potpis prema ključevima na adresi jwks_uri te da je iss vaš izdavatelj, aud vaš ID klijenta, a exp u budućnosti. Vaša biblioteka to radi umjesto vas; provjerite da ta provjera nije isključena.

U okruženju Node.js

openid-client obavlja sve gore navedeno, uključujući provjeru:

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

U drugim jezicima

Sve ove široko korištene biblioteke govore standardni OpenID Connect i rade s platformom Usher bez ičega specifičnog za Usher:

Jezik	Biblioteka
Python	Authlib
Go	`coreos/go-oidc` uz `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`

Ostanak u prijavi

Uz opseg offline_access odgovor s tokenima uključuje i token za osvježavanje. Upotrijebite ga s grant_type=refresh_token kako biste dobili novi pristupni token kad stari istekne. Tokeni za osvježavanje se rotiraju: svaka upotreba vraća novi, a stari prestaje raditi.

Odjava

Najprije očistite vlastitu sesiju, a zatim preusmjerite na end_session_endpoint s post_logout_redirect_uri (i id_token_hint ako ga imate), kako bi i Lobby zaboravio osobu.