SDK Auth Heriade

Objectif

Le package @heriade-app/auth-sdk centralise l'integration SSO des applications Heriade consommatrices. Il remplace les copies locales de auth-session-client.js, les callbacks login dupliques et les guards backend recodes dans chaque projet.

Le portail SSO et le backend console-admin/back restent la source de verite :

1. l'application redirige vers AUTH_APP_URL/login;
2. le portail authentifie l'utilisateur avec Supabase;
3. le portail appelle POST /auth-app/authorize;
4. l'application recoit #app_access_token=...;
5. le SDK renouvelle silencieusement ce token via POST /auth-app/refresh.

Le SDK ne stocke ni mot de passe, ni session Supabase, ni refresh token Supabase cote application consommatrice.

Package

Le code vit dans packages/heriade-auth-sdk.

Exports :

• @heriade-app/auth-sdk : client navigateur et helpers communs;
• @heriade-app/auth-sdk/server : extraction/verification de token et mapping UserContext pour les backends.

Le package est volontairement sans dependance runtime. Il peut etre publie en package prive ou vendorise temporairement par les applications pilotes.

Integration frontend

Exemple minimal :

import {
  buildAppCallbackUrl,
  createHeriadeAuthClient,
} from '@heriade-app/auth-sdk'

const auth = createHeriadeAuthClient({
  authUrl: import.meta.env.VITE_AUTH_APP_URL,
  apiUrl: import.meta.env.VITE_AUTH_API_URL,
  application: 'contacts',
  environment: 'default',
  storage: 'localStorage',
  returnTo: () =>
    buildAppCallbackUrl(
      window.location.origin,
      window.location.pathname + window.location.search,
    ),
})

const ok = await auth.init()
if (!ok) auth.login({ redirectTo: window.location.pathname })

Callback /login/callback :

const params = new URLSearchParams(window.location.search)
const result = await auth.handleCallback({
  hash: window.location.hash,
  redirect: params.get('redirect'),
})

window.history.replaceState(
  window.history.state,
  '',
  `${window.location.pathname}${window.location.search}`,
)
window.location.assign(result.redirect)

Appels API :

const response = await auth.authFetch('/api/contacts')

authFetch ajoute le token, tente un refresh force sur le premier 401, puis rejoue la requete une seule fois. Par defaut le header applicatif reste X-App-Access-Token pour compatibilite avec les apps actuelles. Les nouvelles apps peuvent configurer apiTokenHeader: 'Authorization'.

Integration backend

Mode local JWT, compatible avec l'existant :

import {
  buildUserContextFromPayload,
  extractAppAccessToken,
  verifyAppAccessToken,
} from '@heriade-app/auth-sdk/server'

const token = extractAppAccessToken(request.headers)
const payload = verifyAppAccessToken(token, {
  secret: process.env.APP_ACCESS_TOKEN_SECRET,
  application: process.env.APPLICATION,
  environment: process.env.ENVIRONMENT,
})

if (!payload) throw new UnauthorizedException()
request.userCtx = buildUserContextFromPayload(payload)

Mode centralise recommande pour les apps sensibles :

POST /auth-app/context
x-auth-introspection-secret: <secret>

{ "token": "<app_access_token>" }

Reponse :

{
  "active": true,
  "user": {
    "userId": "uuid",
    "accountId": 12,
    "enterpriseId": 66,
    "enterpriseName": "Heriade",
    "accountType": "enterprise",
    "role": "administrateur",
    "isAdmin": true,
    "isSuperAdmin": false,
    "email": "[email protected]",
    "application": "contacts",
    "environment": "default"
  }
}

Ce mode evite de dupliquer le mapping des claims et tient compte de la table user_token_revocations.

Securite

Le SDK durcit les points qui avaient tendance a diverger par projet :

• nettoyage du hash #app_access_token apres callback;
• refus des redirects externes (https://..., //..., caracteres de controle);
• refresh concurrent deduplique;
• retry applicatif limite a un seul rejeu;
• distinction entre expiration reelle, refus d'acces et indisponibilite temporaire;
• stockage configurable : memoire, sessionStorage, localStorage ou adapter custom;
• logs sans token brut cote backend consommateur.

Variables

Frontend :

AUTH_APP_URL=https://auth.heriade.fr
AUTH_API_URL=https://api.console.heriade.fr
APPLICATION=contacts
ENVIRONMENT=default

Backend consommateur :

APPLICATION=contacts
ENVIRONMENT=default
APP_ACCESS_TOKEN_SECRET=...
AUTH_INTROSPECTION_SECRET=...
CONSOLE_ADMIN_URL=https://api.console.heriade.fr

APP_ACCESS_TOKEN_SECRET reste requis pour le mode local JWT. A moyen terme, il faudra remplacer le secret partage par une signature asymetrique et un JWKS.

Migration d'une application existante

1. installer ou vendoriser @heriade-app/auth-sdk;
2. remplacer la copie locale auth-session-client.js;
3. remplacer les pages login/callback par les wrappers SDK;
4. remplacer le wrapper fetch par auth.authFetch;
5. remplacer le guard backend custom par les helpers serveur ou par /auth-app/context;
6. lancer les tests e2e : login, callback, refresh silencieux, 401 retry, logout global, switch de compte.