Dine egne API’er

En app kan bede om et adgangstoken til et af dine API’er. Den får et signeret JWT, hvis målgruppe er det API og intet andet, og dit API tjekker det med dit miljøs offentliggjorte nøgler uden at kalde Usher. Et token til ét API kan ikke bruges til et andet.

Navngiv API’et

Åbn miljøet i Usher Console, og vælg derefter Applikationer → Dine API’er → Tilføj et API. Giv det et navn og en identifikator: en https://-adresse, f.eks. https://api.example.com, eller en URN, f.eks. urn:example:api:notes. Identifikatoren er det, appen beder om, og det, tokenets aud-claim angiver (RFC 8707).

Giv derefter API’et til de apps, der kalder det: API’er på hver applikation. En app får kun tokens til de API’er, den har fået, uanset hvad den beder om. Fjerner du et API, giver det ikke flere tokens; dem, der allerede er udstedt, udløber inden for få minutter.

Bed om det

Appen tilføjer resource=<identifier> til sin autorisationsanmodning og sine tokenanmodninger. Mobil-SDK’erne gør det for dig:

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

En app, der kalder to af dine API’er, kan bede om begge på én gang; tokenets målgruppe angiver så dem begge.

Tjek det i dit API

Tjek tokenet i hver anmodning, før du stoler på noget af indholdet:

Signaturen, mod nøglerne på den jwks_uri, der står i dit miljøs discovery-dokument. Tag algoritmen fra nøglen, aldrig fra tokenets header.
iss er præcis dit miljøs udsteder. Lås den fast i din konfiguration; læs den aldrig fra tokenet.
aud indeholder dit API’s identifikator. (Med scopet openid angiver den også dit miljøs userinfo-adresse.)
typ i headeren er at+jwt, så et id-token ikke kan udgive sig for at være et adgangstoken.
exp er ikke passeret. Adgangstokens gælder i 10 minutter; SDK’erne fornyer dem for dig.

I Node.js klarer @usher/node det hele:

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

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

Hvad tokenet siger

Claim
`sub`	Personen. Sammen med `iss` den nøgle, du skal gemme personen under.
`client_id`, `azp`	Den app, der spurgte.
`scope`	Det, personen har givet appen lov til.
`email`, `email_verified`	Med scopet `email`: personens adresse, og om Usher har bevist, at den tilhører personen.
`sid`	Personens loginsession.
`org`	Med scopet `organization`: personens aktive organisation og rolle.

Folk, du allerede kender

Har dit API allerede konti fra tidligere, kan du finde en persons konto, første gang personen kommer med et Usher-token: slå op efter email, kun når email_verified er true, og gem iss og sub på kontoen fra da af. Find derefter personen efter iss og sub, aldrig efter e-mail: en adresse kan skifte ejer, det gør et subject aldrig.