> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dépannage et référence SSO

> Autorisations, URL de référence rapide et conseils de dépannage pour SAML SSO sur votre instance EK locale.

Cet article couvre les autorisations, les valeurs de référence rapide et les solutions aux problèmes SSO courants. Pour les instructions de configuration, consultez le [Guide de configuration des métadonnées SSO](/super-admin/sso/saml-sso-metadata-setup-guide).

## Autorisations

Toutes les actions de gestion des métadonnées SSO sont restreintes aux Super Administrateurs, à une exception près : un administrateur d'équipe peut télécharger les métadonnées IdP via un fichier pour le domaine de sa propre équipe.

| Action                                                                                  | Rôle requis                                                                                                      |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Afficher l'onglet Métadonnées SSO                                                       | Super Administrateur                                                                                             |
| Télécharger les métadonnées IdP via un fichier (`POST /admin/saml-metadata/upload`)     | Super Administrateur, ou un administrateur d'équipe dont `sso_domain` correspond au `email_domain` de son équipe |
| Télécharger les métadonnées IdP via XML collé (`POST /admin/saml-metadata/upload-text`) | Super Administrateur uniquement                                                                                  |
| Télécharger les métadonnées stockées (`GET /admin/saml-metadata/download`)              | Super Administrateur                                                                                             |
| Supprimer les métadonnées stockées (`DELETE /admin/saml-metadata/delete`)               | Super Administrateur                                                                                             |

<Note>
  Le point de terminaison des métadonnées SP à `/saml/well-known/sp-metadata` est public par conception. Il ne contient aucun secret — uniquement l'ID d'entité SP, l'URL ACS, le format NameID et le certificat de signature publique.
</Note>

## Référence rapide

<CardGroup cols={2}>
  <Card title="Hôte backend" icon="server">
    `<your-backend-host>` (par exemple `ek-api.corp.acme.com`)

    Gère tout le trafic SAML — métadonnées SP, initiation SSO et le point de terminaison ACS. **C'est le seul hôte que votre IdP doit connaître.**
  </Card>

  <Card title="Hôte frontend" icon="globe">
    `<your-frontend-host>` (par exemple `ek.corp.acme.com`)

    L'interface web que vos utilisateurs ouvrent. Configurée sur le backend via `FRONTEND_ROOT_URL`. **N'apparaît jamais dans la configuration IdP.**
  </Card>

  <Card title="URL des métadonnées SP" icon="link">
    ```
    https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    Partagez ceci avec votre administrateur IdP pour enregistrer EK en tant qu'application SAML.
  </Card>

  <Card title="URL ACS" icon="arrow-right-to-bracket">
    ```
    https://<your-backend-host>/user/generic/sso/saml/acs/admin
    ```

    Où votre IdP envoie les réponses SAML. Toujours l'hôte backend — jamais le frontend.
  </Card>

  <Card title="Point d'entrée SSO lancé par le SP" icon="right-to-bracket">
    ```
    https://<your-backend-host>/sso/login?enterprise_id=<email-domain>
    ```

    Le point de terminaison backend vers lequel le frontend redirige lorsqu'un utilisateur initie SSO.
  </Card>

  <Card title="Format NameID requis" icon="id-card">
    ```
    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    ```

    Votre IdP doit envoyer l'adresse e-mail de l'utilisateur dans ce format.
  </Card>
</CardGroup>

### Variables d'environnement du mode SSO frontend

| Variable                    | Description                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `VITE_ALLOW_ONLY_SSO_LOGIN` | `true` pour SSO à clic unique, `false` (par défaut) pour SSO modal par e-mail.                                                      |
| `VITE_SSO_ENTERPRISE_ID`    | Mode à clic unique uniquement. Doit correspondre à un domaine qui a des métadonnées IdP téléchargées dans l'onglet Métadonnées SSO. |

* **Où télécharger les métadonnées IdP ?** Tableau de bord Super Administrateur → onglet **Métadonnées SSO** → **Ajouter des métadonnées** / **Mise à jour**
* **Un document par domaine.** Le re-téléchargement remplace les métadonnées existantes. La suppression désactive SSO pour ce domaine.
* **Rôle requis ?** Super Administrateur pour toutes les actions, sauf que les administrateurs d'équipe peuvent télécharger via un fichier pour le domaine de leur propre équipe.

## Dépannage

<AccordionGroup>
  <Accordion title="Erreur &#x22;Veuillez entrer un domaine valide&#x22;">
    Le champ **Domaine e-mail de l'équipe SSO** s'attend à un domaine simple comme `acme.com` ou `eu.acme.co.uk`. Supprimez tout `@` initial, `https://`, chemins ou numéros de port avant de soumettre.
  </Accordion>

  <Accordion title="Erreur &#x22;Le fichier doit être un fichier XML&#x22;">
    Le téléchargeur de fichiers n'accepte que les fichiers avec l'extension `.xml`. Si votre IdP a fourni les métadonnées sous forme de fichier `.txt` ou sans extension, renommez-le en `.xml` ou basculez vers l'option **Coller le contenu XML** à la place.
  </Accordion>

  <Accordion title="Erreur &#x22;Le contenu ne semble pas être un XML valide&#x22;">
    Lors de l'utilisation de **Coller le contenu XML**, le contenu collé doit commencer par `<?xml` ou `<` après suppression des espaces blancs. Assurez-vous d'avoir copié le document de métadonnées complet et qu'aucun préambule ou commentaire n'a été inclus.
  </Accordion>

  <Accordion title="La connexion réussit avec l'IdP mais EK rejette l'assertion">
    Cela est presque toujours causé par l'une des raisons suivantes :

    * **Incompatibilité de certificat** — le certificat de signature IdP dans les métadonnées téléchargées ne correspond plus au certificat que votre IdP utilise réellement. Cela se produit généralement après une rotation de certificat IdP. Obtenez des métadonnées fraîches auprès de votre administrateur IdP et utilisez **Mise à jour**.
    * **Format NameID incorrect** — l'IdP n'envoie pas l'adresse e-mail comme NameID. Confirmez que le format est défini sur `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` du côté IdP.
    * **Incompatibilité d'ID d'entité** — l'audience ou l'ID d'entité configuré dans votre IdP ne correspond pas à votre ID d'entité d'instance EK. Reshérez les métadonnées XML SP d'EK et demandez à votre administrateur IdP de les réimporter.
  </Accordion>

  <Accordion title="L'utilisateur se connecte avec succès mais l'accès est refusé">
    Cela est contrôlé par **Super Administrateur → Contrôles d'accès**, pas par l'onglet Métadonnées SSO. Consultez le guide [**Contrôles d'accès SAML**](/super-admin/sa-access-controls) pour plus de détails sur `Autoriser tout nouvel utilisateur` par rapport à `Restreindre aux métadonnées SAML` et les [règles d'affectation d'équipe/projet automatisées](/super-admin/sa-automated-management).
  </Accordion>

  <Accordion title="SSO lancé par IdP ne fonctionne pas">
    Par défaut, EK n'accepte que les réponses SAML lancées à partir de son propre point de terminaison `/sso/login` — ce qui signifie SSO lancé par le SP uniquement. Pour activer SSO lancé par IdP (non sollicité), l'opérateur local doit définir `ALLOW_IDP_INITIATED_SSO=true` sur le backend EK et redémarrer le service. C'est un paramètre au niveau du déploiement, pas quelque chose de configurable dans l'onglet Métadonnées SSO.
  </Accordion>

  <Accordion title="IdP configuré avec l'hôte frontend au lieu de l'hôte backend">
    Si l'application IdP a été configurée avec le nom d'hôte frontend EK pour l'URL ACS ou l'ID d'entité, les réponses SAML seront envoyées au mauvais service et l'authentification échouera silencieusement — généralement en affichant une erreur 404 ou une page d'erreur générique après l'écran de connexion IdP.

    Demandez à votre administrateur IdP de confirmer :

    * L'**URL ACS** est `https://<your-backend-host>/user/generic/sso/saml/acs/admin`.
    * L'**ID d'entité / Audience** correspond au `entityID` dans `https://<your-backend-host>/saml/well-known/sp-metadata`.

    L'hôte frontend ne doit jamais apparaître dans la configuration de l'application SAML de l'IdP.
  </Accordion>

  <Accordion title="Le bouton SSO à clic unique ne fait rien (ou affiche &#x22;Impossible de déterminer le domaine pour la connexion SSO&#x22;)">
    `VITE_SSO_ENTERPRISE_ID` n'est pas défini sur le frontend. Définissez-le sur le domaine e-mail pour lequel vous avez téléchargé les métadonnées IdP, puis redéployez ou redémarrez le frontend pour que la valeur prenne effet.
  </Accordion>

  <Accordion title="Le bouton SSO à clic unique redirige mais SSO échoue sur le backend">
    `VITE_SSO_ENTERPRISE_ID` est défini mais ne correspond à aucun domaine avec métadonnées téléchargées dans l'onglet Métadonnées SSO. Corrigez cela par l'une des deux méthodes :

    * Télécharger les métadonnées IdP pour le domaine actuellement dans `VITE_SSO_ENTERPRISE_ID` — recommandé, car cela garde votre configuration frontend inchangée.
    * Mise à jour de `VITE_SSO_ENTERPRISE_ID` pour correspondre à un domaine qui a déjà des métadonnées téléchargées, puis redéployement ou redémarrage du frontend.

    Les deux valeurs doivent correspondre exactement (insensible à la casse).
  </Accordion>

  <Accordion title="SSO modal par e-mail affiche 'Votre organisation n'est pas configurée pour la connexion SSO'">
    Le domaine e-mail de l'utilisateur n'a pas de métadonnées IdP téléchargées dans l'onglet Métadonnées SSO. Soit téléchargez les métadonnées pour ce domaine, soit demandez à l'utilisateur de se connecter en utilisant l'e-mail/mot de passe ou OAuth à la place.
  </Accordion>

  <Accordion title="Les utilisateurs terminent SSO mais atterrissent sur la mauvaise page ou obtiennent une erreur de redirection">
    Après une réponse SAML réussie, EK redirige l'utilisateur vers l'URL frontend définie par `FRONTEND_ROOT_URL` sur le backend. Si cette variable n'est pas définie, pointe vers le mauvais hôte, ou utilise le mauvais schéma ou port, l'utilisateur semblera terminer l'authentification mais finira sur une page cassée.

    Demandez à votre opérateur local de confirmer que `FRONTEND_ROOT_URL` correspond exactement à `https://<your-frontend-host>` — schéma correct, port correct, pas de problèmes de barre oblique finale.
  </Accordion>
</AccordionGroup>