Saját API-k

Egy app hozzáférési tokent kérhet valamelyik API-dhoz. Egy aláírt JWT-t kap, amelynek a célközönsége az az API és semmi más, az API-d pedig a környezeted közzétett kulcsaival ellenőrzi, az Usher hívása nélkül. Az egyik API-hoz szóló token egy másiknál használhatatlan.

Nevezd meg az API-t

Az Usher Console-ban nyisd meg a környezetet, majd válaszd az Alkalmazások → Saját API-k → API hozzáadása lehetőséget. Adj neki egy nevet és egy azonosítót: egy https:// címet, például https://api.example.com, vagy egy URN-t, például urn:example:api:notes. Az azonosító az, amit az app kér, és amit a token aud mezője tartalmaz (RFC 8707).

Ezután add meg az API-t azoknak az appoknak, amelyek hívják: ehhez mindegyik alkalmazásnál ott az API-k gomb. Egy app csak azokhoz az API-khoz kap tokent, amelyeket megkapott, bármit kér is. Ha eltávolítasz egy API-t, ahhoz nem ad ki több tokent; a már kiadottak perceken belül lejárnak.

Kérd el

Az app hozzáadja a resource=<identifier> paramétert az engedélyezési és a tokenkéréseihez. A mobil SDK-k ezt elvégzik helyetted:

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

Egy app, amely két API-dat is hívja, egyszerre kérheti mindkettőt; a token célközönsége ekkor mindkettőt felsorolja.

Ellenőrizd az API-dban

Minden kérés tokenjét ellenőrizd, mielőtt bármit elhinnél, ami benne áll:

• Az aláírást a környezeted felderítési dokumentumában szereplő jwks_uri címen elérhető kulcsokkal. Az algoritmust a kulcsból vedd, soha ne a token fejlécéből.
• Az iss pontosan a környezeted kibocsátója. Rögzítsd a konfigurációdban; soha ne a tokenből olvasd ki.
• Az aud tartalmazza az API-d azonosítóját. (Az openid hatókörrel a környezeted userinfo címét is felsorolja.)
• A typ értéke a fejlécben at+jwt, így egy ID-tokent nem lehet hozzáférési tokennek kiadni.
• Az exp még nem járt le. A hozzáférési tokenek 10 percig érvényesek; az SDK-k helyetted frissítik őket.

Node.js-ben a @usher/node mindezt elvégzi:

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

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 tartalmaz a token

Akiket már ismersz

Ha az API-dnak korábbról már vannak fiókjai, egy személy fiókját akkor találhatod meg, amikor először érkezik Usher-tokennel: keresd meg az email alapján, de csak akkor, ha az email_verified értéke true, és onnantól tárold az iss és a sub értékét a fiókján. Ezután az iss és a sub alapján keresd, soha ne e-mail-cím alapján: egy cím gazdát cserélhet, egy subject soha.