API của riêng bạn

Một ứng dụng có thể yêu cầu token truy cập cho một trong các API của bạn. Ứng dụng nhận một JWT có chữ ký với đối tượng (audience) là API đó và không gì khác, và API của bạn kiểm tra token bằng các khóa đã công bố của môi trường, mà không cần gọi Usher. Token cho một API không dùng được ở API khác.

Đặt tên cho API

Trong Usher Console, mở môi trường, rồi chọn Ứng dụng → API của bạn → Thêm API. Đặt cho API một tên và một mã định danh: một địa chỉ https://, chẳng hạn https://api.example.com, hoặc một URN, chẳng hạn urn:example:api:notes. Mã định danh là thứ ứng dụng yêu cầu và là nội dung của claim aud trong token (RFC 8707).

Sau đó, cấp API cho các ứng dụng gọi đến nó: dùng nút API trên từng ứng dụng. Một ứng dụng chỉ nhận token cho những API đã được cấp cho nó, bất kể nó yêu cầu gì. Khi bạn gỡ một API, API đó không cấp thêm token nào nữa; các token đã phát hành sẽ hết hạn trong vòng vài phút.

Yêu cầu token

Ứng dụng thêm resource=<identifier> vào yêu cầu ủy quyền và các yêu cầu token. Các SDK di động làm việc này giúp bạn:

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

Một ứng dụng gọi hai API của bạn có thể yêu cầu cả hai cùng lúc; khi đó audience của token sẽ liệt kê cả hai.

Kiểm tra token trong API của bạn

Hãy kiểm tra token của mọi yêu cầu trước khi tin bất cứ thứ gì trong đó:

• Chữ ký, bằng các khóa tại jwks_uri trong tài liệu khám phá của môi trường. Lấy thuật toán từ khóa, không bao giờ từ header của token.
• iss đúng chính xác là bên phát hành của môi trường. Hãy cố định giá trị này trong cấu hình; không bao giờ đọc nó từ token.
• aud có chứa mã định danh của API. (Với phạm vi openid, nó còn liệt kê cả địa chỉ userinfo của môi trường.)
• typ trong header là at+jwt, để không ai có thể dùng token ID giả làm token truy cập.
• exp chưa qua. Token truy cập có hiệu lực 10 phút; các SDK sẽ làm mới chúng giúp bạn.

Trong Node.js, @usher/node làm tất cả những việc này:

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

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

Token cho biết những gì

Những người bạn đã biết

Nếu API của bạn đã có sẵn tài khoản từ trước, bạn có thể tìm tài khoản của một người vào lần đầu họ đến với token Usher: tra cứu theo email, chỉ khi email_verified là true, và từ đó lưu iss và sub vào tài khoản của họ. Sau đó, hãy tìm họ theo iss và sub, không bao giờ theo email: một địa chỉ email có thể đổi chủ, còn subject thì không bao giờ.