API ของคุณเอง

แอปขอโทเค็นการเข้าถึงสำหรับ API ตัวใดตัวหนึ่งของคุณได้ แอปจะได้รับ JWT ที่ลงนามแล้ว ซึ่งมีผู้รับ (audience) เป็น API นั้นเท่านั้น และ API ของคุณตรวจสอบโทเค็นได้ด้วยคีย์ที่สภาพแวดล้อมเผยแพร่ไว้ โดยไม่ต้องเรียก Usher โทเค็นสำหรับ API หนึ่งจึงใช้กับ API อื่นไม่ได้

ตั้งชื่อ API

ใน Usher Console ให้เปิดสภาพแวดล้อม แล้วไปที่ แอปพลิเคชัน → API ของคุณ → เพิ่ม API ตั้งชื่อและตัวระบุให้ API ตัวระบุคือที่อยู่ https:// เช่น https://api.example.com หรือ URN เช่น urn:example:api:notes ตัวระบุคือสิ่งที่แอปขอ และเป็นค่าที่ claim aud ของโทเค็นระบุ (RFC 8707)

จากนั้นมอบ API ให้แอปที่เรียกใช้ ด้วยปุ่ม API ของแต่ละแอปพลิเคชัน แอปจะได้โทเค็นเฉพาะสำหรับ API ที่ได้รับมอบเท่านั้น ไม่ว่าจะขออะไรมาก็ตาม หากเอา API ออก API นั้นจะไม่ได้รับโทเค็นใหม่อีก ส่วนโทเค็นที่ออกไปแล้วจะหมดอายุภายในไม่กี่นาที

ขอโทเค็น

แอปเพิ่ม resource=<identifier> ลงในคำขอการอนุญาตและคำขอโทเค็น ซึ่ง SDK สำหรับมือถือทำให้คุณ:

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

แอปที่เรียก API ของคุณสองตัวขอทั้งสองตัวพร้อมกันได้ ผู้รับของโทเค็นจะระบุทั้งสอง API

ตรวจสอบโทเค็นใน API ของคุณ

ตรวจสอบโทเค็นของทุกคำขอก่อนเชื่อถือสิ่งใดในโทเค็นนั้น:

• ลายเซ็น ตรวจกับคีย์ที่ jwks_uri ในเอกสาร Discovery ของสภาพแวดล้อม ใช้อัลกอริทึมจากคีย์ ห้ามใช้จากเฮดเดอร์ของโทเค็น
• iss ต้องตรงกับ Issuer ของสภาพแวดล้อมทุกตัวอักษร กำหนดค่านี้ไว้ในการตั้งค่าของคุณ ห้ามอ่านจากโทเค็น
• aud ต้องมีตัวระบุของ API ของคุณ (เมื่อใช้ขอบเขต openid จะมีที่อยู่ userinfo ของสภาพแวดล้อมด้วย)
• typ ในเฮดเดอร์ต้องเป็น at+jwt เพื่อไม่ให้ใครนำโทเค็น ID มาแอบอ้างเป็นโทเค็นการเข้าถึง
• exp ต้องยังไม่ผ่านไป โทเค็นการเข้าถึงมีอายุ 10 นาที และ SDK จะรีเฟรชให้คุณ

ใน Node.js @usher/node ทำทั้งหมดนี้ให้:

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:

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

สิ่งที่โทเค็นระบุ

ผู้ใช้ที่คุณรู้จักอยู่แล้ว

หาก API ของคุณมีบัญชีผู้ใช้จากก่อนหน้านี้อยู่แล้ว คุณค้นหาบัญชีของผู้ใช้ได้ในครั้งแรกที่ผู้ใช้มาพร้อมโทเค็นของ Usher: ค้นหาด้วย email เฉพาะเมื่อ email_verified เป็น true และเก็บ iss กับ sub ไว้ในบัญชีของผู้ใช้นับจากนั้น หลังจากนั้นให้ค้นหาผู้ใช้ด้วย iss และ sub ห้ามค้นหาด้วยอีเมล เพราะที่อยู่อีเมลเปลี่ยนมือได้ แต่ subject ไม่มีวันเปลี่ยน