Intégration · Guide pratique

Configuration du proxy

Intégrez la méthode recommandée de même origine avec un proxy serveur renforcé et le client React fourni.

La méthode proxy expose /api/auth/* sur votre application et transmet ces requêtes au service central. Le SDK remplace les en-têtes proxy fournis par l'appelant par le nom d'hôte, le protocole et la clé API de service existante. Auth valide cette clé et les restrictions de permissions configurées avant d'utiliser l'origine transmise pour l'authentification ou la personnalisation des courriels.

Autoriser le proxy

Utilisez la clé API de service déjà configurée sur le serveur de l'application :

env

KRAKSTACK_AUTH_SERVICE_API_KEY=svc_...

Les trois fonctions proxy lisent automatiquement cette variable. Vous pouvez aussi ajouter apiKey: Redacted.make(serviceKey) aux options (Redacted provient de effect). Gardez la clé côté serveur et utilisez HTTPS entre l'application et Auth en production. Le proxy échoue si sa clé manque.

Les clés de service sans permissions configurées (null ou objet vide) disposent de toutes les permissions par défaut. Elles peuvent transmettre les requêtes pour tout projet inscrit, sans autorisation supplémentaire. Le tableau de bord affiche Toutes les permissions pour ces clés et présente les permissions explicites avec le même résumé de liste que les tableaux de clés du SDK.

Lorsqu'une clé de service possède un objet de permissions non vide, l'accès proxy est limité aux permissions auth:proxy explicites des projets concernés. Un administrateur Auth peut les configurer avec l'API de création ou de modification des clés de service :

json

{
  "permissions": {
    "project_your_id": ["auth:proxy"]
  }
}

Inscrivez chaque nom d'hôte applicatif, y compris les hôtes locaux avec leur port, comme domaine actif de son projet. Auth déduit le projet de cette inscription, et non d'un identifiant fourni par l'appelant. Le nom d'hôte doit correspondre à une seule inscription active. Une liste d'actions explicitement vide pour un projet n'accorde pas l'accès proxy. Les restrictions de référents existantes de la clé s'appliquent aussi à l'origine applicative transmise.

L'en-tête dédié x-krakstack-proxy-key authentifie le proxy sans remplacer les témoins, le jeton bearer ou la clé API de l'utilisateur. Auth retire les identifiants du proxy avant de transmettre la requête à Better Auth. La vérification utilise les contrôles existants de validité, d'expiration, de permissions et de limitation de débit; les requêtes proxy comptent dans le quota de vérification de la clé. Les identifiants invalides et les domaines non autorisés sont rejetés. Les en-têtes de transfert standards seuls ne peuvent pas établir l'origine du proxy; les requêtes directes utilisent leur propre hôte.

Déployer le changement

Vérifiez les inscriptions actives des domaines. Si la clé de service possède des restrictions explicites, ajoutez la permission auth:proxy du projet.
Publiez le SDK mis à jour et préparez le déploiement de chaque application proxy. Il joint automatiquement la clé de service existante.
Déployez le service Auth mis à jour, puis immédiatement les applications proxy dans un déploiement coordonné. Auth doit retirer et masquer l'en-tête contenant la clé avant que les applications commencent à le transmettre; les anciennes versions ne fournissent pas cette protection.

Pendant un déploiement avec des versions différentes, les anciens en-têtes d'origine personnalisés sans clé de service sont rejetés et les anciens proxys qui transmettent uniquement les en-têtes standards perdent leur contexte de domaine. Aucun secret proxy ni aucune configuration de signature supplémentaire n'est nécessaire; la rotation et la révocation utilisent la gestion existante des clés API.

Ajouter la route générique

Avec TanStack Start, créez src/routes/api/auth.$.tsx :

tsx

import { proxyAuthRequest } from "@krak-stack/auth/server";
import { createFileRoute } from "@tanstack/react-router";

const proxyAuth = (request: Request) =>
  proxyAuthRequest(request, process.env.KRAKSTACK_AUTH_URL!);

export const Route = createFileRoute("/api/auth/$")({
  server: {
    handlers: {
      GET: ({ request }) => proxyAuth(request),
      HEAD: ({ request }) => proxyAuth(request),
      POST: ({ request }) => proxyAuth(request),
      PUT: ({ request }) => proxyAuth(request),
      PATCH: ({ request }) => proxyAuth(request),
      DELETE: ({ request }) => proxyAuth(request),
      OPTIONS: ({ request }) => proxyAuth(request),
    },
  },
});

Gardez le chemin générique afin que tous les points Better Auth soient transmis. La cible doit provenir d'une configuration serveur de confiance.

Composer avec une API Effect

Si l'application transmet déjà les requêtes /api/* à un routeur HTTP Effect, ajoutez le proxy d'authentification à ce même routeur au lieu de créer une route TanStack Start dédiée :

import { proxyAuthHttpEffect } from "@krak-stack/auth/server";
import { Layer } from "effect";
import { FetchHttpClient, HttpRouter } from "effect/http";
import { HttpApiBuilder } from "effect/http-api";

const authUrl = process.env.KRAKSTACK_AUTH_URL;
if (!authUrl) throw new Error("KRAKSTACK_AUTH_URL is required");

const authProxyLayer = HttpRouter.add(
  "*",
  "/api/auth/*",
  proxyAuthHttpEffect(authUrl, {
    cookieDomain: "example.com",
  }),
).pipe(HttpRouter.provideRequest(FetchHttpClient.layer));

const apiLayer = Layer.mergeAll(
  HttpApiBuilder.layer(Api).pipe(Layer.provide(apiHandlers)),
  authProxyLayer,
);

Remplacez Api et apiHandlers par l'HttpApi et les couches de gestionnaires existantes de l'application. La route serveur générale /api/* de l'application doit transmettre la requête au routeur Effect.

Gardez le proxy à côté de HttpApiBuilder.layer(Api) plutôt que de l'ajouter à un HttpApiGroup. Le proxy est un transport générique opaque qui doit préserver les requêtes et réponses Better Auth brutes; ce n'est ni un point d'API applicatif typé ni un contrat OpenAPI. Les points HttpApi explicites peuvent rester dans le même routeur Effect, tandis que la route /api/auth/* traite le reste du trafic Better Auth.

proxyAuthHttpEffect utilise Effect HttpClient, qui crée automatiquement une span cliente et injecte ses en-têtes de traçage W3C et B3 dans la requête en amont. Le traceur serveur Effect du service d'authentification extrait ce contexte, ce qui maintient les deux services dans une même trace distribuée. Utilisez ce helper plutôt que d'envelopper proxyAuthRequest dans HttpEffect.fromWebHandler, car ce dernier passe dans un callback Promise avant qu'Effect HttpClient puisse propager la span active.

Omettez cookieDomain pour utiliser des témoins limités à l'hôte. Définissez-le uniquement lorsque des applications de confiance sur des sous-domaines d'un même domaine racine doivent partager les témoins d'authentification.

Utiliser le contrat navigateur

Les composants et atomes fournis utilisent l'origine de l'application par défaut; aucun client Better Auth ne doit être créé. Pour un client Effect personnalisé, importez le contrat navigateur fourni :

import { AuthApiGroup } from "@krak-stack/auth/auth";

Enregistrez AuthApiGroup avec HttpApi, ou utilisez l'API combinée AuthClientApi de @krak-stack/auth/api, pour construire un client Effect HttpApiClient ou AtomHttpApi. Configurez ce client avec l'origine de l'application et non celle du serveur d'authentification en amont.

Ajouter le fournisseur

tsx

import { KrakstackAuthProvider } from "@krak-stack/auth/components";

<KrakstackAuthProvider
  locale="fr"
  projectId={import.meta.env.VITE_KRAKSTACK_AUTH_PROJECT_ID}
>
  <App />
</KrakstackAuthProvider>;

Configurer le service central

Ajoutez chaque origine d'application à BETTER_AUTH_TRUSTED_ORIGINS. Utilisez des origines HTTPS exactes en production. Ajoutez les audiences OAuth séparément lorsqu'elles sont requises.

Vérifier

Ouvrez /api/auth/ok sur l'application.
Connectez-vous et confirmez que les témoins appartiennent au domaine applicatif.
Rechargez une page protégée et vérifiez la session côté serveur.
Testez la déconnexion, la vérification du courriel, la réinitialisation et le deuxième facteur.

Autoriser le proxy#

Déployer le changement#

Ajouter la route générique#

Composer avec une API Effect#

Utiliser le contrat navigateur#

Ajouter le fournisseur#

Configurer le service central#

Vérifier#