فوری آغاز: کوئی بھی 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 کی طرف اشارہ کر دیں، تو وہی اس کا جاری کنندہ ہوتا ہے۔

ڈسکوری دستاویز پڑھیں

آپ کے کلائنٹ کو درکار ہر اینڈ پوائنٹ اور کلید یہاں درج ہے۔ URLs اپنے کوڈ میں کاپی کرنے کے بجائے اپنی لائبریری کو اسے پڑھنے دیں۔

ٹرمینل

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 پر ری ڈائریکٹ کریں، تاکہ لابی بھی فرد کو بھول جائے۔