क्विकस्टार्ट: कोई भी 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 में, उसके इश्यूअर के बगल में दिखता है। Development एनवायरनमेंट को एक रैंडम हैंडल मिलता है, जैसे wise-otter-42; production एनवायरनमेंट का हैंडल वही होता है जो आपने चुना। Production एनवायरनमेंट इसके बजाय आपके अपने डोमेन पर भी रह सकता है, जैसे 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 के साथ रीडायरेक्ट करें।

उन्हें साइन इन करने दें

यहाँ से 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"

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 पर रीडायरेक्ट करें, ताकि Lobby भी उस व्यक्ति को भूल जाए।