Vaši vlastiti API-ji

Aplikacija može zatražiti pristupni token za neki od vaših API-ja. Dobiva potpisani JWT čija je publika taj API i ništa drugo, a vaš ga API provjerava objavljenim ključevima vašeg okruženja, bez pozivanja platforme Usher. Token za jedan API ne vrijedi ni za koji drugi.

Imenujte API

U sučelju Usher Console otvorite okruženje, a zatim Aplikacije → Vaši API-ji → Dodaj API. Dajte mu naziv i identifikator: adresu https://, kao što je https://api.example.com, ili URN, kao što je urn:example:api:notes. Identifikator je ono što aplikacija traži i ono što navodi tvrdnja aud u tokenu (RFC 8707).

Zatim API dodijelite aplikacijama koje ga pozivaju: API-ji na svakoj aplikaciji. Aplikacija dobiva tokene samo za API-je koji su joj dodijeljeni, što god tražila. Uklonite li API, on više ne daje tokene; oni koji su već izdani istječu za nekoliko minuta.

Zatražite ga

Aplikacija dodaje resource=<identifier> svojem zahtjevu za autorizaciju i zahtjevima za token. Mobilni SDK-ovi to rade umjesto 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 koja poziva dva vaša API-ja može zatražiti oba odjednom; publika tokena tada navodi oba.

Provjerite ga u svojem API-ju

Provjerite token svakog zahtjeva prije nego što povjerujete bilo čemu u njemu:

Potpis, prema ključevima na adresi jwks_uri u dokumentu za otkrivanje vašeg okruženja. Algoritam uzmite iz ključa, nikad iz zaglavlja tokena.
iss je točno izdavatelj vašeg okruženja. Fiksirajte ga u konfiguraciji; nikad ga ne čitajte iz tokena.
aud uključuje identifikator vašeg API-ja. (Uz opseg openid navodi i adresu userinfo vašeg okruženja.)
typ u zaglavlju je at+jwt, kako se ID token ne bi mogao podmetnuti kao pristupni token.
exp nije prošao. Pristupni tokeni traju 10 minuta; SDK-ovi ih osvježavaju umjesto vas.

U okruženju Node.js sve to obavlja @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

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

Što token govori

Tvrdnja
`sub`	Osoba. Zajedno s `iss` ključ je po kojem je pamtite.
`client_id`, `azp`	Aplikacija koja je zatražila token.
`scope`	Ono za što je osoba pristala da aplikacija smije raditi.
`email`, `email_verified`	Uz opseg `email`: adresa osobe i podatak je li Usher potvrdio da je njezina.
`sid`	Njezina sesija prijave.
`org`	Uz opseg `organization`: njezina aktivna organizacija i uloga.

Ljudi koje već poznajete

Ako vaš API već ima račune od prije, račun neke osobe možete pronaći kad prvi put stigne s Usher tokenom: potražite je po email, samo kad je email_verified jednako true, i od tada na njezinu računu čuvajte iss i sub. Nakon toga pronalazite je po iss i sub, nikad po adresi e-pošte: adresa može promijeniti vlasnika, a subjekt nikad.