SDK JavaScript per il browser

@keenauth/js è il core per il browser di KeenAuth. Accede gli utenti alla tua single-page app, conserva i loro token e chiama la tua API. Non ha dipendenze di runtime, e i componenti React si basano su di esso. Il pacchetto non è ancora pubblicato su npm.

Accedi con un redirect

L'SDK è un client pubblico OpenID Connect standard:

import { KeenAuth } from "@keenauth/js";

const auth = new KeenAuth({
  issuer: "https://acme.eu.keenauth.app", // l'issuer del tuo ambiente, esattamente
  clientId: "app_01j9zzzzzzzzzzzzzzzzzzzz",
  redirectUri: "https://app.acme.example/callback",
  postLogoutRedirectUri: "https://app.acme.example/",
});

// Sul tuo pulsante di accesso:
await auth.signInRedirect({ appState: "/orders" });

// Su https://app.acme.example/callback:
const { appState } = await auth.handleRedirectCallback();

handleRedirectCallback accetta una risposta una sola volta. Fallisce con un KeenAuthError quando:

Un errore inviato dal server viene sollevato come KeenAuthOAuthError con il codice error di OAuth.

Chiama la tua API

Per ottenere un access token per la tua API, passa il suo identificatore come resource (RFC 8707). Viene inviato nella richiesta di autorizzazione, nello scambio del codice e in ogni refresh, e l'aud del token è quell'identificatore:

const auth = new KeenAuth({
  issuer: "https://acme.eu.keenauth.app",
  clientId: "app_01j9zzzzzzzzzzzzzzzzzzzz",
  redirectUri: "https://app.acme.example/callback",
  resource: "https://api.acme.example", // l'identificatore della tua API
  scope: "openid profile email offline_access messages:read",
});

const res = await auth.authorizedFetch("https://api.acme.example/v1/orders");

// Oppure prendi tu il token; viene rinnovato quando sta per scadere.
const token = await auth.getAccessToken();

authorizedFetch invia Authorization: DPoP con una prova DPoP nuova, vincolata al token. Se il server chiede un nonce DPoP, riprova una volta con quel nonce. Le chiamate concorrenti condividono un'unica richiesta di refresh, e ogni refresh ruota il refresh token. Per verificare questi token nella tua API, vedi Verifica dei token nella tua API.

Disconnettiti

await auth.signOut();

signOut elimina i token e revoca il refresh token. Poi porta il browser all'endpoint di logout del tuo ambiente, che lo riporta a postLogoutRedirectUri.

Dove vengono conservati i token

Accesso incorporato

Lo stesso oggetto fornisce anche ai componenti incorporati un client API frontend:

Queste chiamate usano i cookie del tuo ambiente e un header CSRF. Il server le accetta solo dall'origine di login dell'ambiente stesso.

Accedi senza redirect

In una pagina al di fuori della tua origine di login, avvia la transazione con il tuo clientId. L'SDK la lega poi alla sua chiave DPoP invece che ai cookie:

let tx = await auth.transactions.create({ client_id: "app_01j9...", organization: "acme" });
tx = await auth.transactions.step("identifier", { identifier: "ada@acme.example" });
tx = await auth.transactions.step("password", { password });
if (tx.state === "completed") await auth.complete(tx); // { kind: "signed_in" }

Chiamate dell'account dalla tua origine

Una volta che l'utente ha effettuato l'accesso e l'SDK possiede un refresh token (lo scope predefinito richiede offline_access), le chiamate me e organizations non hanno più bisogno del cookie di sessione dell'host di accesso:

Vedi Token di accesso della Front API per le regole lato server.

Cambiare organizzazione

organizations.switch(orgId) sposta l'utente già autenticato in un'altra organizzazione senza ricaricare la pagina. Passa l'ID org_… di un'organizzazione presa da organizations.listMine():

const { data } = await auth.organizations.listMine();
await auth.organizations.switch(data[1].id);

Limiti attuali