Vaše vlastní API

Aplikace může požádat o přístupový token pro jedno z vašich API. Dostane podepsaný JWT, jehož příjemcem (audience) je právě toto API a nic jiného, a vaše API ho ověří zveřejněnými klíči vašeho prostředí, aniž by volalo Usher. Token pro jedno API je v jiném k ničemu.

Pojmenujte API

V Usher Console otevřete prostředí a pak Aplikace → Vaše API → Přidat API. Zadejte název a identifikátor: adresu https://, například https://api.example.com, nebo URN, například urn:example:api:notes. Identifikátor je to, o co aplikace žádá a co uvádí deklarace aud tokenu (RFC 8707).

Pak API přidělte aplikacím, které ho volají: tlačítkem API u každé aplikace. Aplikace dostane tokeny jen pro API, která jí byla přidělena, ať žádá o cokoli. Když API odeberete, už žádné tokeny nevydá; ty, které už jsou venku, během několika minut vyprší.

Požádejte o něj

Aplikace přidá resource=<identifier> do svého autorizačního požadavku i do požadavků na token. Mobilní sady SDK to udělají za vás:

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

Aplikace, která volá dvě z vašich API, může požádat o obě najednou; příjemci tokenu pak uvádějí obě.

Zkontrolujte ho ve svém API

Než čemukoli v tokenu uvěříte, zkontrolujte ho u každého požadavku:

Podpis, proti klíčům na jwks_uri z dokumentu discovery vašeho prostředí. Algoritmus berte z klíče, nikdy z hlavičky tokenu.
iss je přesně vydavatel vašeho prostředí. Zadejte ho napevno do konfigurace; nikdy ho nečtěte z tokenu.
aud obsahuje identifikátor vašeho API. (S rozsahem openid uvádí i adresu userinfo vašeho prostředí.)
typ v hlavičce je at+jwt, takže ID token nejde vydávat za přístupový token.
exp ještě nenastal. Přístupové tokeny platí 10 minut; sady SDK je za vás obnovují.

V Node.js to všechno zvládne @usher/node:

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

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

Co token říká

Deklarace
`sub`	Daný člověk. Spolu s `iss` klíč, pod kterým ho evidovat.
`client_id`, `azp`	Aplikace, která o token požádala.
`scope`	Co člověk aplikaci povolil.
`email`, `email_verified`	S rozsahem `email`: adresa daného člověka a informace, jestli Usher ověřil, že patří jemu.
`sid`	Jeho přihlašovací relace.
`org`	S rozsahem `organization`: jeho aktivní organizace a role.

Lidé, které už znáte

Pokud vaše API už má účty z dřívějška, můžete daného člověka najít, když poprvé přijde s tokenem Usher: vyhledejte ho podle email, jen když je email_verified rovno true, a od té doby si u jeho účtu uchovávejte iss a sub. Potom ho vyhledávejte podle iss a sub, nikdy podle e-mailu: adresa může změnit majitele, subjekt nikdy.