క్విక్స్టార్ట్: ఏదైనా 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 వెరిఫైయర్ను టోకెన్ ఎండ్పాయింట్కు POST చేయండి:
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 ధృవీకరణతో సహా పైవన్నీ చేస్తుంది:
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 | golang.org/x/oauth2తో coreos/go-oidc |
| 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కు రీడైరెక్ట్ చేయండి.