API Anda sendiri

Aplikasi dapat meminta token akses untuk salah satu API Anda. Aplikasi itu mendapat JWT bertanda tangan yang audiensnya adalah API tersebut dan bukan yang lain, dan API Anda memeriksanya dengan kunci lingkungan Anda yang dipublikasikan, tanpa memanggil Usher. Token untuk satu API tidak berguna di API lain.

Beri nama API

Di Usher Console, buka lingkungan, lalu Aplikasi → API Anda → Tambahkan API. Beri nama dan pengenal: alamat https://, seperti https://api.example.com, atau URN, seperti urn:example:api:notes. Pengenal adalah apa yang diminta aplikasi dan apa yang dinyatakan klaim aud pada token (RFC 8707).

Lalu berikan API itu ke aplikasi yang memanggilnya: API di setiap aplikasi. Aplikasi hanya mendapat token untuk API yang sudah diberikan kepadanya, apa pun yang dimintanya. Hapus sebuah API, dan API itu tidak lagi memberikan token; token yang sudah beredar habis masa berlakunya dalam hitungan menit.

Memintanya

Aplikasi menambahkan resource=<identifier> ke permintaan otorisasi dan permintaan tokennya. SDK seluler 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 dapat meminta keduanya sekaligus; audiens token kemudian mencantumkan keduanya.

Memeriksanya di API Anda

Periksa token setiap permintaan sebelum Anda memercayai isinya:

• Tanda tangannya, terhadap kunci di jwks_uri dalam dokumen discovery lingkungan Anda. Ambil algoritmanya dari kunci, jangan pernah dari header token.
• iss persis sama dengan penerbit lingkungan Anda. Tetapkan nilainya di konfigurasi Anda; jangan pernah membacanya dari token.
• aud menyertakan pengenal API Anda. (Dengan cakupan openid, klaim ini juga mencantumkan alamat userinfo lingkungan Anda.)
• typ di header bernilai at+jwt, sehingga token ID tidak bisa disamarkan sebagai token akses.
• exp belum lewat. Token akses berlaku 10 menit; SDK memperbaruinya untuk Anda.

Di Node.js, @usher/node mengerjakan 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

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

Isi token

Orang yang sudah Anda kenal

Jika API Anda sudah memiliki akun dari sebelumnya, Anda dapat menemukan akun seseorang saat ia pertama kali datang dengan token Usher: cari berdasarkan email, hanya jika email_verified bernilai true, lalu simpan iss dan sub di akunnya sejak saat itu. Setelah itu, temukan orang tersebut berdasarkan iss dan sub, jangan pernah berdasarkan email: sebuah alamat bisa berpindah tangan, sedangkan subjek tidak pernah.