Ваші власні 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, а ніколи не за електронною поштою: адреса може перейти до іншої людини, а суб’єкт — ніколи.