As suas próprias APIs

Um app pode pedir um token de acesso para uma das suas APIs. Ele recebe um JWT assinado cujo público-alvo é essa API e nada mais, e a sua API o verifica com as chaves publicadas do seu ambiente, sem chamar o Usher. Um token para uma API não serve em outra.

Dê um nome à API

No Usher Console, abra o ambiente e vá em Aplicações → Suas APIs → Adicionar uma API. Dê a ela um nome e um identificador: um endereço https://, como https://api.example.com, ou uma URN, como urn:example:api:notes. O identificador é o que o app pede e o que diz a claim aud do token (RFC 8707).

Depois, conceda a API aos apps que a chamam: APIs, em cada aplicação. Um app só recebe tokens para as APIs que lhe foram concedidas, não importa o que ele peça. Se você remover uma API, nenhum token novo é emitido para ela; os que já foram emitidos expiram em poucos minutos.

Peça o token

O app adiciona resource=<identifier> à requisição de autorização e às requisições de token. Os SDKs para dispositivos móveis fazem isso por você:

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")))

Um app que chama duas das suas APIs pode pedir as duas de uma vez; o público-alvo do token passa então a listar as duas.

Verifique o token na sua API

Verifique o token de cada requisição antes de confiar em qualquer coisa que ele contenha:

• A assinatura, com as chaves do jwks_uri no documento de descoberta do seu ambiente. Use o algoritmo indicado pela chave, nunca o do cabeçalho do token.
• iss é exatamente o emissor do seu ambiente. Fixe esse valor na sua configuração; nunca o leia do token.
• aud inclui o identificador da sua API. (Com o escopo openid, ele também lista o endereço de userinfo do seu ambiente.)
• typ, no cabeçalho, é at+jwt, para que um token de ID não possa se passar por um token de acesso.
• exp ainda não passou. Os tokens de acesso duram 10 minutos; os SDKs os renovam para você.

No Node.js, o @usher/node faz tudo isso:

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

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

O que o token diz

Pessoas que você já conhece

Se a sua API já tem contas de antes, você pode encontrar a conta de uma pessoa na primeira vez em que ela chegar com um token do Usher: procure pelo email, somente quando email_verified for true, e, a partir daí, guarde iss e sub na conta dela. Depois disso, encontre a pessoa por iss e sub, nunca pelo e-mail: um endereço pode mudar de dono; um subject, nunca.