FranceConnect v2 : guide d'intégration et migration pour les apps santé

FranceConnect v1 a été décommissionné en octobre 2025. Les anciennes URLs en /api/v1/ retournent désormais des 404. Si vous intégrez FranceConnect aujourd'hui ou si vous maintenez un service qui tournait sur v1, ce guide est pour vous.

Chez Bob le développeur, on utilise FranceConnect pour authentifier les patients sur des plateformes de téléconsultation. Cet article couvre l'intégration complète en v2 et la checklist de migration depuis v1.

L'essentiel :

Toutes les URLs passent de /api/v1/ à /api/v2/

Le endpoint de logout change : /logout devient /session/end

Le minimum pour state et nonce passe à 32 caractères

La réponse /userinfo est désormais signée (vérification obligatoire)

Un nouveau paramètre iss est ajouté au callback

Les scopes individuels restent valides, mais de nouveaux scopes groupés apparaissent

FranceConnect en 2 minutes : ce que les développeurs doivent savoir

FranceConnect est le fédérateur d'identité de l'État français, opéré par la DINUM. Il permet aux usagers de s'authentifier sur votre service en utilisant un compte existant : impots.gouv.fr, Ameli, La Poste, MSA, ou d'autres fournisseurs d'identité partenaires.

Le protocole sous-jacent est OpenID Connect 1.0 avec un Authorization Code Flow classique. L'utilisateur est redirigé vers FranceConnect, choisit son fournisseur d'identité, s'authentifie, puis revient sur votre service avec un code d'autorisation que votre backend échange contre des tokens.

FranceConnect existe en deux niveaux :

FranceConnect (eIDAS Low, acr_values=eidas1) : identité déclarative, suffisant pour la majorité des services y compris l'authentification des patients
FranceConnect+ (eIDAS Substantial, acr_values=eidas2) : identité vérifiée en face-à-face, requis pour les services sensibles (finance, certaines démarches santé)

Pour une application de téléconsultation, FranceConnect standard suffit côté patient. Les médecins passent par Pro Santé Connect, le fédérateur sectoriel de la santé.

Ce qui change entre v1 et v2

Si vous venez de v1 ou si vous avez lu de la documentation datée, voici les différences à connaître.

Tableau comparatif v1 vs v2

Élément	v1 (mort)	v2 (actuel)
Base path	`/api/v1/`	`/api/v2/`
Endpoint logout	`/api/v1/logout`	`/api/v2/session/end`
Endpoint JWKS	Non disponible	`/api/v2/jwks`
Méthode /authorize	GET uniquement	GET ou POST
Réponse /userinfo	Non signée	Signée (vérification obligatoire)
Paramètre `iss`	Absent du callback	Ajouté au callback (`?code=...&state=...&iss=...`)
`acr_values`	Optionnel	Obligatoire
`state` / `nonce`	Min. 22 chars	Min. 32 chars
Scopes groupés	Non disponibles	`profile`, `birth`, `identite_pivot`

Les changements critiques

La signature du userinfo. En v2, la réponse du endpoint /userinfo est signée. Vous devez vérifier cette signature en récupérant les clés publiques via le endpoint JWKS (/api/v2/jwks). C'est une protection contre la falsification des données d'identité en transit.

Le paramètre iss dans le callback. En v2, FranceConnect ajoute un paramètre iss à l'URL de callback. Il identifie l'émetteur du code d'autorisation. Votre code de parsing du callback doit gérer ce paramètre supplémentaire (même si vous ne l'utilisez pas activement, il est présent dans l'URL).

Le minimum 32 caractères pour state/nonce. En v1, le minimum était 22 caractères. En v2, FC rejette toute valeur inférieure à 32. La solution la plus simple : crypto.randomBytes(32).toString('hex'), qui produit 64 caractères hexadécimaux.

Endpoints FranceConnect v2 : sandbox et production

Sandbox (environnement d'intégration)

Endpoint	URL
Discovery	`https://fcp-low.integ01.dev-franceconnect.fr/api/v2/.well-known/openid-configuration`
Authorize	`https://fcp-low.integ01.dev-franceconnect.fr/api/v2/authorize`
Token	`https://fcp-low.integ01.dev-franceconnect.fr/api/v2/token`
UserInfo	`https://fcp-low.integ01.dev-franceconnect.fr/api/v2/userinfo`
Logout	`https://fcp-low.integ01.dev-franceconnect.fr/api/v2/session/end`
JWKS	`https://fcp-low.integ01.dev-franceconnect.fr/api/v2/jwks`

Le host sandbox est fcp-low.integ01.dev-franceconnect.fr. L'ancien fcp.integ01 était celui de v1.

Production

Les URLs de production exactes vous sont communiquées après validation de votre habilitation Datapass. Elles suivent le pattern /api/v2/ avec un host différent de la sandbox.

En sandbox, HTTP est autorisé pour les callbacks sur localhost (pratique pour le développement local). En production, HTTPS est obligatoire pour toutes les URLs de callback.

Scopes et claims en v2 : individuels et groupés

FranceConnect v2 conserve les scopes individuels de v1 et ajoute des scopes groupés.

Scopes individuels

Chaque scope retourne un ou deux claims spécifiques :

Scope	Claims retournés
`openid`	`sub` (obligatoire)
`given_name`	`given_name`, `given_name_array`
`family_name`	`family_name`
`birthdate`	`birthdate` (YYYY-MM-DD)
`email`	`email`
`gender`	`gender`
`birthplace`	`birthplace`
`birthcountry`	`birthcountry`
`preferred_username`	`preferred_username`

Scopes groupés (nouveauté v2)

Scope	Claims inclus
`profile`	`family_name`, `given_name`, `preferred_username`, `gender`, `birthdate`
`birth`	`birthplace`, `birthcountry`
`identite_pivot`	`given_name`, `family_name`, `birthdate`, `gender`, `birthplace`, `birthcountry`

Les deux approches sont valides. openid given_name family_name birthdate email retourne les mêmes claims que openid profile email (en excluant preferred_username et gender). Choisissez la notation qui vous convient.

Nouveauté v2 : given_name_array

En v2, le scope given_name retourne aussi given_name_array, un tableau de tous les prénoms de l'utilisateur. given_name reste une chaîne simple (le premier prénom), tandis que given_name_array contient la liste complète.

Le claim `sub`

Le sub FranceConnect est un identifiant opaque, unique par couple (utilisateur, fournisseur de service). Un même citoyen aura un sub différent sur chaque service. Il est stable dans le temps pour un couple donné, ce qui en fait une bonne clé primaire pour identifier vos utilisateurs.

Le logout obligatoire : la règle que personne ne respecte du premier coup

FranceConnect impose contractuellement un logout redirect. Quand un utilisateur se déconnecte de votre service, vous devez aussi le déconnecter de FranceConnect. Si vous ne respectez pas cette obligation, la DINUM peut révoquer votre habilitation.

Le flow de déconnexion

1. L'utilisateur clique "Se déconnecter"
2. Votre backend détruit la session locale
3. Redirect vers FC : /api/v2/session/end?id_token_hint=...&post_logout_redirect_uri=...
4. FranceConnect déconnecte l'utilisateur
5. FranceConnect redirige vers votre post_logout_redirect_uri

L'URL de logout v2

GET https://<host>/api/v2/session/end
  ?id_token_hint=<id_token_original>
  &state=<random>
  &post_logout_redirect_uri=<votre_url_post_logout>

Le point qui piège beaucoup de développeurs : vous devez conserver l'id_token en session dès la connexion. Il est requis comme id_token_hint au moment du logout. Si vous le jetez après avoir extrait les claims, votre logout ne fonctionnera pas.

En v2, le endpoint est /api/v2/session/end. L'ancien /api/v1/logout n'existe plus.

Implémentation NestJS complète

La strategy Passport

// auth/strategies/franceconnect.strategy.ts
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PassportStrategy } from '@nestjs/passport';
import { Strategy } from 'passport-openidconnect';

@Injectable()
export class FranceConnectStrategy extends PassportStrategy(
  Strategy,
  'franceconnect',
) {
  constructor(private configService: ConfigService) {
    super({
      issuer: configService.get('FC_ISSUER'),
      authorizationURL: configService.get('FC_AUTHORIZATION_URL'),
      tokenURL: configService.get('FC_TOKEN_URL'),
      userInfoURL: configService.get('FC_USERINFO_URL'),
      clientID: configService.get('FC_CLIENT_ID'),
      clientSecret: configService.get('FC_CLIENT_SECRET'),
      callbackURL: configService.get('FC_CALLBACK_URL'),
      scope: 'openid given_name family_name birthdate email',
    });
  }

  async validate(
    accessToken: string,
    refreshToken: string,
    profile: any,
  ) {
    return {
      fcSub: profile.sub,
      firstName: profile.given_name,
      lastName: profile.family_name,
      birthdate: profile.birthdate,
      email: profile.email,
    };
  }
}

Les variables d'environnement

# FranceConnect v2 — Sandbox
FC_ISSUER=https://fcp-low.integ01.dev-franceconnect.fr
FC_AUTHORIZATION_URL=https://fcp-low.integ01.dev-franceconnect.fr/api/v2/authorize
FC_TOKEN_URL=https://fcp-low.integ01.dev-franceconnect.fr/api/v2/token
FC_USERINFO_URL=https://fcp-low.integ01.dev-franceconnect.fr/api/v2/userinfo
FC_LOGOUT_URL=https://fcp-low.integ01.dev-franceconnect.fr/api/v2/session/end
FC_CLIENT_ID=your-client-id
FC_CLIENT_SECRET=your-client-secret
FC_CALLBACK_URL=https://your-app.example.com/auth/fc/callback
FC_POST_LOGOUT_REDIRECT_URI=https://your-app.example.com

Gestion du logout dans le controller

// auth/auth.controller.ts (extrait)
@Get('logout')
async logout(@Req() req, @Res() res) {
  const idToken = req.session.idToken; // Conservé depuis le login
  const logoutUrl = this.configService.get('FC_LOGOUT_URL');
  const postLogoutUri = this.configService.get('FC_POST_LOGOUT_REDIRECT_URI');
  const state = crypto.randomBytes(32).toString('hex');

  // Détruire la session locale
  req.session.destroy();

  // Rediriger vers FC pour le logout fédéré
  const params = new URLSearchParams({
    id_token_hint: idToken,
    state,
    post_logout_redirect_uri: postLogoutUri,
  });

  return res.redirect(`${logoutUrl}?${params.toString()}`);
}

N'oubliez pas de stocker l'id_token en session dès le callback de login. Sans lui, cette redirection échoue.

Les 7 erreurs qui bloquent votre intégration FranceConnect

1. Utiliser des URLs v1. Les endpoints /api/v1/ retournent des 404 depuis octobre 2025. Tout doit pointer vers /api/v2/. Vérifiez aussi le host sandbox : c'est fcp-low.integ01, pas fcp.integ01.

2. Générer des state/nonce trop courts. En v2, le minimum est 32 caractères. FC rejette silencieusement les valeurs plus courtes. Utilisez crypto.randomBytes(32).toString('hex') pour 64 caractères hex.

3. Oublier le logout redirect. Le logout fédéré est une obligation contractuelle. FranceConnect peut révoquer votre accès si vous ne le respectez pas. L'endpoint est /api/v2/session/end, pas /logout.

4. Jeter l'id_token après le login. L'id_token est requis comme id_token_hint pour le logout. Stockez-le en session dès la connexion et ne le supprimez qu'à la déconnexion effective.

5. Demander des scopes non justifiés. Datapass rejette les demandes qui incluent des scopes sans justification métier. Si vous n'avez pas besoin de gender ou birthplace, ne les demandez pas.

6. Avoir une callback URL qui ne correspond pas exactement. FranceConnect compare votre URL de callback caractère par caractère avec celle déclarée dans Datapass. Un slash de trop, un port manquant, une différence HTTP/HTTPS : le flow échoue. Pas de wildcard, pas de variation.

7. Ignorer la signature du userinfo en v2. La réponse /userinfo est signée. Votre backend doit récupérer les clés JWKS (/api/v2/jwks) et vérifier la signature. Ignorer cette vérification, c'est accepter des données d'identité potentiellement falsifiées.

Checklist migration v1 vers v2

Si votre service tournait sur FranceConnect v1, voici la liste exhaustive des modifications à appliquer :

La documentation officielle de migration est disponible sur docs.partenaires.franceconnect.gouv.fr/fs/migration/.

Le processus d'habilitation Datapass

L'habilitation FranceConnect passe par datapass.api.gouv.fr et suit un processus plus rapide que celui de Pro Santé Connect.

Étape	Durée estimée
Validation du dossier Datapass	~5 jours ouvrés
Développement et tests en sandbox	1-2 semaines
Tests et recette	1 semaine
Passage en production	~5 jours ouvrés
Total	~4-5 semaines

Les documents à fournir : description du service et sa finalité, justification du besoin d'identité vérifiée, URL du service (même en développement), politique de confidentialité, et contacts technique et DPO.

Un point souvent oublié : chaque scope demandé doit être justifié individuellement. Si vous demandez email, expliquez pourquoi vous en avez besoin. Les demandes généreuses ("on prend tout au cas où") sont refusées.

Le bouton officiel

FranceConnect impose l'utilisation de son bouton officiel, téléchargeable sur l'espace partenaire après habilitation. Le texte doit être exactement "S'identifier avec FranceConnect", accompagné d'un lien "Qu'est-ce que FranceConnect ?" en dessous. Aucune personnalisation n'est autorisée : dimensions, couleurs, marges et texte sont imposés.

FAQ : les questions fréquentes sur FranceConnect v2

FranceConnect v1 fonctionne-t-il encore ?

Non. FranceConnect v1 a été décommissionné en octobre 2025. Les endpoints /api/v1/ ne répondent plus. Tous les fournisseurs de services doivent être sur v2. Si vous avez commencé votre intégration après juin 2024, vous êtes déjà sur la bonne plateforme.

FranceConnect est-il gratuit ?

Oui. FranceConnect est un service public gratuit, sans frais d'intégration ni redevance. La seule condition est d'obtenir une habilitation via Datapass et de respecter les obligations techniques (logout, bouton officiel, sécurité).

Quelle différence entre FranceConnect et FranceConnect+ ?

FranceConnect standard correspond au niveau eIDAS Low (acr_values=eidas1). L'identité est déclarative. FranceConnect+ correspond au niveau eIDAS Substantial (acr_values=eidas2) et requiert une vérification d'identité en face-à-face. FranceConnect+ est nécessaire pour les démarches sensibles (ouverture de compte bancaire, certains services de santé). Pour l'authentification des patients en téléconsultation, FranceConnect standard est suffisant.

Peut-on utiliser FranceConnect pour authentifier des médecins ?

Non. FranceConnect authentifie les citoyens, pas les professionnels de santé. Pour les médecins, vous devez utiliser Pro Santé Connect, le fédérateur d'identité sectoriel de l'ANS, qui garantit l'identification via la carte CPS ou l'e-CPS et fournit le numéro RPPS.

Le bouton FranceConnect est-il personnalisable ?

Non. FranceConnect impose un bouton officiel avec un design fixe : couleurs, dimensions, marges et texte ("S'identifier avec FranceConnect") sont imposés. Un lien "Qu'est-ce que FranceConnect ?" doit figurer sous le bouton. Le kit graphique est disponible dans l'espace partenaire après habilitation.

Conclusion

FranceConnect v2 reste un standard OpenID Connect classique. Les changements par rapport à v1 sont ciblés (signature userinfo, endpoints renommés, minimum state/nonce) mais peuvent bloquer une intégration si on ne les connaît pas.

Pour une application e-santé, FranceConnect authentifie vos patients tandis que Pro Santé Connect authentifie vos médecins. Les deux reposent sur OIDC et peuvent cohabiter dans le même backend avec deux Passport strategies distinctes.

Vous construisez une plateforme de téléconsultation ou une app santé ? Chez Bob le développeur, on intègre FranceConnect et Pro Santé Connect depuis plusieurs années. Contactez-nous pour discuter de votre projet.

L'agence d'experts pour votre tech

Accélérez dès maintenant votre innovation grâce à votre équipe de développeurs dédiée !

FranceConnect v2 : guide d'intégration et migration pour les apps santé

FranceConnect en 2 minutes : ce que les développeurs doivent savoir

Ce qui change entre v1 et v2

Tableau comparatif v1 vs v2

Les changements critiques

Endpoints FranceConnect v2 : sandbox et production

Sandbox (environnement d'intégration)

Production

Scopes et claims en v2 : individuels et groupés

Scopes individuels

Scopes groupés (nouveauté v2)

Nouveauté v2 : given_name_array

Le claim `sub`

Le logout obligatoire : la règle que personne ne respecte du premier coup

Le flow de déconnexion

L'URL de logout v2

Implémentation NestJS complète

La strategy Passport

Les variables d'environnement

Gestion du logout dans le controller

Les 7 erreurs qui bloquent votre intégration FranceConnect

Checklist migration v1 vers v2

Le processus d'habilitation Datapass

Le bouton officiel

FAQ : les questions fréquentes sur FranceConnect v2

FranceConnect v1 fonctionne-t-il encore ?

FranceConnect est-il gratuit ?

Quelle différence entre FranceConnect et FranceConnect+ ?

Peut-on utiliser FranceConnect pour authentifier des médecins ?

Le bouton FranceConnect est-il personnalisable ?

Conclusion

La newsletter qu'on n'ignore pas

L'agence d'experts pour votre tech

Accélérez dès maintenant votre innovation grâce à votre équipe de développeurs dédiée !

FranceConnect v2 : guide d'intégration et migration pour les apps santé

FranceConnect en 2 minutes : ce que les développeurs doivent savoir

Ce qui change entre v1 et v2

Tableau comparatif v1 vs v2

Les changements critiques

Endpoints FranceConnect v2 : sandbox et production

Sandbox (environnement d'intégration)

Production

Scopes et claims en v2 : individuels et groupés

Scopes individuels

Scopes groupés (nouveauté v2)

Nouveauté v2 : given_name_array

Le claim sub

Le logout obligatoire : la règle que personne ne respecte du premier coup

Le flow de déconnexion

L'URL de logout v2

Implémentation NestJS complète

La strategy Passport

Les variables d'environnement

Gestion du logout dans le controller

Les 7 erreurs qui bloquent votre intégration FranceConnect

Checklist migration v1 vers v2

Le processus d'habilitation Datapass

Le bouton officiel

FAQ : les questions fréquentes sur FranceConnect v2

FranceConnect v1 fonctionne-t-il encore ?

FranceConnect est-il gratuit ?

Quelle différence entre FranceConnect et FranceConnect+ ?

Peut-on utiliser FranceConnect pour authentifier des médecins ?

Le bouton FranceConnect est-il personnalisable ?

Conclusion

La newsletter qu'on n'ignore pas

Le claim `sub`