Dine egne API-er

En app kan be om et tilgangstoken for et av API-ene dine. Den får en signert JWT med det API-et som mottaker og ingenting annet, og API-et sjekker den med miljøets publiserte nøkler, uten å kalle Usher. Et token for ett API er ubrukelig hos et annet.

Gi API-et et navn

I Usher Console åpner du miljøet og deretter Apper → Dine API-er → Legg til et API. Gi det et navn og en identifikator: en https://-adresse, som https://api.example.com, eller en URN, som urn:example:api:notes. Identifikatoren er det appen ber om, og det tokenets aud-krav sier (RFC 8707).

Gi deretter API-et til appene som kaller det: API-er på hver app. En app får bare tokener for API-ene den har fått, uansett hva den ber om. Fjerner du et API, gir det ingen flere tokener; de som allerede er utstedt, utløper i løpet av minutter.

Be om det

Appen legger til resource=<identifier> i autorisasjonsforespørselen og tokenforespørslene sine. Mobil-SDK-ene gjør dette for deg:

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 kaller to av API-ene dine, kan be om begge på én gang; da oppgir tokenet begge som mottakere.

Sjekk det i API-et ditt

Sjekk tokenet i hver forespørsel før du stoler på noe i det:

Signaturen, mot nøklene på jwks_uri i miljøets discovery-dokument. Ta algoritmen fra nøkkelen, aldri fra tokenets header.
iss er nøyaktig miljøets utsteder. Fastsett den i konfigurasjonen din; les den aldri fra tokenet.
aud inneholder API-ets identifikator. (Med omfanget openid oppgir den også miljøets userinfo-adresse.)
typ i headeren er at+jwt, så et ID-token ikke kan utgis for å være et tilgangstoken.
exp har ikke passert. Tilgangstokener varer i 10 minutter; SDK-ene fornyer dem for deg.

I Node.js gjør @usher/node alt dette:

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

Hva tokenet sier

Krav
`sub`	Personen. Sammen med `iss` er det nøkkelen du lagrer dem under.
`client_id`, `azp`	Appen som spurte.
`scope`	Det personen har godtatt at appen kan gjøre.
`email`, `email_verified`	Med omfanget `email`: personens adresse, og om Usher har bekreftet at den er deres.
`sid`	Påloggingsøkten deres.
`org`	Med omfanget `organization`: den aktive organisasjonen og rollen deres.

Folk du allerede kjenner

Hvis API-et ditt allerede har kontoer fra før, kan du finne en persons konto første gang den kommer med et Usher-token: slå opp på email, bare når email_verified er true, og lagre iss og sub på kontoen fra da av. Etter det finner du dem på iss og sub, aldri på e-post: en adresse kan skifte eier, det gjør aldri et subjekt.