Γρήγορη έναρξη: οποιαδήποτε βιβλιοθήκη OIDC

Το Usher είναι ένας τυπικός πάροχος OpenID Connect. Αν η γλώσσα σας έχει πιστοποιημένο πελάτη OIDC, έχετε ήδη ό,τι χρειάζεστε: στρέψτε τον στο έγγραφο ανακάλυψης του περιβάλλοντός σας και χρησιμοποιήστε τη ροή κωδικού εξουσιοδότησης με PKCE.

Οι ρυθμίσεις

Ρύθμιση	Τιμή
Εκδότης	`https://<handle>.usherid.com`
URL ανακάλυψης	`https://<handle>.usherid.com/.well-known/openid-configuration`
Ροή	Κωδικός εξουσιοδότησης (`response_type=code`)
PKCE	Υποχρεωτικό, `code_challenge_method=S256`
Εμβέλειες	`openid profile email offline_access`
Έλεγχος ταυτότητας πελάτη	Όπως αναφέρεται στο `token_endpoint_auth_methods_supported`

Το ψευδώνυμο του περιβάλλοντός σας βρίσκεται στο Usher Console, δίπλα στον εκδότη του. Τα περιβάλλοντα ανάπτυξης παίρνουν ένα τυχαίο, όπως wise-otter-42· τα περιβάλλοντα παραγωγής έχουν το ψευδώνυμο που επιλέξατε. Ένα περιβάλλον παραγωγής μπορεί αντ’ αυτού να βρίσκεται στον δικό σας τομέα, όπως login.acme.com: τότε αυτός είναι ο εκδότης του, αφού στρέψετε τον τομέα στο Usher με μια εγγραφή CNAME.

Διαβάστε το έγγραφο ανακάλυψης

Εδώ αναφέρεται κάθε τελικό σημείο και κλειδί που χρειάζεται ο πελάτης σας. Αφήστε τη βιβλιοθήκη σας να το διαβάσει, αντί να αντιγράφετε URL στον κώδικά σας.

Τερματικό

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

Απάντηση (συντομευμένη)

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

Η ροή

Στείλτε τον χρήστη στο τελικό σημείο εξουσιοδότησης

Δημιουργήστε έναν τυχαίο επαληθευτή PKCE και κρατήστε τον, μαζί με μια τυχαία τιμή state, κάπου όπου έχει πρόσβαση μόνο η περίοδος σύνδεσης αυτού του προγράμματος περιήγησης (ένα cookie σύντομης διάρκειας με httpOnly λειτουργεί καλά). Έπειτα ανακατευθύνετε με response_type=code, το client_id και το redirect_uri σας, τις παραπάνω εμβέλειες, το state και το S256 code_challenge του επαληθευτή σας.

Αφήστε τον να συνδεθεί

Από εδώ αναλαμβάνει το Lobby: ονομάζει την εφαρμογή σας, προσφέρει τις μεθόδους σύνδεσης που επιτρέπει το περιβάλλον σας και ζητά συναίνεση την πρώτη φορά.

Ελέγξτε την επιστροφή

Το Usher ανακατευθύνει στο redirect_uri σας με code και state. Απορρίψτε την απάντηση εκτός αν το state ταιριάζει με αυτό που αποθηκεύσατε. Ο κωδικός είναι μίας χρήσης και ισχύει πέντε λεπτά.

Ανταλλάξτε τον κωδικό με διακριτικά

Από τον διακομιστή σας, στείλτε τον κωδικό και τον επαληθευτή PKCE στο τελικό σημείο διακριτικών:

Αίτημα διακριτικών

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"

Επικυρώστε το διακριτικό αναγνωριστικού

Ελέγξτε την υπογραφή του με τα κλειδιά στο jwks_uri, και ότι το iss είναι ο εκδότης σας, το aud είναι το αναγνωριστικό πελάτη σας και το exp βρίσκεται στο μέλλον. Η βιβλιοθήκη σας το κάνει αυτό για εσάς· βεβαιωθείτε ότι δεν είναι απενεργοποιημένο.

Στο Node.js

Το openid-client κάνει όλα τα παραπάνω, μαζί με την επικύρωση:

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

Σε άλλες γλώσσες

Αυτές οι ευρέως χρησιμοποιούμενες βιβλιοθήκες μιλούν όλες τυπικό OpenID Connect και λειτουργούν με το Usher χωρίς τίποτα ειδικό για το Usher:

Γλώσσα	Βιβλιοθήκη
Python	Authlib
Go	`coreos/go-oidc` με `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`

Παραμονή σε σύνδεση

Με την εμβέλεια offline_access, η απάντηση διακριτικών περιλαμβάνει ένα διακριτικό ανανέωσης. Χρησιμοποιήστε το με grant_type=refresh_token για να πάρετε νέο διακριτικό πρόσβασης όταν λήξει το παλιό. Τα διακριτικά ανανέωσης εναλλάσσονται: κάθε χρήση επιστρέφει νέο, και το παλιό σταματά να λειτουργεί.

Αποσύνδεση

Καθαρίστε πρώτα τη δική σας περίοδο σύνδεσης και, στη συνέχεια, ανακατευθύνετε στο end_session_endpoint με post_logout_redirect_uri (και id_token_hint αν το έχετε), ώστε να ξεχάσει τον χρήστη και το Lobby.