Hızlı başlangıç: herhangi bir OIDC kütüphanesi

Usher standart bir OpenID Connect sağlayıcısıdır. Kullandığınız dilin sertifikalı bir OIDC istemcisi varsa ihtiyacınız olan her şey zaten elinizde: onu ortamınızın keşif belgesine yönlendirin ve PKCE ile yetkilendirme kodu akışını kullanın.

Ayarlar

Ayar	Değer
Yayıncı	`https://<handle>.usherid.com`
Keşif URL’si	`https://<handle>.usherid.com/.well-known/openid-configuration`
Akış	Yetkilendirme kodu (`response_type=code`)
PKCE	Zorunlu, `code_challenge_method=S256`
Kapsamlar	`openid profile email offline_access`
İstemci kimlik doğrulaması	`token_endpoint_auth_methods_supported` içinde listelendiği gibi

Ortamınızın kısa adı Usher Console’da, yayıncısının yanında yer alır. Geliştirme ortamları wise-otter-42 gibi rastgele bir kısa ad alır; üretim ortamlarının kısa adı sizin seçtiğinizdir. Bir üretim ortamı bunun yerine login.acme.com gibi kendi alan adınızda da bulunabilir: alan adını bir CNAME kaydıyla Usher’a yönlendirdiğinizde yayıncısı o olur.

Keşif belgesini okuyun

İstemcinizin ihtiyaç duyduğu her uç nokta ve anahtar burada listelenir. URL’leri kodunuza kopyalamak yerine bu belgeyi kütüphanenizin okumasına izin verin.

Terminal

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

Yanıt (kısaltılmış)

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

Akış

Kişiyi yetkilendirme uç noktasına gönderin

Rastgele bir PKCE doğrulayıcısı oluşturun ve onu rastgele bir state değeriyle birlikte yalnızca bu tarayıcının oturumunun erişebileceği bir yerde saklayın (kısa ömürlü, httpOnly bir çerez iyi iş görür). Ardından response_type=code, client_id ve redirect_uri değerleriniz, yukarıdaki kapsamlar, state ve doğrulayıcınızın S256 code_challenge değeriyle yönlendirin.

Giriş yapmalarına izin verin

Buradan sonrasını Lobby üstlenir: uygulamanızı adıyla söyler, ortamınızın izin verdiği giriş yöntemlerini sunar ve ilk seferinde onay ister.

Geri dönüşü denetleyin

Usher, code ve state ile redirect_uri adresinize yönlendirir. state, sakladığınızla eşleşmiyorsa yanıtı reddedin. Kod tek kullanımlıktır ve beş dakika geçerlidir.

Kodu belirteçlerle değiştirin

Sunucunuzdan kodu ve PKCE doğrulayıcısını belirteç uç noktasına gönderin:

Belirteç isteği

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"

Kimlik belirtecini doğrulayın

İmzasını jwks_uri adresindeki anahtarlarla doğrulayın; iss değerinin yayıncınız, aud değerinin istemci kimliğiniz olduğunu ve exp değerinin gelecekte olduğunu denetleyin. Bunu kütüphaneniz sizin için yapar; kapatılmadığından emin olun.

Node.js’te

openid-client, doğrulama dahil yukarıdakilerin hepsini yapar:

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ğer dillerde

Yaygın olarak kullanılan bu kütüphanelerin hepsi standart OpenID Connect konuşur ve Usher’a özgü hiçbir şey gerektirmeden Usher ile çalışır:

Dil	Kütüphane
Python	Authlib
Go	`coreos/go-oidc` ile `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`

Oturumu açık tutmak

offline_access kapsamıyla belirteç yanıtı bir yenileme belirteci de içerir. Eski erişim belirtecinin süresi dolduğunda yenisini almak için onu grant_type=refresh_token ile kullanın. Yenileme belirteçleri her kullanımda değişir: her kullanımda yeni bir belirteç gelir ve eskisi artık çalışmaz.

Çıkış yapmak

Önce kendi oturumunuzu temizleyin, ardından Lobby’nin de kişiyi unutması için post_logout_redirect_uri (ve varsa id_token_hint) ile end_session_endpoint adresine yönlendirin.