Vaši API-ji

Aplikacija lahko zahteva žeton za dostop do enega od vaših API-jev. Dobi podpisan JWT, katerega občinstvo je ta API in nič drugega, vaš API pa ga preveri z objavljenimi ključi vašega okolja, ne da bi klical Usher. Žeton za en API pri drugem ni uporaben.

Poimenujte API

V Usher Console odprite okolje, nato Aplikacije → Vaši API-ji → Dodaj API. Dajte mu ime in identifikator: naslov https://, na primer https://api.example.com, ali URN, na primer urn:example:api:notes. Identifikator je tisto, kar aplikacija zahteva, in tisto, kar navaja trditev aud v žetonu (RFC 8707).

Nato API dodelite aplikacijam, ki ga kličejo: API-ji pri vsaki aplikaciji. Aplikacija dobi žetone samo za API-je, ki so ji bili dodeljeni, ne glede na to, kaj zahteva. Če API odstranite, ne izdaja več žetonov; tistim, ki so že izdani, veljavnost poteče v nekaj minutah.

Zahtevajte ga

Aplikacija svoji avtorizacijski zahtevi in zahtevam za žetone doda resource=<identifier>. Mobilni SDK-ji to naredijo namesto vas:

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

Aplikacija, ki kliče dva vaša API-ja, lahko zahteva oba hkrati; občinstvo žetona nato navaja oba.

Preverite ga v svojem API-ju

Žeton vsake zahteve preverite, preden zaupate čemur koli v njem:

Podpis, s ključi na jwks_uri v dokumentu za odkrivanje vašega okolja. Algoritem vzemite iz ključa, nikoli iz glave žetona.
iss je natanko izdajatelj vašega okolja. Določite ga v svoji konfiguraciji; nikoli ga ne berite iz žetona.
aud vključuje identifikator vašega API-ja. (Z obsegom openid navaja tudi naslov userinfo vašega okolja.)
typ v glavi je at+jwt, zato žetona ID ni mogoče podtakniti kot žeton za dostop.
exp še ni potekel. Žetoni za dostop veljajo 10 minut; SDK-ji jih osvežijo namesto vas.

V Node.js vse to naredi @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"],
        };
    });

Kaj pove žeton

Trditev
`sub`	Oseba. Skupaj z `iss` ključ, po katerem jo hranite.
`client_id`, `azp`	Aplikacija, ki je zahtevala žeton.
`scope`	Kaj je oseba dovolila aplikaciji.
`email`, `email_verified`	Z obsegom `email`: naslov osebe in ali je Usher dokazal, da je njen.
`sid`	Njena seja prijave.
`org`	Z obsegom `organization`: njena aktivna organizacija in vloga.

Ljudje, ki jih že poznate

Če ima vaš API že račune od prej, lahko račun osebe najdete, ko prvič pride z žetonom Usher: poiščite jo po email, samo če je email_verified enako true, in od takrat naprej pri njenem računu hranite iss in sub. Potem jo iščite po iss in sub, nikoli po e-pošti: naslov lahko zamenja lastnika, subjekt pa nikoli.