Omat API:t

Sovellus voi pyytää käyttöoikeustunnusta johonkin API:istasi. Se saa allekirjoitetun JWT:n, jonka yleisö (audience) on se API eikä mikään muu, ja API:si tarkistaa sen ympäristösi julkaistuilla avaimilla kutsumatta Usheria. Yhden API:n tunnus ei kelpaa toiseen.

Nimeä API

Avaa Usher Consolessa ympäristö ja sitten Sovellukset → Omat API:t → Lisää API. Anna sille nimi ja tunniste: https://-osoite, kuten https://api.example.com, tai URN, kuten urn:example:api:notes. Tunniste on se, mitä sovellus pyytää, ja se, mitä tunnuksen aud-väite sanoo (RFC 8707).

Anna API sitten sovelluksille, jotka kutsuvat sitä: kunkin sovelluksen kohta API:t. Sovellus saa tunnuksia vain niihin API:ihin, jotka sille on annettu, pyysipä se mitä tahansa. Jos poistat API:n, se ei anna enää tunnuksia; jo annetut vanhenevat minuuteissa.

Pyydä sitä

Sovellus lisää resource=<identifier> valtuutuspyyntöönsä ja tunnuspyyntöihinsä. Mobiili-SDK:t tekevät tämän puolestasi:

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

Sovellus, joka kutsuu kahta API:istasi, voi pyytää molempia kerralla; tunnuksen yleisössä luetellaan silloin molemmat.

Tarkista se API:ssasi

Tarkista jokaisen pyynnön tunnus, ennen kuin luotat mihinkään sen sisältöön:

Allekirjoitus ympäristösi discovery-dokumentin jwks_uri-osoitteen avaimia vasten. Ota algoritmi avaimesta, älä koskaan tunnuksen otsakkeesta.
iss on täsmälleen ympäristösi myöntäjä. Kiinnitä se määrityksiisi; älä koskaan lue sitä tunnuksesta.
aud sisältää API:si tunnisteen. (Käyttöalueen openid kanssa siinä on myös ympäristösi userinfo-osoite.)
typ otsakkeessa on at+jwt, jotta ID-tunnusta ei voi esittää käyttöoikeustunnuksena.
exp ei ole mennyt. Käyttöoikeustunnukset ovat voimassa 10 minuuttia; SDK:t päivittävät ne puolestasi.

Node.js:ssä @usher/node hoitaa kaiken tämän:

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 Coressa:

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

Mitä tunnus kertoo

Väite
`sub`	Ihminen. Yhdessä `iss`-arvon kanssa avain, jolla hänet tunnistetaan jatkossa.
`client_id`, `azp`	Sovellus, joka pyysi tunnusta.
`scope`	Mitä ihminen suostui sovelluksen tekevän.
`email`, `email_verified`	Käyttöalueen `email` kanssa: ihmisen osoite ja tieto siitä, onko Usher todentanut sen hänen omakseen.
`sid`	Hänen kirjautumisistuntonsa.
`org`	Käyttöalueen `organization` kanssa: hänen aktiivinen organisaationsa ja roolinsa.

Ihmiset, jotka jo tunnet

Jos API:llasi on jo aiempia tilejä, voit löytää ihmisen tilin, kun hän saapuu ensimmäistä kertaa Usher-tunnuksen kanssa: hae häntä email-arvolla, vain kun email_verified on true, ja tallenna siitä lähtien iss ja sub hänen tiliinsä. Sen jälkeen etsi häntä iss- ja sub-arvoilla, älä koskaan sähköpostiosoitteella: osoite voi vaihtaa omistajaa, mutta sub ei koskaan vaihdu.