API anda sendiri

Sesebuah aplikasi boleh meminta token akses untuk salah satu API anda. Ia mendapat JWT bertandatangan yang audiensnya ialah API itu dan tiada yang lain, dan API anda menyemaknya dengan kunci persekitaran anda yang diterbitkan, tanpa memanggil Usher. Token untuk satu API tidak berguna di API lain.

Namakan API

Dalam Usher Console, buka persekitaran, kemudian Aplikasi → API anda → Tambah API. Berikan nama dan pengecam: alamat https://, seperti https://api.example.com, atau URN, seperti urn:example:api:notes. Pengecam ialah apa yang diminta oleh aplikasi dan apa yang dinyatakan oleh tuntutan aud token itu (RFC 8707).

Kemudian berikan API itu kepada aplikasi yang memanggilnya: API pada setiap aplikasi. Sesebuah aplikasi hanya mendapat token untuk API yang telah diberikan kepadanya, apa pun yang dimintanya. Keluarkan API dan ia tidak memberikan token lagi; token yang sudah dikeluarkan akan luput dalam beberapa minit.

Memintanya

Aplikasi itu menambah resource=<identifier> pada permintaan kebenaran dan permintaan tokennya. SDK mudah alih melakukannya untuk anda:

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

Aplikasi yang memanggil dua API anda boleh meminta kedua-duanya sekali gus; audiens token itu kemudiannya menyenaraikan kedua-duanya.

Semaknya dalam API anda

Semak token setiap permintaan sebelum anda mempercayai apa-apa di dalamnya:

• Tandatangannya, terhadap kunci di jwks_uri dalam dokumen penemuan persekitaran anda. Ambil algoritma daripada kunci, tidak sekali-kali daripada pengepala token.
• iss mestilah tepat pengeluar persekitaran anda. Tetapkannya dalam konfigurasi anda; jangan sekali-kali membacanya daripada token.
• aud termasuk pengecam API anda. (Dengan skop openid, ia juga menyenaraikan alamat userinfo persekitaran anda.)
• typ dalam pengepala ialah at+jwt, supaya token ID tidak boleh disamarkan sebagai token akses.
• exp belum berlalu. Token akses bertahan 10 minit; SDK memuat semulanya untuk anda.

Dalam Node.js, @usher/node melakukan semuanya:

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

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

Apa yang dinyatakan oleh token

Orang yang sudah anda kenali

Jika API anda sudah mempunyai akaun dari sebelumnya, anda boleh mencari akaun seseorang pada kali pertama mereka tiba dengan token Usher: cari mereka mengikut email, hanya apabila email_verified ialah true, dan simpan iss dan sub pada akaun mereka mulai saat itu. Selepas itu, cari mereka mengikut iss dan sub, tidak sekali-kali mengikut e-mel: alamat boleh bertukar tangan, tetapi subjek tidak pernah.