Tester la connexion SSO

Vérifie la configuration SSO/SAML de l'espace de travail (accessibilité des métadonnées IdP, présence du certificat, état d'activation) et renvoie le mapping des claims.

2 min de lectureTélécharger en PDF

Requête exemple

{}

Réponse exemple

{
  "ok": true,
  "checks": [
    {
      "check": "metadata_url_reachable",
      "detail": "HTTP 200",
      "status": "ok"
    },
    {
      "check": "certificate_present",
      "detail": "Inline cert missing - relying on metadata URL fetch",
      "status": "warn"
    },
    {
      "check": "enabled_flag",
      "detail": "SSO is active",
      "status": "ok"
    }
  ],
  "claim_mapping": {
    "name": "displayName",
    "email": "NameID",
    "groups": "memberOf"
  }
}

POST/v1/sso/test-connectionValide la configuration SSO de l'espace de travail et renvoie une liste de vérifications de diagnostic.

Cet endpoint exécute une série de vérifications de diagnostic sur la configuration SSO/SAML de l'espace de travail courant, sans modifier aucun état. Il lit la configuration stockée (URL de métadonnées de l'IdP, certificat IdP, indicateur d'activation), tente un appel HTTP vers l'URL de métadonnées lorsqu'elle est définie, puis renvoie le détail de chaque contrôle ainsi que le mapping des claims attendu. Il s'agit d'un outil de pré-vol à utiliser avant d'activer le SSO en production : si aucune configuration n'existe encore, l'appel échoue et vous oriente vers la mise à jour de la configuration.

Comportement notable : l'appel vers l'URL de métadonnées est soumis à un délai d'expiration de 5 secondes. Un échec ou un timeout de cet appel produit un contrôle en statut fail mais n'interrompt pas la requête. Le champ global ok vaut true uniquement si aucun contrôle n'est en fail (les statuts warn ne le font pas basculer à false).

Authentification

Requiert une clé API valide portant le scope workspace:manage. En son absence, l'API renvoie une erreur scope_missing (HTTP 403). L'espace de travail ciblé est déterminé par la clé API utilisée, il n'est pas passé dans le corps.

Corps de la requête

Cet endpoint n'attend aucun champ dans le corps de la requête. Toute la configuration testée est lue côté serveur à partir de l'espace de travail associé à la clé API. Vous pouvez envoyer un corps vide ou un objet JSON vide.

Champ	Type	Requis	Description
—	—	Non	Aucun paramètre de corps. La cible est déduite de la clé API.

Réponse

La réponse renvoie un objet avec trois champs. ok (booléen) indique le verdict global : il est true tant qu'aucun contrôle n'est en échec. checks est un tableau d'objets de diagnostic, chacun comprenant check (identifiant du contrôle), status (ok, warn ou fail) et detail (explication lisible). claim_mapping décrit la correspondance attendue entre les attributs Coffrify et les claims SAML de l'IdP.

Les contrôles possibles sont : metadata_url_reachable (l'URL de métadonnées répond, avec le code HTTP en détail), certificate_present (présence du certificat IdP inline ; warn si absent et que l'on s'appuie sur l'URL de métadonnées) et enabled_flag (le SSO est actif ; warn si la configuration existe mais est désactivée).

Champ	Type	Description
ok	booléen	true si aucun contrôle n'est en statut fail.
checks	tableau d'objets	Liste des contrôles : { check, status, detail }.
checks[].check	chaîne	Identifiant du contrôle (ex. metadata_url_reachable).
checks[].status	chaîne	ok, warn ou fail.
checks[].detail	chaîne	Détail lisible du contrôle.
claim_mapping	objet	Mapping des attributs (email, name, groups) vers les claims SAML.

Erreurs

Code	Quand	Résolution
validation_error (412)	Aucune configuration SSO n'existe pour l'espace (ni URL de métadonnées, ni certificat IdP).	Créez d'abord la configuration via update_sso_config, puis relancez le test.
scope_missing (403)	La clé API ne porte pas le scope workspace:manage.	Émettez une clé API avec le scope workspace:manage.
missing_api_key (401)	En-tête Authorization absent.	Ajoutez l'en-tête Authorization: Bearer cof_live_...
invalid_api_key (401)	Clé API invalide ou mal formée.	Vérifiez le préfixe et la validité de la clé.
rate_limited (429)	Quota de requêtes de l'espace dépassé.	Patientez puis réessayez en respectant l'en-tête Retry-After.
internal_error (500)	Erreur serveur inattendue.	Réessayez ; si le problème persiste, contactez le support avec le request_id.

Voir aussi

update_sso_config — créer ou mettre à jour la configuration SSO/SAML de l'espace.
get_sso_config — consulter la configuration SSO actuelle.
/v1/audit/logs — retrouver les événements de test et de modification SSO via le journal d'audit.