ਛੇਤੀ ਸ਼ੁਰੂਆਤ: ਕੋਈ ਵੀ 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 ’ਤੇ ਰੀਡਾਇਰੈਕਟ ਕਰੋ, ਤਾਂ ਜੋ ਲਾਬੀ ਵੀ ਵਿਅਕਤੀ ਨੂੰ ਭੁੱਲ ਜਾਵੇ।