Identité fédérée

Le parent se connecte à magot avec l'identité de sa banque. magot n'a ni mot de passe ni compte à créer pour les clients d'une banque intégrée : la banque reste le fournisseur d'identité, magot vérifie ses jetons.

Deux intégrations, un seul point d'échange

Intégration	Jeton présenté à magot
SDK dans l'app de la banque	un jeton JWT que l'app obtient de l'IdP de la banque pour magot (access token JWT ou id_token)
App magot marque blanche	l'`id_token` obtenu par une connexion OIDC (code + PKCE) à l'IdP de la banque

Dans les deux cas, l'app l'échange contre une session magot par OAuth 2.0 Token Exchange (RFC 8693).

Échange

POST /v1/identity/token
Content-Type: application/x-www-form-urlencoded   (JSON accepté aussi)

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<JWT de la banque>
&subject_token_type=urn:ietf:params:oauth:token-type:id_token
&device_id=<facultatif : appareil magot d'une session précédente>

subject_token_type : id_token, jwt ou access_token (JWT uniquement).

Réponse (Cache-Control: no-store) :

{
  "access_token": "mgt_p_…",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "adult_id": "…", "household_id": "…", "device_id": "…",
  "provisioned": false
}

Le jeton magot s'utilise ensuite en Authorization: Bearer sur toute l'API.

Erreurs (RFC 6749 §5.2) : 400 avec error parmi invalid_request, invalid_grant (jeton invalide, expiré, émetteur inconnu, identité non liée), unsupported_grant_type, unsupported_token_type.

Vérification du jeton bancaire

émetteur (iss) enregistré pour l'établissement, signature vérifiée avec les clés publiques de la banque (URL JWKS en HTTPS, mise en cache et rafraîchie à la rotation des clés, ou jeu de clés statique) ;
algorithmes asymétriques uniquement (RS256, PS256, ES256, EdDSA, selon la configuration) : none et HMAC sont toujours refusés ;
audience (aud) propre à magot chez cet établissement ;
exp et iat obligatoires, tolérance d'horloge de 60 s ;
sujet : sub par défaut (configurable), identifiant pseudonyme du client chez la banque — magot ne demande ni e-mail ni numéro de client.

Le jeton d'une banque ne peut ouvrir une session que dans son établissement : le même identifiant client dans deux banques donne deux parents distincts.

Sessions

durée : le minimum entre la durée configurée pour l'établissement (défaut 1 h, de 60 s à 24 h) et l'expiration du jeton bancaire. Une session magot ne survit jamais au jeton bancaire qui l'a ouverte ; l'app en rouvre une en échangeant un jeton frais ;
device_id réutilise l'appareil magot (et son jeton de notifications) et révoque la session précédente de cet appareil : un seul jeton actif par appareil ;
POST /v1/identity/logout révoque immédiatement le jeton présenté.

Premier passage d'un client

Réglé par établissement :

jit (défaut) : un client inconnu obtient son foyer magot à sa première connexion ; son nom d'affichage vient des claims name / given_name s'ils sont présents ;
link_only : seuls les clients déjà liés entrent. Un parent déjà inscrit par passkey lie son identité bancaire avec POST /v1/identity/federated-links (authentifié, même corps subject_token / subject_token_type). Une identité déjà liée à un autre parent : 409.

Traçabilité

Chaque échange, liaison et déconnexion est inscrit au journal d'audit (audit_log) : fournisseur, parent, appareil, création de foyer, durée.

Mise en service (exploitation magot)

tsx scripts/add-identity-provider.ts <tenant> <issuer> <audience> --jwks-uri https://…/jwks.json [--link-only] [--ttl 900]

puis redémarrage du service (ou kill -HUP). La banque communique son issuer, l'URL de ses clés publiques et l'audience qu'elle émettra pour magot.