உங்கள் சொந்த API-கள்

ஒரு ஆப்ஸ் உங்கள் API-களில் ஒன்றுக்கான அணுகல் டோக்கனைக் கேட்கலாம். அதற்குக் கிடைப்பது, அந்த API-ஐ மட்டுமே ஆடியன்ஸாகக் கொண்ட கையொப்பமிட்ட JWT, உங்கள் API அதை Usher-ஐ அழைக்காமலேயே உங்கள் சூழலின் வெளியிடப்பட்ட விசைகளைக் கொண்டு சரிபார்க்கிறது. ஒரு API-க்கான டோக்கன் இன்னொன்றில் பயன்படாது.

API-க்குப் பெயரிடுங்கள்

Usher Console-இல் சூழலைத் திறந்து, பிறகு பயன்பாடுகள் → உங்கள் API-கள் → API-ஐச் சேர் என்பதற்குச் செல்லுங்கள். அதற்கு ஒரு பெயரும் அடையாளங்காட்டியும் கொடுங்கள்: https://api.example.com போன்ற https:// முகவரி, அல்லது urn:example:api:notes போன்ற URN. ஆப்ஸ் கேட்பதும், டோக்கனின் aud கோரல் சொல்வதும் இந்த அடையாளங்காட்டிதான் (RFC 8707).

பிறகு அந்த 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-இல் அதைச் சரிபாருங்கள்

ஒவ்வொரு கோரிக்கையின் டோக்கனிலும் உள்ள எதையும் நம்புவதற்கு முன் அதைச் சரிபாருங்கள்:

• கையொப்பம், உங்கள் சூழலின் டிஸ்கவரி ஆவணத்தில் உள்ள jwks_uri இல் இருக்கும் விசைகளுக்கு எதிராக. அல்காரிதத்தை விசையிலிருந்து எடுங்கள், டோக்கனின் ஹெடரிலிருந்து ஒருபோதும் எடுக்காதீர்கள்.
• iss என்பது துல்லியமாக உங்கள் சூழலின் இஷ்யூவர். அதை உங்கள் உள்ளமைவில் நிலையாக வையுங்கள்; டோக்கனிலிருந்து ஒருபோதும் படிக்காதீர்கள்.
• 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 ஒருபோதும் மாறாது.