Je eigen API’s

Een app kan een toegangstoken vragen voor een van je API’s. De app krijgt een ondertekend JWT met die API als audience en verder niets, en je API controleert het met de gepubliceerde sleutels van je omgeving, zonder Usher aan te roepen. Een token voor de ene API is bij een andere niets waard.

Registreer de API

Open in Usher Console de omgeving en kies Applicaties → Je API’s → Voeg een API toe. Geef de API een naam en een identifier: een https://-adres, zoals https://api.example.com, of een URN, zoals urn:example:api:notes. De identifier is waar de app om vraagt en wat de aud-claim van het token zegt (RFC 8707).

Geef de API daarna aan de apps die hem aanroepen: API’s bij elke applicatie. Een app krijgt alleen tokens voor de API’s die hij heeft gekregen, waar hij ook om vraagt. Haal je een API weg, dan worden er geen tokens meer voor uitgegeven; de tokens die al zijn uitgegeven, verlopen binnen enkele minuten.

Vraag erom

De app voegt resource=<identifier> toe aan zijn autorisatieverzoek en zijn tokenverzoeken. De mobiele SDK’s doen dit voor je:

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

Een app die twee van je API’s aanroept, kan om beide tegelijk vragen; de audience van het token noemt dan beide.

Controleer het in je API

Controleer bij elk verzoek het token voordat je iets vertrouwt wat erin staat:

De handtekening, tegen de sleutels op de jwks_uri in het discovery-document van je omgeving. Neem het algoritme van de sleutel, nooit uit de header van het token.
iss is precies de issuer van je omgeving. Leg die vast in je configuratie; lees hem nooit uit het token.
aud bevat de identifier van je API. (Met de scope openid staat ook het userinfo-adres van je omgeving erin.)
typ in de header is at+jwt, zodat een ID-token niet kan doorgaan voor een toegangstoken.
exp is nog niet verstreken. Toegangstokens zijn 10 minuten geldig; de SDK’s vernieuwen ze voor je.

In Node.js doet @usher/node dit allemaal:

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

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

Wat het token zegt

Claim
`sub`	De persoon. Samen met `iss` de sleutel waaronder je diegene bewaart.
`client_id`, `azp`	De app die erom vroeg.
`scope`	Wat de persoon de app heeft toegestaan.
`email`, `email_verified`	Met de scope `email`: het adres van de persoon, en of Usher heeft vastgesteld dat het echt van diegene is.
`sid`	De inlogsessie.
`org`	Met de scope `organization`: de actieve organisatie en rol.

Mensen die je al kent

Heeft je API al accounts van vroeger, dan kun je iemands account vinden de eerste keer dat diegene binnenkomt met een Usher-token: zoek op email, alleen als email_verified true is, en bewaar vanaf dan iss en sub bij het account. Daarna vind je iemand op iss en sub, nooit op e-mailadres: een adres kan van eigenaar wisselen, een subject nooit.