Jūsų API

Programa gali paprašyti prieigos žetono vienai iš jūsų API. Ji gauna pasirašytą JWT, kurio auditorija yra tik ta API, o jūsų API jį patikrina jūsų aplinkos paskelbtais raktais, nesikreipdama į Usher. Vienai API skirtas žetonas kitai netinka.

Pavadinkite API

Usher Console atidarykite aplinką, tada Programos → Jūsų API → Pridėti API. Suteikite jai pavadinimą ir identifikatorių: https:// adresą, pavyzdžiui, https://api.example.com, arba URN, pavyzdžiui, urn:example:api:notes. Identifikatorius – tai, ko prašo programa, ir tai, ką nurodo žetono teiginys aud (RFC 8707).

Tada priskirkite API ją kviečiančioms programoms: kiekvienos programos skiltyje API. Programa gauna žetonus tik toms API, kurios jai priskirtos, kad ir ko ji prašytų. Pašalinkite API, ir ji nebeduos žetonų; jau išduotieji nustos galioti per kelias minutes.

Paprašykite jo

Programa prideda resource=<identifier> prie savo autorizacijos užklausos ir žetonų užklausų. Mobilieji SDK tai padaro už jus:

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

Programa, kviečianti dvi jūsų API, gali paprašyti abiejų iš karto; tada žetono auditorijoje nurodomos abi.

Patikrinkite jį savo API

Patikrinkite kiekvienos užklausos žetoną, prieš pasitikėdami bet kuo, kas jame yra:

Parašą – pagal raktus, esančius jwks_uri jūsų aplinkos aptikimo dokumente. Algoritmą imkite iš rakto, niekada iš žetono antraštės.
iss turi tiksliai sutapti su jūsų aplinkos išdavėju. Nustatykite jį savo konfigūracijoje; niekada neskaitykite jo iš žetono.
aud turi apimti jūsų API identifikatorių. (Su aprėptimi openid joje taip pat nurodomas jūsų aplinkos userinfo adresas.)
typ antraštėje turi būti at+jwt, kad ID žetono nebūtų galima pateikti kaip prieigos žetono.
exp dar neturi būti praėjęs. Prieigos žetonai galioja 10 minučių; SDK juos atnaujina už jus.

Node.js aplinkoje visa tai atlieka @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

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

Ką nurodo žetonas

Teiginys
`sub`	Žmogus. Kartu su `iss` – raktas, pagal kurį jį saugoti.
`client_id`, `azp`	Programa, kuri paprašė.
`scope`	Ką žmogus sutiko leisti programai daryti.
`email`, `email_verified`	Su aprėptimi `email`: žmogaus adresas ir ar Usher įrodė, kad jis priklauso jam.
`sid`	Žmogaus prisijungimo sesija.
`org`	Su aprėptimi `organization`: žmogaus aktyvi organizacija ir vaidmuo.

Žmonės, kuriuos jau pažįstate

Jei jūsų API jau turi paskyrų iš anksčiau, žmogaus paskyrą galite rasti, kai jis pirmą kartą ateina su Usher žetonu: ieškokite pagal email, tik kai email_verified yra true, ir nuo tada saugokite iss bei sub jo paskyroje. Po to ieškokite jo pagal iss ir sub, niekada pagal el. pašto adresą: adresas gali pereiti kitam žmogui, o subjektas – niekada.