Өз API-ларыңыз

Қолданба сіздің API-ларыңыздың біріне қатынас токенін сұрай алады. Ол аудиториясы тек сол API болатын қол қойылған JWT алады, ал API-ыңыз оны Usher-ге жүгінбей, ортаңыздың жарияланған кілттерімен тексереді. Бір API-ға арналған токен басқасына жарамайды.

API-ды атаңыз

Usher Console ішінде ортаны ашып, Қолданбалар → Сіздің API-ларыңыз → API қосу тармағын таңдаңыз. Оған атау мен идентификатор беріңіз: https://api.example.com сияқты https:// мекенжайы немесе urn:example:api:notes сияқты URN. Идентификатор — қолданба сұрайтын және токеннің aud талабында көрсетілетін мән (RFC 8707).

Содан кейін API-ды оны шақыратын қолданбаларға беріңіз: әр қолданбаның API-лар бөлімінде. Қолданба не сұраса да, тек өзіне берілген API-ларға арналған токендерді алады. API-ды алып тастасаңыз, ол бұдан былай токен бермейді; бұрын берілгендерінің мерзімі бірнеше минут ішінде бітеді.

Оны сұраңыз

Қолданба өзінің авторизация сұрауына және токен сұрауларына resource=<identifier> қосады. Мобильді SDK-лар мұны сіз үшін жасайды:

swift

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>

kotlin

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-ыңызда тексеріңіз

Әр сұраудың токеніндегі кез келген нәрсеге сенбес бұрын оны тексеріңіз:

Қолтаңбаны — ортаңыздың discovery құжатындағы jwks_uri мекенжайындағы кілттер бойынша. Алгоритмді токеннің тақырыбынан емес, әрқашан кілттен алыңыз.
iss ортаңыздың эмитентімен дәл сәйкес келуі керек. Оны конфигурацияңызда бекітіңіз; ешқашан токеннен оқымаңыз.
aud API-ыңыздың идентификаторын қамтуы керек. (openid ауқымымен онда ортаңыздың userinfo мекенжайы да көрсетіледі.)
Тақырыптағы typ мәні at+jwt болуы керек, сонда ID токенін қатынас токені ретінде өткізу мүмкін болмайды.
exp әлі өтпеген болуы керек. Қатынас токендері 10 минут жарамды; SDK-лар оларды сіз үшін жаңартады.

Node.js ортасында мұның бәрін @usher/node жасайды:

TypeScript

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 ортасында:

csharp

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

Токен не айтады

Талап
`sub`	Адам. `iss` мәнімен бірге — оны сақтайтын кілт.
`client_id`, `azp`	Сұраған қолданба.
`scope`	Адам қолданбаға не істеуге келіскені.
`email`, `email_verified`	`email` ауқымымен: адамның мекенжайы және Usher оның сол адамдікі екенін дәлелдегені.
`sid`	Адамның кіру сеансы.
`org`	`organization` ауқымымен: адамның белсенді ұйымы мен рөлі.

Бұрыннан танитын адамдар

Егер API-ыңызда бұрыннан аккаунттар болса, адам Usher токенімен алғаш келгенде оның аккаунтын таба аласыз: оны email бойынша іздеңіз, тек email_verified мәні true болғанда, және содан бастап оның аккаунтында iss пен sub мәндерін сақтаңыз. Одан кейін оны электрондық пошта бойынша емес, әрқашан iss пен sub бойынша табыңыз: мекенжай басқа адамға өтуі мүмкін, ал субъект ешқашан өтпейді.