Kendi API’leriniz

Bir uygulama, API’lerinizden biri için erişim belirteci isteyebilir. Hedef kitlesi (audience) yalnızca o API olan imzalı bir JWT alır; API’niz de onu Usher’ı çağırmadan, ortamınızın yayımlanmış anahtarlarıyla denetler. Bir API için verilmiş belirteç başka bir API’de işe yaramaz.

API’yi adlandırın

Usher Console’da ortamı açın, ardından Uygulamalar → API’leriniz → API ekle yolunu izleyin. API’ye bir ad ve bir tanımlayıcı verin: https://api.example.com gibi bir https:// adresi ya da urn:example:api:notes gibi bir URN. Tanımlayıcı, uygulamanın istediği şeydir ve belirtecin aud talebinde (claim) yazan değerdir (RFC 8707).

Ardından API’yi onu çağıran uygulamalara verin: her uygulamadaki API’ler düğmesiyle. Bir uygulama, ne isterse istesin, yalnızca kendisine verilmiş API’ler için belirteç alır. Bir API’yi kaldırdığınızda artık belirteç vermez; dağıtılmış olanların süresi de birkaç dakika içinde dolar.

API’yi isteyin

Uygulama, yetkilendirme isteğine ve belirteç isteklerine resource=<identifier> ekler. Mobil SDK’lar bunu sizin için yapar:

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’lerinizden ikisini çağıran bir uygulama ikisini birden isteyebilir; bu durumda belirtecin hedef kitlesinde ikisi de listelenir.

API’nizde denetleyin

Bir isteğin belirtecindeki hiçbir şeye güvenmeden önce belirteci denetleyin:

• İmza: ortamınızın keşif belgesindeki jwks_uri adresinde bulunan anahtarlarla. Algoritmayı belirtecin üst bilgisinden değil, her zaman anahtardan alın.
• iss, ortamınızın yayıncısıyla birebir aynıdır. Bu değeri yapılandırmanızda sabitleyin; asla belirteçten okumayın.
• aud, API’nizin tanımlayıcısını içerir. (openid kapsamıyla, ortamınızın userinfo adresi de listelenir.)
• Üst bilgideki typ, at+jwt değeridir; böylece bir kimlik belirteci erişim belirteci yerine geçirilemez.
• exp geçmemiştir. Erişim belirteçleri 10 dakika geçerlidir; SDK’lar onları sizin için yeniler.

Node.js’te bunların hepsini @usher/node yapar:

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’da:

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"],
        };
    });

Belirteç ne söyler?

Zaten tanıdığınız kişiler

API’nizde önceden kalma hesaplar varsa, bir kişi bir Usher belirteciyle ilk kez geldiğinde onun hesabını bulabilirsiniz: onu email ile arayın, yalnızca email_verified değeri true olduğunda, ve o andan itibaren hesabında iss ve sub değerlerini saklayın. Bundan sonra onu e-postayla değil, her zaman iss ve sub ile bulun: bir adres el değiştirebilir, bir özne (subject) asla değiştirmez.