Dina egna API:er

En app kan be om en åtkomsttoken för ett av dina API:er. Den får en signerad JWT vars målgrupp är det API:et och inget annat, och ditt API kontrollerar den med din miljös publicerade nycklar, utan att anropa Usher. En token för ett API är oanvändbar hos ett annat.

Namnge API:et

Öppna miljön i Usher Console och välj sedan Appar → Dina API:er → Lägg till ett API. Ge det ett namn och en identifierare: en https://-adress, till exempel https://api.example.com, eller en URN, till exempel urn:example:api:notes. Identifieraren är det som appen ber om och det som tokenens aud-anspråk anger (RFC 8707).

Ge sedan API:et till apparna som anropar det: API:er på varje app. En app får bara tokens för de API:er den har fått, oavsett vad den ber om. Tar du bort ett API ger det inga fler tokens; de som redan har utfärdats går ut inom några minuter.

Be om det

Appen lägger till resource=<identifier> i sin auktoriseringsförfrågan och sina tokenförfrågningar. Mobil-SDK:erna gör det åt 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 som anropar två av dina API:er kan be om båda på en gång; tokenens målgrupp listar då båda.

Kontrollera den i ditt API

Kontrollera tokenen i varje förfrågan innan du litar på något i den:

Signaturen, mot nycklarna på den jwks_uri som finns i din miljös discovery-dokument. Ta algoritmen från nyckeln, aldrig från tokenens rubrik.
iss är exakt din miljös utfärdare. Ange den i din konfiguration; läs den aldrig från tokenen.
aud innehåller ditt API:s identifierare. (Med scopet openid listar den också din miljös userinfo-adress.)
typ i rubriken är at+jwt, så att en ID-token inte kan utges för att vara en åtkomsttoken.
exp har inte passerats. Åtkomsttokens gäller i 10 minuter; SDK:erna förnyar dem åt dig.

I Node.js gör @usher/node allt detta:

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

Vad tokenen säger

Anspråk
`sub`	Personen. Tillsammans med `iss` nyckeln att spara personen under.
`client_id`, `azp`	Appen som bad om tokenen.
`scope`	Vad personen har godkänt att appen får göra.
`email`, `email_verified`	Med scopet `email`: personens adress, och om Usher har bekräftat att den är personens.
`sid`	Personens inloggningssession.
`org`	Med scopet `organization`: personens aktiva organisation och roll.

Människor du redan känner

Om ditt API redan har konton sedan tidigare kan du hitta en persons konto första gången personen kommer med en token från Usher: slå upp kontot med email, bara när email_verified är true, och spara iss och sub på kontot från och med då. Hitta sedan personen med iss och sub, aldrig med e-postadressen: en adress kan byta ägare, men ett subjekt gör det aldrig.