Migration depuis Auth0

Auris offre une parité de fonctionnalités avec Auth0 en authentification, autorisation et gestion des utilisateurs, plus des fonctionnalités qu’Auth0 facture en supplément ou n’offre pas (FGA style Zanzibar, provisioning SCIM intégré, Actions Engine avec éditeur visuel, et déploiement self-hosted). Ce guide illustre une migration complète d’Auth0 vers Auris avec un downtime minimal.

Mapping des Fonctionnalités

Étapes de Migration

Étape 1 : Exporter les Utilisateurs depuis Auth0

Utilise l’Auth0 Management API pour exporter tes utilisateurs :

# Créer un job d'export
curl -X POST https://VOTRE_DOMAINE_AUTH0/api/v2/jobs/users-exports \
  -H "Authorization: Bearer $AUTH0_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "fields": [
      { "name": "user_id" },
      { "name": "email" },
      { "name": "email_verified" },
      { "name": "name" },
      { "name": "given_name" },
      { "name": "family_name" },
      { "name": "created_at" },
      { "name": "app_metadata" },
      { "name": "user_metadata" }
    ]
  }'

# Vérifier le statut de l'export
curl https://VOTRE_DOMAINE_AUTH0/api/v2/jobs/JOB_ID \
  -H "Authorization: Bearer $AUTH0_MANAGEMENT_TOKEN"
 
# Quand le statut est "completed", télécharge le fichier depuis l'URL location

Étape 2 : Transformer et Importer les Utilisateurs dans Auris

Transforme le format d’export Auth0 au format d’import Auris :

// transform-auth0-users.ts
import fs from 'fs'
 
interface Auth0User {
  user_id: string
  email: string
  email_verified: boolean
  name: string
  given_name: string
  family_name: string
  created_at: string
  app_metadata: Record<string, unknown>
  user_metadata: Record<string, unknown>
}
 
interface AurisImportUser {
  email: string
  firstName: string
  lastName: string
  emailVerified: boolean
}
 
const auth0Users: Auth0User[] = JSON.parse(
  fs.readFileSync('auth0-export.json', 'utf-8')
)
 
const aurisUsers: AurisImportUser[] = auth0Users.map((user) => ({
  email: user.email,
  firstName: user.given_name || user.name?.split(' ')[0] || '',
  lastName: user.family_name || user.name?.split(' ').slice(1).join(' ') || '',
  emailVerified: user.email_verified,
}))
 
fs.writeFileSync('auris-import.json', JSON.stringify(aurisUsers, null, 2))
console.log(`${aurisUsers.length} utilisateurs transformés`)

Importe dans Auris :

curl -X POST https://auth.votredomaine.com/api/users/import \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: votre-tenant-id" \
  -F "[email protected]" \
  -F "format=json"

Étape 3 : Créer les Applications dans la Console Auris

Pour chaque Application Auth0, crée une Application correspondante dans Auris :

1. Ouvre Console puis Applications puis Créer une Application
2. Définis le Type d’Application pour correspondre au type Auth0 :
   • Auth0 “Single Page Application” ou “Regular Web Application” = Auris WEB
   • Auth0 “Native” = Auris MOBILE
   • Auth0 “Machine to Machine” = Auris M2M
3. Configure les URLs de Callback Autorisées avec les mêmes redirect URIs qu’Auth0
4. Configure les Origines Autorisées avec les mêmes origines qu’Auth0
5. Note le nouveau Client ID (et le Client Secret pour les apps M2M)

Étape 4 : Remplacer le SDK Auth0 par le SDK Auris

Installe le SDK Auris et supprime le SDK Auth0 :

# Supprimer Auth0
npm uninstall @auth0/auth0-spa-js @auth0/auth0-react @auth0/nextjs-auth0
 
# Installer Auris
npm install @auris/js @auris/react
# Pour Next.js :
npm install @auris/nextjs

Étape 5 : Mettre à Jour le Code de l’Application

L’API du SDK Auris est intentionnellement similaire à celle d’Auth0 pour minimiser l’effort de migration.

Configuration Provider (React) :

// AVANT (Auth0)
import { Auth0Provider } from '@auth0/auth0-react'
 
function App() {
  return (
    <Auth0Provider
      domain="votre-tenant.auth0.com"
      clientId="auth0-client-id"
      authorizationParams={{
        redirect_uri: window.location.origin + '/callback',
      }}
    >
      <MyApp />
    </Auth0Provider>
  )
}
 
// APRÈS (Auris)
import { AurisProvider } from '@auris/react'
 
function App() {
  return (
    <AurisProvider
      domain="auth.votreentreprise.com"
      clientId="auris-client-id"
      redirectUri={window.location.origin + '/callback'}
    >
      <MyApp />
    </AurisProvider>
  )
}

Hook d’Authentification :

// AVANT (Auth0)
const { loginWithRedirect, logout, user, isAuthenticated, isLoading, getAccessTokenSilently } = useAuth0()
 
// APRÈS (Auris)
const { loginWithRedirect, logout, user, isAuthenticated, isLoading, getAccessToken } = useAuris()
 
// Le logout est légèrement différent :
// Auth0: logout({ logoutParams: { returnTo: window.location.origin } })
// Auris: logout({ returnTo: window.location.origin })

Appels API avec Access Token :

// AVANT (Auth0)
const token = await getAccessTokenSilently()
 
// APRÈS (Auris)
const token = await getAccessToken()
 
// Le reste du code API reste inchangé
const response = await fetch('/api/protected', {
  headers: { Authorization: `Bearer ${token}` },
})

Vérification des Permissions (React) :

// AVANT (Auth0 — vérification manuelle du claim)
const { user } = useAuth0()
const hasPermission = user?.['https://myapp.com/permissions']?.includes('read:data')
 
// APRÈS (Auris — hook de permissions intégré)
import { useCheckPermission } from '@auris/react'
 
const canReadData = useCheckPermission('read:data')

Middleware Next.js :

// AVANT (Auth0)
import { withMiddlewareAuthRequired } from '@auth0/nextjs-auth0/edge'
export default withMiddlewareAuthRequired()
 
// APRÈS (Auris)
import { aurisMiddleware } from '@auris/nextjs/middleware'
export default aurisMiddleware({
  protectedPaths: ['/dashboard(.*)'],
  publicPaths: ['/', '/about', '/pricing'],
  loginUrl: '/auth/login',
})

Étape 6 : Mettre à Jour les Redirect URIs

Mets à jour les Callback URLs dans l’application Auris pour correspondre à ce que ton app envoie :

• Remplace https://votre-tenant.auth0.com/ par https://auth.votreentreprise.com/ dans tous les redirect URIs

Étape 7 : Migrer les Rules vers les Actions

Les Rules et Actions Auth0 se mappent aux déclencheurs de l’Actions Engine Auris :

Exemple d’Action Auth0 :

// Auth0 Action (post-login)
exports.onExecutePostLogin = async (event, api) => {
  if (!event.user.email_verified) {
    api.access.deny('Vérifie ton e-mail avant d\'accéder.')
  }
  api.idToken.setCustomClaim('https://myapp.com/role', event.user.app_metadata.role)
}

Équivalent Auris Action :

// Auris Action (déclencheur post-login)
async function action(context) {
  if (!context.user.emailVerified) {
    return { deny: true, message: 'Vérifie ton e-mail avant d\'accéder.' }
  }
  return {
    claims: {
      role: context.user.metadata?.role || 'user'
    }
  }
}

Étape 8 : Migrer l’RBAC

Exporte les rôles et permissions depuis Auth0 et recrée-les dans Auris :

# Lister les rôles Auth0
curl https://VOTRE_DOMAINE_AUTH0/api/v2/roles \
  -H "Authorization: Bearer $AUTH0_MANAGEMENT_TOKEN"

Pour chaque rôle, crée-le dans Auris :

curl -X POST https://auth.votredomaine.com/api/roles \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: votre-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Éditeur",
    "description": "Peut modifier les contenus",
    "color": "#3B82F6"
  }'

Auris supporte les permissions tri-state (ALLOW/DENY) qui sont plus granulaires que le modèle binaire d’Auth0.

Étape 9 : DNS Cutover

Une fois tout testé :

1. Configure un domaine personnalisé dans Auris (ex. auth.votreentreprise.com)
2. Mets à jour le DNS pour pointer ton domaine d’authentification vers Auris
3. Mets à jour toutes les applications pour utiliser le nouveau domaine
4. Surveille les logs d’audit Auris pendant les premières heures après le cutover

Gestion des Mots de Passe (Migration Lazy)

Puisqu’Auth0 n’exporte pas les hashes de mots de passe, tu as deux options :

Option A : Forcer la Réinitialisation du Mot de Passe (Plus Simple)

Après avoir importé les utilisateurs, déclenche un e-mail de réinitialisation de mot de passe en masse :

1. Tous les utilisateurs importés reçoivent un e-mail “Définis ton mot de passe”
2. Les utilisateurs cliquent le lien et définissent un nouveau mot de passe sur Auris
3. Aucune modification du code de l’application requise

Option B : Migration Lazy (Zéro Friction)

Fais tourner Auth0 et Auris en parallèle temporairement. Quand un utilisateur se connecte :

1. Auris tente d’authentifier l’utilisateur
2. Si l’utilisateur n’a pas de mot de passe dans Auris (importé sans), Auris retourne une erreur spécifique
3. Ton application intercepte cette erreur et tente l’authentification sur Auth0 comme fallback
4. Si Auth0 réussit, ton application crée le mot de passe dans Auris via l’Admin API
5. Les connexions suivantes passent directement par Auris

Cette approche migre les mots de passe de façon transparente au fur et à mesure que les utilisateurs se connectent, avec zéro friction.

Plan de Rollback

En cas de problèmes pendant la migration :

1. Maintiens Auth0 actif pendant au moins 30 jours après le cutover
2. Rollback DNS : Redirige ton domaine d’authentification vers Auth0
3. Rollback SDK : Restaure les packages @auris/* avec @auth0/* dans le code et redéploie
4. Aucune perte de données : Les utilisateurs créés dans Auris pendant la migration peuvent être exportés et réimportés dans Auth0

Checklist Post-Migration

Après avoir terminé la migration, vérifie :

• Tous les utilisateurs peuvent se connecter (teste avec plusieurs comptes)
• Les fournisseurs de connexion sociale fonctionnent (Google, GitHub, etc.)
• L’inscription et la vérification MFA fonctionnent
• Le contrôle d’accès basé sur les rôles est appliqué correctement
• Les webhooks livrent des événements à tes endpoints
• Le log streaming est actif (si configuré)
• Les domaines personnalisés et SSL fonctionnent
• Les applications mobiles (si présentes) sont mises à jour avec le nouveau SDK
• Les applications M2M peuvent obtenir des tokens
• Le provisioning SCIM est connecté (si utilisé)

Guides Associés

• Connexion Hébergée (PKCE) — Implémenter le flux de connexion
• Rôles et Permissions — Configurer l’RBAC
• Autorisation Fine-Grained — Migrer depuis Auth0 FGA
• Import/Export Utilisateurs — Migration d’utilisateurs en masse
• Domaines Personnalisés — White-label des pages d’authentification
• Migration depuis Firebase — Guide de migration alternatif