> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Guide d'intégration Didit Authentication : architecture et mise en production

> Architecture d'une intégration Didit Authentication : écrans hébergés ou propres, tokens, backend, sessions, apps natives et mise en production.

Ce guide explique comment s'articule une intégration Didit Authentication en production, de la première redirection jusqu'à la liste de contrôle avant mise en production.
Commencez par le [démarrage rapide](https://docs.didit.me/fr/authentication/quickstart.md) si vous n'avez pas encore connecté un utilisateur, et utilisez les guides de démarrage rapide des plateformes pour le code de chaque SDK.

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

Quatre éléments interviennent :

| Élément | Responsabilité |
| - | - |
| Votre application | Lancer la connexion, conserver le vérificateur PKCE et `state`, stocker les tokens et envoyer le token d'accès à votre backend. Les SDK gèrent l'ensemble de ces opérations. |
| Votre origine de connexion | `https://<slug>.auth.didit.me` (ou votre [domaine personnalisé](https://docs.didit.me/fr/authentication/branding-and-custom-domain.md#domaine-personnalisé)) : les pages hébergées, l'endpoint de token, la session, le document de découverte et les clés de signature. |
| Votre backend | Vérifier le token d'accès à chaque requête protégée, contrôler la session avant toute action sensible et décider de ce que la personne est autorisée à faire. |
| Console Didit et webhooks | La configuration, les personnes et leurs sessions, les événements de connexion et les webhooks `auth.*` auxquels votre serveur s'abonne. |

Aucune clé API Didit ni aucun secret ne doit figurer dans votre application : la clé publiable est publique, et l'échange de code est protégé par PKCE au lieu d'un secret client.

## Pages hébergées ou vos propres écrans

Choisissez où les utilisateurs saisissent leur e-mail, leur mot de passe ou leur code.
Le paramètre `sign_in_ui` (`hosted` par défaut, ou `own`) peut être modifié à tout moment.

| | Pages hébergées (recommandé) | Vos propres écrans |
| - | - | - |
| Ce que vous développez | Un bouton de connexion et une page de rappel. | Chaque écran et chaque étape intermédiaire. |
| Méthodes | Toutes, y compris les liens magiques, le SSO d'entreprise et les passkeys. | Mot de passe, code par e-mail, code par téléphone, MFA et défis de protection via les méthodes headless des SDK. Les liens magiques ne fonctionnent que sur les pages hébergées. |
| Étapes suivantes | Prises en charge pour vous : MFA, inscription à la MFA, défis de protection et vérification lors de l'inscription. | Vos écrans gèrent `mfa_required`, `mfa_enrollment_required`, `protection_required` et `verification_required`. Voir [méthodes de connexion](https://docs.didit.me/fr/authentication/sign-in-methods.md). |
| Image de marque | Votre logo, vos couleurs et vos textes depuis la [personnalisation](https://docs.didit.me/fr/authentication/branding-and-custom-domain.md). | Entièrement à vous. |
| Configuration | URL de redirection. | URL de redirection, plus l'origine web de votre site dans **Allowed origins**. |

Les passkeys sont liés à l'origine de connexion de votre application.
Les méthodes passkey des SDK ne fonctionnent que sur les pages servies depuis cette origine. Ainsi, sur vos propres écrans situés sur un autre domaine, orientez les utilisateurs vers la page hébergée pour les passkeys.

## Choisir votre SDK

| Votre application | Package | Emplacement des tokens |
| - | - | - |
| Application web monopage | [`@didit-protocol/auth`](https://docs.didit.me/fr/authentication/quickstarts/javascript) ou [`@didit-protocol/auth-react`](https://docs.didit.me/fr/authentication/quickstarts/react) | Stockage web ou mémoire du navigateur. Conservez une politique de sécurité du contenu stricte. |
| Application web rendue côté serveur | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/fr/authentication/quickstarts/nextjs) | Cookies HttpOnly définis par votre serveur. La page ne voit jamais les tokens. |
| iOS | [`DiditAuth`](https://docs.didit.me/fr/authentication/quickstarts/ios) | Le Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/fr/authentication/quickstarts/android) | Stockage protégé par l'Android Keystore. |
| React Native ou Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/fr/authentication/quickstarts/react-native) ou [`didit_auth`](https://docs.didit.me/fr/authentication/quickstarts/flutter) | Le stockage protégé de la plateforme, via les modules natifs. |
| Tout backend | [SDK serveur](https://docs.didit.me/fr/integration/server-sdks/overview.md), `verifyToken` depuis `@didit-protocol/auth/server`, ou toute bibliothèque JWT | Rien à stocker : il vérifie le token qu'il reçoit. |

Sans SDK, implémentez vous-même le flux d'autorisation par code avec PKCE : le [démarrage rapide JavaScript](https://docs.didit.me/fr/authentication/quickstarts/javascript.md#sans-le-sdk) présente l'ensemble du contrat.

## Protégez votre backend

Une vérification de session côté frontend ne contrôle que ce que vous affichez.
Votre backend prend chaque décision à partir d'un token vérifié.

1. **Vérifiez le token d'accès à chaque requête.** Contrôlez la signature ES256 avec le JWKS de votre émetteur, puis `iss`, `aud`, `exp` et `typ: at+jwt`, et rejetez un token dont `act` n'est pas `null`, sauf si la route accepte les [agents IA](https://docs.didit.me/fr/authentication/agent-access.md). Voir [vérifier un token sur votre serveur](https://docs.didit.me/fr/authentication/tokens-and-jwks.md#vérifier-un-jeton-sur-votre-serveur).
2. **Contrôlez la session active avant une action sensible.** Un token d'accès reste valide jusqu'à son expiration, dans un délai maximal de 5 minutes. `GET /session/` échoue immédiatement lorsque la session a été révoquée, est restée inactive ou a expiré, lorsque la personne a été bloquée, ou lorsque la session ne respecte plus votre politique MFA. Voir [contrôler la session](https://docs.didit.me/fr/authentication/tokens-and-jwks.md#vérifier-la-session).
3. **Demandez un step-up lorsque l'action est risquée.** Avant un versement, un nouveau compte bancaire ou une modification de l'e-mail ou du téléphone, demandez à Didit si la personne doit se vérifier à nouveau, et n'agissez que sur un step-up `approved` que votre backend a lui-même lu. Voir [step-up avant les actions sensibles](https://docs.didit.me/fr/authentication/verified-identity.md#vérification-renforcée-avant-les-actions-sensibles).
4. **Prenez `vendor_data` depuis le token vérifié**, jamais depuis un champ envoyé par le navigateur, et utilisez-le pour les vérifications et les transactions de la personne.

## Sessions

| Événement | Ce qui se passe |
| - | - |
| Connexion | Une session démarre. Sa durée correspond à votre `session_lifetime` (30 jours par défaut) et elle prend fin plus tôt après `idle_timeout` sans activité (1 jour par défaut). |
| Toutes les quelques minutes | Le SDK renouvelle le token d'accès, qui dure 5 minutes au maximum. Le token de renouvellement fait l'objet d'une rotation : chaque token ne fonctionne qu'une seule fois. |
| Un token de renouvellement déjà utilisé est envoyé de nouveau | Didit considère qu'il s'agit d'un vol et met fin à la session. N'effectuez qu'un seul renouvellement à la fois par session. |
| Connexion sur un autre appareil | Avec `multiple_sessions: false`, les autres sessions de la personne prennent fin. |
| Réinitialisation du mot de passe | Toutes les sessions prennent fin lorsque `revoke_on_password_change` est activé (par défaut). |
| Déconnexion | `DELETE /session/` met fin à la session, et votre application redirige la personne vers votre `post_logout_redirect_uri`. |
| Votre équipe intervient | La console peut révoquer une session, déconnecter une personne partout ou la bloquer. Consultez le [guide de la console](https://docs.didit.me/fr/authentication/console.md#connexions-et-sessions). |

Modifiez les durées dans **Authentication > Security and sessions**, ou par API dans les [paramètres de l'application](https://docs.didit.me/fr/authentication/overview.md#paramètres-de-l’application).

![La vue Active sessions de la Business Console de Didit, listant les sessions ouvertes avec l'appareil, la localisation, la date de début, la date de dernière activité, la date de fin et un bouton Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, avec Revoke sur chaque session.

## Applications natives

Didit renvoie les utilisateurs vers une application native uniquement par une redirection HTTPS : il n'accepte aucun schéma d'URL personnalisé.

* **iOS :** faites de la redirection un domaine associé, avec `webcredentials` dans votre `apple-app-site-association`.
* **Android :** faites de la redirection un App Link, avec votre `assetlinks.json`.
* Enregistrez chaque URL de redirection sous **Authentication > Security and sessions**, comme une URL de rappel web.

Pour les clés d'accès de votre application, enregistrez les applications qui partagent les clés d'accès de votre application avec `PUT native-apps/` sur l'[API de gestion de l'authentification](https://docs.didit.me/fr/authentication/set-up-by-api.md).
Didit les liste ensuite dans les fichiers `apple-app-site-association` et `assetlinks.json` qu'il sert sur l'origine de connexion de votre application.
`MANAGEMENT_BASE` est l'adresse de l'API de gestion de votre application, et une clé API avec le périmètre `authentication` en écriture peut effectuer l'appel.
L'appel remplace les deux listes : envoyez donc les deux :

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Champ | Règle |
| - | - |
| `ios_app_ids` | Jusqu'à 10 entrées, chacune composée de votre Team ID et de votre identifiant de bundle, par exemple `ABCDE12345.com.example.app`. |
| `android_apps` | Jusqu'à 10 applications, chacune avec son `package_name` et de 1 à 5 empreintes SHA-256 du certificat de signature. |

Les guides de démarrage rapide [iOS](https://docs.didit.me/fr/authentication/quickstarts/ios.md) et [Android](https://docs.didit.me/fr/authentication/quickstarts/android.md) montrent le côté application.

## Connecter la vérification d'identité et la Surveillance des transactions

Chaque personne dispose d'une seule valeur `vendor_data`, présente dans ses tokens et dans sa session.
Utilisez-la comme `vendor_data` lorsque vous [créez une session de vérification](https://docs.didit.me/fr/sessions-api/create-session.md) ou [soumettez une transaction](https://docs.didit.me/fr/transaction-monitoring/transactions.md). La console affiche alors les connexions, les vérifications et les transactions d'une même personne.

* Pour vérifier les personnes lors de l'inscription, ou à nouveau avant un versement, sans créer de parcours de vérification, utilisez [identité vérifiée](https://docs.didit.me/fr/authentication/verified-identity.md).
* Les événements de connexion sont transmis automatiquement aux [règles d'événements](https://docs.didit.me/fr/transaction-monitoring/event-rules.md) et aux vues antifraude. N'envoyez pas vos propres événements `auth.login` pour les mêmes connexions.
* Une connexion réussie n'approuve jamais une vérification ni une transaction : traitez séparément la décision propre à chaque produit.

Consultez [garder une même personne à travers les produits](https://docs.didit.me/fr/authentication/overview.md#garder-une-même-personne-entre-les-produits).

## Recevoir les événements de connexion

Abonnez une [destination de webhook](https://docs.didit.me/fr/integration/webhooks.md) aux types `auth.*` dont vous avez besoin, par exemple `auth.new_device` ou `auth.account_locked`.
Effectuez la déduplication à partir de `auth_event.event_id`, et vérifiez la signature comme pour tout webhook Didit.
Consultez [les événements et les webhooks](https://docs.didit.me/fr/authentication/events-and-webhooks.md) pour chaque type et son payload.

## Migrer les utilisateurs existants

Si vos utilisateurs disposent déjà de comptes sur une autre plateforme d'identité ou dans votre propre base de données, [importez-les](https://docs.didit.me/fr/authentication/migration.md) avant de modifier le mode de connexion.
Importez leurs hachages de mot de passe lorsque la source les fournit, conservez leurs liens de connexion sociale, et conservez vos propres identifiants utilisateur sous la forme `external_id`, qui devient leur `vendor_data`.
Rien ne change pour eux tant que vous n'avez pas basculé votre application vers Didit.

## Liste de contrôle avant la mise en production

1. L'authentification est activée pour votre application Live sur la page **Products**.
2. Vos URL de redirection `https://` et origines autorisées de production sont enregistrées sur l'application Live. Une application Live n'accepte aucune adresse `http://`.
3. Chaque méthode de connexion sociale utilise l'identifiant client et le secret de votre propre application : les identifiants de test de Didit ne fonctionnent qu'en Sandbox.
4. Votre configuration de production contient la clé publique Live (`pk_live_`) et votre émetteur Live.
5. Votre politique MFA, la durée de vie de la session, le délai d'inactivité, la longueur des mots de passe et la politique d'inscription correspondent à vos besoins. Consultez les [paramètres de l'application](https://docs.didit.me/fr/authentication/overview.md#paramètres-de-l’application).
6. La [protection contre les bots](https://docs.didit.me/fr/authentication/bot-protection.md) est activée, ainsi que le contrôle des mots de passe compromis.
7. Votre backend vérifie chaque token d'accès et appelle `GET /session/` avant les actions sensibles.
8. Votre identité visuelle, les textes des pages ainsi que les liens vers les conditions d'utilisation et la politique de confidentialité sont configurés. Si vous prévoyez un [domaine personnalisé](https://docs.didit.me/fr/authentication/branding-and-custom-domain.md#domaine-personnalisé), activez-le avant que les utilisateurs n'ajoutent des clés d'accès.
9. Votre destination de webhook est abonnée aux types `auth.*` que vous gérez.
10. Vous avez testé sur l'application Live l'inscription, la connexion des utilisateurs existants, l'annulation, le mot de passe oublié, la MFA, l'expiration de la session, la déconnexion et une session révoquée.

## Dépannage

| Symptôme | Cause et solution |
| - | - |
| Toutes les routes d'exécution renvoient `404` | L'authentification est désactivée pour l'application, ou l'adresse mélange une origine sandbox et une origine de production. Activez-la depuis la page **Products**, et utilisez l'origine indiquée par votre clé publiable. |
| La page de connexion renvoie `400` et vous demande d'enregistrer une adresse, ou `POST /authorize/` renvoie `invalid_redirect_uri` | Le `redirect_uri` n'est pas enregistré à l'identique : le schéma, l'hôte, le port, le chemin et la requête doivent correspondre caractère par caractère. Voir [URL de redirection](https://docs.didit.me/fr/authentication/overview.md#url-de-redirection). |
| Un appel depuis le navigateur vers votre origine de connexion renvoie `403` avec `origin_not_allowed` | Votre origine web ne figure pas dans **Allowed origins**. Ajoutez-la sans chemin ni barre oblique finale. |
| `POST /token/` renvoie `invalid_grant` | Le code a déjà été utilisé ou date de plus de 60 secondes, ou il a été envoyé avec un autre vérificateur PKCE ou un autre `redirect_uri`. Pour un renouvellement, le token de renouvellement a déjà été utilisé, ce qui met fin à la session. Relancez la connexion. |
| Une connexion par mot de passe renvoie `invalid_credentials` avec le bon mot de passe | L'e-mail n'est pas vérifié, ou le compte est verrouillé ou bloqué. Didit renvoie volontairement la même réponse. Vérifiez la personne dans **Users**. |
| `GET /session/` renvoie `401` | La session a été révoquée, est restée inactive ou a expiré, la personne a été bloquée, le token a été remplacé lors d'un renouvellement, ou la session ne respecte plus votre politique MFA. Renouvelez le token ou reconnectez la personne. |
| L'ajout d'une clé d'accès ou d'un authentificateur renvoie `403 reauthentication_required` | Ces opérations exigent une session créée au cours des 5 dernières minutes. Reconnectez d'abord la personne. |
| L'envoi d'un code par téléphone renvoie `503 delivery_unavailable` | Le code n'a pas pu être livré. Laissez la personne réessayer ou proposez une autre méthode. |
| Un appel renvoie `429` | Vous avez atteint une limite de débit. Réessayez après le délai indiqué dans `Retry-After`. Voir [limites de débit](https://docs.didit.me/fr/authentication/bot-protection.md#limites-de-débit). |
| Un appel de configuration avec une clé API renvoie `409 product_disabled` | L'authentification est désactivée pour l'application. Une personne l'active dans la console. |
| Un appel renvoie `403 plan_required` | La fonctionnalité, comme les rôles personnalisés ou les liens de configuration SSO entreprise, nécessite le forfait Scale ou Enterprise. Les applications sandbox y ont accès quel que soit le forfait. |
| Les tokens échouent après l'activation d'un domaine personnalisé | L'émetteur et la clé publiable ont changé. Copiez la nouvelle clé dans votre application et mettez à jour l'émetteur que vérifie votre backend. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.