واجهات API الخاصة بك

يمكن للتطبيق أن يطلب رمز وصول لإحدى واجهات API الخاصة بك. فيحصل على رمز JWT موقّع جمهوره (audience) تلك الواجهة لا غير، وتتحقق منه واجهتك بالمفاتيح المنشورة لبيئتك، دون الاتصال بـ Usher. والرمز المخصص لواجهة ما لا ينفع مع أخرى.

سمِّ واجهة 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، فلا يمكن تمرير رمز هوية على أنه رمز وصول.
• 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، لا بالبريد الإلكتروني أبدًا: فالعنوان قد ينتقل إلى شخص آخر، أما المعرّف (subject) فلا يتغير أبدًا.