Τα δικά σας API

Μια εφαρμογή μπορεί να ζητήσει διακριτικό πρόσβασης για ένα από τα API σας. Παίρνει ένα υπογεγραμμένο JWT του οποίου το κοινό είναι αυτό το API και τίποτα άλλο, και το API σας το ελέγχει με τα δημοσιευμένα κλειδιά του περιβάλλοντός σας, χωρίς να καλεί το Usher. Ένα διακριτικό για ένα API δεν χρησιμεύει σε άλλο.

Ονομάστε το API

Στο Usher Console, ανοίξτε το περιβάλλον και, στη συνέχεια, Εφαρμογές → Τα API σας → Προσθήκη API. Δώστε του ένα όνομα και ένα αναγνωριστικό: μια διεύθυνση https://, όπως https://api.example.com, ή ένα URN, όπως urn:example:api:notes. Το αναγνωριστικό είναι αυτό που ζητά η εφαρμογή και αυτό που λέει η δήλωση 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, ώστε ένα διακριτικό αναγνωριστικού να μην μπορεί να περάσει για διακριτικό πρόσβασης.
• Το 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, ποτέ με βάση το email: μια διεύθυνση μπορεί να αλλάξει κάτοχο, ένα subject ποτέ.