Вашите собствени API

Приложението може да поиска токен за достъп за някой от вашите API. То получава подписан JWT, чиято аудитория е този API и нищо друго, а вашият API го проверява с публикуваните ключове на средата ви, без да се обръща към Usher. Токен за един API е безполезен за друг.

Назовете API

В Usher Console отворете средата, след това Приложения → Вашите API → Добавяне на API. Дайте му име и идентификатор: адрес https://, например https://api.example.com, или URN, например urn:example:api:notes. Идентификаторът е това, което приложението иска, и това, което казва claim 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

Проверявайте токена при всяка заявка, преди да се доверите на каквото и да е в него:

Подписа – спрямо ключовете на 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"],
        };
    });

Какво казва токенът

Claim
`sub`	Човекът. Заедно с `iss` – ключът, по който да го пазите.
`client_id`, `azp`	Приложението, което е поискало токена.
`scope`	Какво човекът се е съгласил, че приложението може да прави.
`email`, `email_verified`	С обхвата `email`: адресът на човека и дали Usher е доказал, че е негов.
`sid`	Сесията му за вход.
`org`	С обхвата `organization`: активната му организация и ролята му в нея.

Хора, които вече познавате

Ако вашият API вече има акаунти отпреди, можете да намерите акаунта на даден човек първия път, когато пристигне с токен от Usher: потърсете го по email, само когато email_verified е true, и от този момент пазете iss и sub в акаунта му. След това го намирайте по iss и sub, никога по имейл: един адрес може да смени собственика си, а субектът – никога.