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

# Annexe technique SAML

> Documentation technique de l'intégration SAML pour le SSO Serenest

## Protocole utilisé

Serenest utilise **SAML 2.0** (Security Assertion Markup Language) comme standard pour la gestion des intégrations SSO entre les fournisseurs d'identité tiers (IdP) et Serenest (fournisseur de service / SP).

L'objectif est de permettre aux utilisateurs connectés à un système tiers (ex. une application d'entreprise) d'accéder aux Webviews Serenest **sans avoir à se reconnecter manuellement**.

## Flux SAML détaillé

<img src="https://mintcdn.com/terros-2c115507/ykeFBEdLC1R75Vs_/images/FlowSAML.png?fit=max&auto=format&n=ykeFBEdLC1R75Vs_&q=85&s=27831c43a2465bd80eaa80058dc19445" alt="Flux SAML complet" style={{width: "25%"}} width="1024" height="1024" data-path="images/FlowSAML.png" />

<Steps>
  <Step title="Clic utilisateur">
    L'utilisateur clique sur un bouton dans l'application tierce pour accéder à Serenest.
  </Step>

  <Step title="Requête au backend">
    L'application tierce ouvre un navigateur interne et envoie une requête à son propre backend avec le **token d'authentification** de l'utilisateur et l'URL de destination souhaitée (paramètre `url`).
  </Step>

  <Step title="Génération de la réponse SAML">
    Le backend tiers génère une **réponse SAML**, l'encode en base64 et effectue une requête POST vers l'URL ACS de Serenest.
  </Step>

  <Step title="Vérification par Serenest">
    Serenest décode et vérifie la **signature SAML** (via le certificat `.crt` fourni).
  </Step>

  <Step title="Extraction et token">
    Serenest extrait les données utilisateur et génère un token d'accès interne.
  </Step>

  <Step title="Connexion automatique">
    Ce token est envoyé à l'application tierce, qui connecte automatiquement l'utilisateur.
  </Step>
</Steps>

## URLs ACS

| Environnement  | URL                                                         |
| -------------- | ----------------------------------------------------------- |
| Pré-production | `https://preprod.app.serenest.fr/api/auth/sso/serenest/acs` |
| Production     | `https://app.serenest.fr/api/auth/sso/serenest/acs`         |

## Structure de la SAMLResponse

Le payload de la SAMLResponse doit contenir les champs suivants :

| Champ SAML       | Description                              | Requis    |
| ---------------- | ---------------------------------------- | --------- |
| `emailaddress`   | Adresse email de l'utilisateur           | Oui       |
| `givenname`      | Prénom                                   | Oui       |
| `surname`        | Nom de famille                           | Oui       |
| `name`           | Nom complet                              | Oui       |
| `nameidentifier` | UUID du site tiers (lié à l'utilisateur) | Oui       |
| `badgenumber`    | Numéro de badge                          | Optionnel |
| `destination`    | URL cible dans Serenest (ex. `/menus`)   | Oui       |

**Format attendu** : POST form-data avec un seul champ nommé `SAMLResponse` contenant le XML encodé en Base64.

## Certificats et sécurité

Le tiers doit fournir à Serenest :

* Un **certificat X.509** (`.crt`)
* Une **clé publique** (`.pub`)

Ces fichiers sont utilisés pour :

* Authentifier la source de la requête SAML
* Valider la signature de la réponse
* Optionnellement générer un fichier de métadonnées IdP

## Flux de test

<Steps>
  <Step title="Partage du certificat">
    Le tiers partage son certificat `.crt` avec l'équipe Serenest.
  </Step>

  <Step title="Configuration de l'IdP">
    Serenest configure l'IdP dans son backend.
  </Step>

  <Step title="Échange de comptes de test">
    Un **compte de test** est échangé entre les deux parties.
  </Step>

  <Step title="Intégration du bouton SSO">
    Un bouton d'accès SSO est intégré dans l'application tierce.
  </Step>

  <Step title="Tests en pré-production">
    La réponse SAML est testée en environnement de pré-production.
  </Step>

  <Step title="Mise en production">
    Une fois validée, la configuration est répliquée en production.
  </Step>
</Steps>

## Bonnes pratiques et recommandations

<Warning>
  Ne pas créer automatiquement un compte dans Serenest si l'utilisateur n'existe pas (conformité RGPD).
</Warning>

* Vérifier la **période de validité** de la réponse SAML (via `NotOnOrAfter`).
* En cas d'erreur, fournir des logs incluant :
  * L'horodatage de la requête
  * L'ID de la réponse SAML
  * L'adresse email de l'utilisateur