آپ کی اپنی APIs

کوئی ایپ آپ کی کسی API کے لیے ایکسیس ٹوکن مانگ سکتی ہے۔ اسے ایک سائن شدہ JWT ملتا ہے جس کی آڈیئنس وہی API ہے اور کچھ نہیں، اور آپ کی API اسے آپ کے انوائرنمنٹ کی شائع شدہ کلیدوں سے، Usher کو کال کیے بغیر جانچتی ہے۔ ایک API کا ٹوکن دوسری API پر کسی کام کا نہیں۔

API کا نام دیں

Usher Console میں انوائرنمنٹ کھولیں، پھر ایپلیکیشنز ← آپ کی APIs ← API شامل کریں۔ اسے ایک نام اور ایک شناخت کنندہ دیں: ایک https:// پتہ، جیسے https://api.example.com، یا ایک URN، جیسے urn:example:api:notes۔ شناخت کنندہ وہ ہے جو ایپ مانگتی ہے اور جو ٹوکن کے aud کلیم میں لکھا ہوتا ہے (RFC 8707)۔

پھر API ان ایپس کو دیں جو اسے کال کرتی ہیں: ہر ایپلیکیشن پر APIs۔ ایپ کو صرف انہی APIs کے ٹوکن ملتے ہیں جو اسے دی گئی ہیں، چاہے وہ کچھ بھی مانگے۔ کوئی API ہٹا دیں تو وہ مزید ٹوکن نہیں دیتی؛ جو پہلے دیے جا چکے ہیں وہ چند منٹ میں ختم ہو جاتے ہیں۔

اسے مانگیں

ایپ اپنی آتھرائزیشن درخواست اور ٹوکن درخواستوں میں resource=<identifier> شامل کرتی ہے۔ موبائل SDKs یہ آپ کے لیے کرتے ہیں:

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")))

جو ایپ آپ کی دو APIs کو کال کرتی ہے وہ دونوں ایک ساتھ مانگ سکتی ہے؛ تب ٹوکن کی آڈیئنس میں دونوں درج ہوتی ہیں۔

اپنی API میں اسے جانچیں

ہر درخواست کے ٹوکن کی کسی بھی چیز پر بھروسا کرنے سے پہلے اسے جانچیں:

• دستخط، آپ کے انوائرنمنٹ کی ڈسکوری دستاویز میں موجود jwks_uri کی کلیدوں سے۔ الگورتھم کلید سے لیں، کبھی ٹوکن کے ہیڈر سے نہیں۔
• iss بالکل آپ کے انوائرنمنٹ کا جاری کنندہ ہو۔ اسے اپنی کنفیگریشن میں طے کریں؛ کبھی ٹوکن سے نہ پڑھیں۔
• aud میں آپ کی API کا شناخت کنندہ شامل ہو۔ (openid اسکوپ کے ساتھ اس میں آپ کے انوائرنمنٹ کا userinfo پتہ بھی ہوتا ہے۔)
• ہیڈر میں typ کی قدر at+jwt ہو، تاکہ ID ٹوکن کو ایکسیس ٹوکن بنا کر پیش نہ کیا جا سکے۔
• exp گزرا نہ ہو۔ ایکسیس ٹوکن 10 منٹ چلتے ہیں؛ SDKs انہیں آپ کے لیے ریفریش کرتے ہیں۔

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 سے تلاش کریں، کبھی ای میل سے نہیں: پتہ ہاتھ بدل سکتا ہے، سبجیکٹ کبھی نہیں بدلتا۔