As suas próprias APIs

Uma app pode pedir um token de acesso para uma das suas APIs. Recebe um JWT assinado cuja audiência é essa API e mais nenhuma, e a sua API verifica-o com as chaves publicadas do seu ambiente, sem chamar o Usher. Um token para uma API não serve de nada noutra.

Dê um nome à API

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

Depois, atribua a API às apps que a chamam: APIs, em cada aplicação. Uma app só recebe tokens para as APIs que lhe foram atribuídas, peça o que pedir. Remova uma API e ela deixa de dar tokens; os que já foram emitidos expiram em poucos minutos.

Peça-a

A app acrescenta resource=<identifier> ao seu pedido de autorização e aos seus pedidos de token. Os SDKs móveis fazem-no por si:

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

Uma app que chama duas das suas APIs pode pedir ambas de uma vez; a audiência do token passa então a indicar as duas.

Verifique-o na sua API

Verifique o token de cada pedido antes de confiar no que quer que seja que ele contenha:

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

Em Node.js, o @usher/node faz tudo isto:

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

Em 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 já conhece

Se a sua API já tinha contas antes, pode encontrar a de uma pessoa da primeira vez que ela chega com um token do Usher: procure-a por email, só quando email_verified for true, e guarde iss e sub na conta dela a partir daí. Depois disso, encontre-a por iss e sub, nunca pelo e-mail: um endereço pode mudar de dono, e um sujeito nunca muda.