झटपट सुरुवात: कोणतीही 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: तुम्ही CNAME रेकॉर्डने ते डोमेन Usher कडे निर्देशित केल्यावर, तोच त्याचा इश्युअर असतो.

डिस्कव्हरी दस्तऐवज वाचा

तुमच्या क्लायंटला लागणारा प्रत्येक एंडपॉइंट आणि की इथे दिलेली आहे. 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 सह, फक्त याच ब्राउझरचे सेशन पोहोचू शकेल अशा ठिकाणी ठेवा (अल्पकालीन, httpOnly कुकी चांगली चालते). मग response_type=code, तुमचा client_id आणि redirect_uri, वरील स्कोप, state, आणि तुमच्या व्हेरिफायरचा S256 code_challenge घेऊन रीडायरेक्ट करा.

त्यांना साइन इन करू द्या

इथून पुढे लॉबी सांभाळते: ती तुमच्या ॲपचे नाव दाखवते, तुमचे एन्व्हायर्नमेंट परवानगी देते त्या साइन-इन पद्धती देते, आणि पहिल्यांदा संमती मागते.

कॉलबॅक तपासा

Usher code आणि state सह तुमच्या redirect_uri वर रीडायरेक्ट करतो. 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"

ID टोकन व्हॅलिडेट करा

त्याची सही jwks_uri वरील की विरुद्ध तपासा, आणि iss हा तुमचा इश्युअर, aud हा तुमचा क्लायंट ID आणि 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 सह वापरा. रिफ्रेश टोकन रोटेट होतात: प्रत्येक वापरावर नवीन मिळते, आणि जुने काम करणे थांबवते.

साइन आउट करणे

आधी तुमचे स्वतःचे सेशन साफ करा, मग post_logout_redirect_uri (आणि तुमच्याकडे असल्यास id_token_hint) सह end_session_endpoint कडे रीडायरेक्ट करा, म्हणजे लॉबीही व्यक्तीला विसरते.