Twoje własne API

Aplikacja może poprosić o token dostępu do jednego z Twoich API. Dostaje podpisany token JWT, którego odbiorcą (audience) jest to API i nic poza nim, a Twoje API sprawdza go opublikowanymi kluczami Twojego środowiska, bez wywoływania Usher. Token dla jednego API jest bezużyteczny w innym.

Nazwij API

W Usher Console otwórz środowisko, a następnie wybierz Aplikacje → Twoje API → Dodaj API. Nadaj mu nazwę i identyfikator: adres https://, taki jak https://api.example.com, albo URN, taki jak urn:example:api:notes. O ten identyfikator prosi aplikacja i to on znajduje się w oświadczeniu aud tokenu (RFC 8707).

Następnie przydziel API aplikacjom, które je wywołują: sekcja API w każdej aplikacji. Aplikacja dostaje tokeny tylko do przydzielonych jej API, niezależnie od tego, o co prosi. Gdy usuniesz API, nie będą wydawane kolejne tokeny, a te już wydane wygasną w ciągu kilku minut.

Poproś o token

Aplikacja dodaje resource=<identifier> do żądania autoryzacji i do żądań tokenów. Mobilne SDK robią to za Ciebie:

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

Aplikacja, która wywołuje dwa Twoje API, może poprosić o oba naraz; wtedy oba znajdą się na liście odbiorców tokenu.

Sprawdź token w swoim API

Sprawdzaj token każdego żądania, zanim zaufasz czemukolwiek, co zawiera:

Podpis, kluczami spod jwks_uri w dokumencie wykrywania Twojego środowiska. Algorytm bierz z klucza, nigdy z nagłówka tokenu.
iss to dokładnie wystawca Twojego środowiska. Ustal go w konfiguracji; nigdy nie odczytuj go z tokenu.
aud zawiera identyfikator Twojego API. (Z zakresem openid zawiera też adres userinfo Twojego środowiska).
typ w nagłówku ma wartość at+jwt, więc tokenu ID nie da się podsunąć jako tokenu dostępu.
exp jeszcze nie minął. Tokeny dostępu są ważne przez 10 minut; SDK odświeżają je za Ciebie.

W Node.js wszystko to robi @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

W 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 zawiera token

Oświadczenie
`sub`	Dana osoba. Razem z `iss` stanowi klucz, pod którym ją przechowujesz.
`client_id`, `azp`	Aplikacja, która poprosiła o token.
`scope`	To, na co ta osoba pozwoliła aplikacji.
`email`, `email_verified`	Z zakresem `email`: adres tej osoby i informacja, czy Usher potwierdził, że należy do niej.
`sid`	Jej sesja logowania.
`org`	Z zakresem `organization`: jej aktywna organizacja i rola.

Osoby, które już znasz

Jeśli Twoje API ma już wcześniejsze konta, możesz znaleźć konto danej osoby, gdy po raz pierwszy przyjdzie z tokenem Usher: wyszukaj je po email, tylko gdy email_verified ma wartość true, i od tej pory przechowuj na tym koncie iss i sub. Później szukaj tej osoby po iss i sub, nigdy po adresie e-mail: adres może zmienić właściciela, a identyfikator podmiotu nigdy.