Démarrage rapide : toute bibliothèque OIDC

Usher est un fournisseur OpenID Connect standard. Si votre langage dispose d’un client OIDC certifié, vous avez déjà tout ce qu’il vous faut : pointez-le vers le document de découverte de votre environnement et utilisez le flux de code d’autorisation avec PKCE.

Les paramètres

Paramètre	Valeur
Émetteur	`https://<handle>.usherid.com`
URL de découverte	`https://<handle>.usherid.com/.well-known/openid-configuration`
Flux	Code d’autorisation (`response_type=code`)
PKCE	Obligatoire, `code_challenge_method=S256`
Portées	`openid profile email offline_access`
Authentification du client	Selon la liste de `token_endpoint_auth_methods_supported`

L’identifiant de votre environnement figure dans Usher Console, à côté de son émetteur. Les environnements de développement en reçoivent un aléatoire, comme wise-otter-42; les environnements de production ont celui que vous avez choisi. Un environnement de production peut aussi se trouver sur votre propre domaine, comme login.acme.com : c’est alors son émetteur, une fois que vous avez fait pointer le domaine vers Usher avec un enregistrement CNAME.

Lire le document de découverte

Tous les points de terminaison et toutes les clés dont votre client a besoin y sont répertoriés. Laissez votre bibliothèque le lire plutôt que de copier des URL dans votre code.

Terminal

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

Réponse (extrait)

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

Le flux

Envoyer la personne vers le point de terminaison d’autorisation

Créez un vérificateur PKCE aléatoire et conservez-le, avec un state aléatoire, à un endroit que seule la session de ce navigateur peut atteindre (un cookie httpOnly de courte durée convient bien). Redirigez ensuite avec response_type=code, votre client_id et votre redirect_uri, les portées ci-dessus, le state, et le code_challenge S256 de votre vérificateur.

La laisser se connecter

Le Lobby prend le relais : il nomme votre app, propose les méthodes de connexion que votre environnement autorise, et demande le consentement la première fois.

Vérifier le retour

Usher redirige vers votre redirect_uri avec code et state. Refusez la réponse si state ne correspond pas à celui que vous avez stocké. Le code est à usage unique et valable cinq minutes.

Échanger le code contre des jetons

Depuis votre serveur, envoyez le code et le vérificateur PKCE au point de terminaison de jeton :

Requête de jeton

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"

Valider le jeton d’ID

Vérifiez sa signature avec les clés de jwks_uri, et contrôlez que iss est votre émetteur, que aud est votre ID client et que exp est dans le futur. Votre bibliothèque le fait pour vous; assurez-vous simplement que cette vérification n’est pas désactivée.

Avec Node.js

openid-client fait tout ce qui précède, validation comprise :

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

Dans d’autres langages

Ces bibliothèques très répandues parlent toutes OpenID Connect standard et fonctionnent avec Usher sans rien de spécifique à Usher :

Langage	Bibliothèque
Python	Authlib
Go	`coreos/go-oidc` avec `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`

Rester connecté

Avec la portée offline_access, la réponse de jeton inclut un jeton d’actualisation. Utilisez-le avec grant_type=refresh_token pour obtenir un nouveau jeton d’accès quand l’ancien expire. Les jetons d’actualisation font l’objet d’une rotation : chaque utilisation en renvoie un nouveau, et l’ancien cesse de fonctionner.

Se déconnecter

Effacez d’abord votre propre session, puis redirigez vers le end_session_endpoint avec post_logout_redirect_uri (et id_token_hint si vous l’avez), pour que le Lobby oublie aussi la personne.