JavaScript-Browser-SDK

@keenauth/js ist der Browser-Kern von KeenAuth. Es meldet Benutzer in Ihrer Single-Page-App an, speichert deren Tokens und ruft Ihre API auf. Es hat keine Laufzeitabhängigkeiten, und die React-Komponenten bauen darauf auf. Das Paket ist noch nicht auf npm veröffentlicht.

Anmeldung mit Weiterleitung

Das SDK ist ein Standard-Public-Client für OpenID Connect:

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

const auth = new KeenAuth({
  issuer: "https://acme.eu.keenauth.app", // your environment's issuer, exactly
  clientId: "app_01j9zzzzzzzzzzzzzzzzzzzz",
  redirectUri: "https://app.acme.example/callback",
  postLogoutRedirectUri: "https://app.acme.example/",
});

// On your sign-in button:
await auth.signInRedirect({ appState: "/orders" });

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

handleRedirectCallback akzeptiert eine Antwort nur einmal. Es schlägt mit einem KeenAuthError fehl, wenn:

Ein Fehler, den der Server zurückgibt, wird als KeenAuthOAuthError mit dem OAuth-Code error ausgelöst.

Ihre API aufrufen

Um ein Zugriffstoken für Ihre API zu erhalten, übergeben Sie deren Kennung als resource (RFC 8707). Sie wird bei der Autorisierungsanfrage, beim Code-Austausch und bei jeder Aktualisierung gesendet, und der aud des Tokens ist diese Kennung:

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

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

// Or take the token yourself; it is refreshed when it is about to expire.
const token = await auth.getAccessToken();

authorizedFetch sendet Authorization: DPoP mit einem frischen, an das Token gebundenen Nachweis. Wenn der Server einen DPoP-Nonce verlangt, wiederholt es den Aufruf einmal mit diesem Nonce. Gleichzeitige Aufrufe teilen sich eine Aktualisierungsanfrage, und jede Aktualisierung rotiert das Refresh-Token. Informationen zur Prüfung dieser Tokens in Ihrer API finden Sie unter Tokens in Ihrer API prüfen.

Abmelden

await auth.signOut();

signOut verwirft die Tokens und widerruft das Refresh-Token. Anschließend leitet es den Browser zum Logout-Endpunkt Ihrer Umgebung weiter, der ihn zu postLogoutRedirectUri zurückbringt.

Wo Tokens gespeichert werden

Eingebettete Anmeldung

Dasselbe Objekt stellt den eingebetteten Komponenten außerdem einen Frontend-API-Client zur Verfügung:

Diese Aufrufe verwenden die Cookies Ihrer Umgebung und einen CSRF-Header. Der Server akzeptiert sie nur vom eigenen Anmelde-Origin der Umgebung.

Anmeldung ohne Weiterleitung

Starten Sie auf einer Seite außerhalb Ihres Anmelde-Origins die Transaktion mit Ihrer clientId. Das SDK bindet sie dann an seinen DPoP-Schlüssel statt an Cookies:

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

Kontoaufrufe von Ihrem eigenen Origin

Sobald der Benutzer angemeldet ist und das SDK ein Refresh-Token hält (der Standard-Scope fordert offline_access an), benötigen die Aufrufe me und organizations kein Sitzungs-Cookie des Anmeldehosts mehr:

Die Serverregeln finden Sie unter Zugriffstoken für die Frontend-API.

Organisation wechseln

organizations.switch(orgId) wechselt den angemeldeten Benutzer ohne Seitenaufruf in eine andere Organisation. Übergeben Sie die ID org_… einer Organisation aus organizations.listMine():

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

Aktuelle Einschränkungen