आपके अपने API

कोई ऐप आपके किसी API के लिए ऐक्सेस टोकन माँग सकता है। उसे एक साइन किया गया JWT मिलता है, जिसकी ऑडियंस वही API है और कुछ नहीं, और आपका API उसे Usher को कॉल किए बिना, आपके एनवायरनमेंट की प्रकाशित कुंजियों से जाँचता है। एक API का टोकन किसी दूसरे API पर किसी काम का नहीं।

API को नाम दें

Usher Console में एनवायरनमेंट खोलें, फिर ऐप्लिकेशन → आपके API → API जोड़ें पर जाएँ। इसे एक नाम और एक आइडेंटिफ़ायर दें: एक https:// पता, जैसे https://api.example.com, या एक URN, जैसे urn:example:api:notes। ऐप यही आइडेंटिफ़ायर माँगता है, और टोकन का aud क्लेम भी यही बताता है (RFC 8707)।

फिर API उन ऐप को दें जो उसे कॉल करते हैं: हर ऐप्लिकेशन पर API। ऐप चाहे जो माँगे, उसे सिर्फ़ उन्हीं API के टोकन मिलते हैं जो उसे दिए गए हैं। कोई API हटा दें, तो उसके लिए और टोकन नहीं मिलते; जो पहले से जारी हो चुके हैं, वे कुछ ही मिनटों में ख़त्म हो जाते हैं।

इसे माँगें

ऐप अपने ऑथराइज़ेशन अनुरोध और अपने टोकन अनुरोधों में resource=<identifier> जोड़ता है। मोबाइल SDK यह आपके लिए कर देते हैं:

let usher = UsherClient(configuration: .init(
    issuer: URL(string: "https://login.example.com")!,
    clientID: "…",
    redirectURI: URL(string: "com.example.notes:/oauth/callback")!,
    resources: ["urn:example:api:notes"]))

var request = URLRequest(url: URL(string: "https://api.example.com/notes")!)
try await usher.authorize(&request)   // Authorization: Bearer <a JWT for the Notes API>

val usher = Usher.client(context, UsherConfiguration(
    issuer = "https://login.example.com",
    clientId = "…",
    redirectUri = "com.example.notes:/oauth/callback",
    resources = listOf("urn:example:api:notes")))

जो ऐप आपके दो API कॉल करता है, वह दोनों एक साथ माँग सकता है; तब टोकन की ऑडियंस में दोनों होते हैं।

अपने API में इसे जाँचें

टोकन में दी गई किसी भी चीज़ पर भरोसा करने से पहले, हर अनुरोध का टोकन जाँचें:

• सिग्नेचर, आपके एनवायरनमेंट के डिस्कवरी दस्तावेज़ में दिए jwks_uri की कुंजियों से। एल्गोरिदम कुंजी से लें, टोकन के हेडर से कभी नहीं।
• iss बिल्कुल आपके एनवायरनमेंट का इश्यूअर हो। इसे अपने कॉन्फ़िगरेशन में तय रखें; टोकन से कभी न पढ़ें।
• aud में आपके API का आइडेंटिफ़ायर हो। (openid स्कोप के साथ इसमें आपके एनवायरनमेंट का userinfo पता भी होता है।)
• हेडर में typ का मान at+jwt हो, ताकि कोई ID टोकन ऐक्सेस टोकन बनाकर न चलाया जा सके।
• exp बीता न हो। ऐक्सेस टोकन 10 मिनट चलते हैं; SDK उन्हें आपके लिए रीफ़्रेश कर देते हैं।

Node.js में, @usher/node यह सब करता है:

import { createVerifier } from '@usher/node'

const usher = await createVerifier({
  issuer: 'https://login.example.com',
  audience: 'urn:example:api:notes',
})

const claims = await usher.accessToken(bearerToken) // throws if any check fails

ASP.NET Core में:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.Authority = "https://login.example.com"; // discovery and keys come from here
        o.MapInboundClaims = false;
        o.TokenValidationParameters = new()
        {
            ValidIssuer = "https://login.example.com",
            ValidAudience = "urn:example:api:notes",
            ValidTypes = ["at+jwt"],
        };
    });

टोकन क्या बताता है

जिन लोगों को आप पहले से जानते हैं

अगर आपके API में पहले से खाते हैं, तो कोई व्यक्ति पहली बार Usher टोकन के साथ आए, तब आप उसका खाता खोज सकते हैं: उन्हें email से खोजें, सिर्फ़ तब, जब email_verified का मान true हो, और उसके बाद से उनके खाते पर iss और sub सहेज लें। उसके बाद उन्हें iss और sub से खोजें, ईमेल से कभी नहीं: कोई पता किसी और के हाथ में जा सकता है, पर सब्जेक्ट कभी नहीं बदलता।