API-urile dvs.

O aplicație poate cere un token de acces pentru unul dintre API-urile dvs. Primește un JWT semnat a cărui audiență este acel API și nimic altceva, iar API-ul dvs. îl verifică cu cheile publicate ale mediului, fără să apeleze Usher. Un token pentru un API nu folosește la nimic la altul.

Denumiți API-ul

În Usher Console, deschideți mediul, apoi Aplicații → API-urile dvs. → Adăugați un API. Dați-i un nume și un identificator: o adresă https://, cum ar fi https://api.example.com, sau un URN, cum ar fi urn:example:api:notes. Identificatorul este ce cere aplicația și ce spune revendicarea aud a tokenului (RFC 8707).

Apoi dați API-ul aplicațiilor care îl apelează: API-uri, la fiecare aplicație. O aplicație primește tokenuri doar pentru API-urile care i-au fost date, orice ar cere. Dacă eliminați un API, nu se mai emit tokenuri pentru el; cele deja emise expiră în câteva minute.

Cereți-l

Aplicația adaugă resource=<identifier> la cererea de autorizare și la cererile de tokenuri. SDK-urile mobile fac asta pentru dvs.:

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>

val usher = Usher.client(context, UsherConfiguration(
    issuer = "https://login.example.com",
    clientId = "…",
    redirectUri = "com.example.notes:/oauth/callback",
    resources = listOf("urn:example:api:notes")))

O aplicație care apelează două dintre API-urile dvs. le poate cere pe amândouă deodată; audiența tokenului le listează atunci pe amândouă.

Verificați-l în API-ul dvs.

Verificați tokenul fiecărei cereri înainte să aveți încredere în ceva din el:

• Semnătura, cu cheile de la jwks_uri din documentul de descoperire al mediului. Luați algoritmul din cheie, niciodată din antetul tokenului.
• iss este exact emitentul mediului. Fixați-l în configurație; nu-l citiți niciodată din token.
• aud include identificatorul API-ului dvs. (Cu scope-ul openid, listează și adresa userinfo a mediului.)
• typ din antet este at+jwt, ca un token ID să nu poată fi dat drept token de acces.
• exp nu a trecut. Tokenurile de acces sunt valabile 10 minute; SDK-urile le reîmprospătează pentru dvs.

În Node.js, @usher/node face toate acestea:

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

În ASP.NET Core:

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

Ce spune tokenul

Persoane pe care le cunoașteți deja

Dacă API-ul dvs. are deja conturi de dinainte, puteți găsi contul unei persoane prima dată când sosește cu un token Usher: căutați-o după email, doar când email_verified este true, și păstrați de atunci încolo iss și sub în contul ei. După aceea, găsiți-o după iss și sub, niciodată după adresa de e-mail: o adresă poate ajunge la altcineva, un subiect niciodată.