Vaše vlastné API

Aplikácia si môže vyžiadať prístupový token pre jedno z vašich API. Dostane podpísaný JWT, ktorého príjemcom (audience) je toto API a nič iné, a vaše API ho overí zverejnenými kľúčmi vášho prostredia bez volania služby Usher. Token pre jedno API je pri inom bezcenný.

Pomenujte API

V Usher Console otvorte prostredie a potom Aplikácie → Vaše API → Pridať API. Zadajte názov a identifikátor: adresu https://, napríklad https://api.example.com, alebo URN, napríklad urn:example:api:notes. Identifikátor je to, o čo aplikácia žiada a čo uvádza nárok aud v tokene (RFC 8707).

Potom API priraďte aplikáciám, ktoré ho volajú: API pri každej aplikácii. Aplikácia dostane tokeny len pre API, ktoré má priradené, nech žiada o čokoľvek. Keď API odstránite, prestane dostávať tokeny; tie, ktoré už boli vydané, do niekoľkých minút vypršia.

Vyžiadajte si ho

Aplikácia pridá resource=<identifier> do svojej autorizačnej požiadavky aj do požiadaviek na token. Mobilné SDK to urobia 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")))

Aplikácia, ktorá volá dve z vašich API, si môže vyžiadať obe naraz; príjemcovia tokenu potom uvádzajú obe.

Overte ho vo svojom API

Token v každej požiadavke overte skôr, než čomukoľvek v ňom uveríte:

Podpis voči kľúčom na jwks_uri v dokumente zisťovania vášho prostredia. Algoritmus berte z kľúča, nikdy z hlavičky tokenu.
iss je presne vydavateľ vášho prostredia. Zadajte ho napevno v konfigurácii; nikdy ho nečítajte z tokenu.
aud obsahuje identifikátor vášho API. (S rozsahom openid uvádza aj adresu userinfo vášho prostredia.)
typ v hlavičke je at+jwt, takže token ID sa nedá vydávať za prístupový token.
exp ešte neuplynul. Prístupové tokeny platia 10 minút; SDK ich obnovujú za vás.

V Node.js to všetko urobí @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"],
        };
    });

Čo token obsahuje

Nárok
`sub`	Človek. Spolu s `iss` je to kľúč, podľa ktorého ho evidujete.
`client_id`, `azp`	Aplikácia, ktorá o token požiadala.
`scope`	Čo človek aplikácii dovolil robiť.
`email`, `email_verified`	S rozsahom `email`: adresa človeka a informácia, či Usher overil, že patrí jemu.
`sid`	Jeho prihlasovacia relácia.
`org`	S rozsahom `organization`: jeho aktívna organizácia a rola.

Ľudia, ktorých už poznáte

Ak vaše API už má účty z minulosti, účet človeka môžete nájsť pri jeho prvom príchode s tokenom Usher: vyhľadajte ho podľa email, len keď je email_verified rovné true, a odvtedy si pri jeho účte uchovávajte iss a sub. Potom ho hľadajte podľa iss a sub, nikdy podľa e-mailu: adresa môže zmeniť majiteľa, subjekt nikdy.