SSO et SAML

La connexion unique (SSO) via SAML 2.0 permet aux membres d'un compte entreprise de se connecter à Coffrify avec les identifiants gérés par votre fournisseur d'identité (Okta, Microsoft Entra ID, Google Workspace, etc.), sans mot de passe propre à Coffrify. Vos équipes informatiques gardent la main sur les accès depuis un point central, et les arrivées comme les départs se répercutent automatiquement. Cette page explique à quoi sert le SSO, comment le configurer côté API, et comment surveiller les connexions grâce aux évènements webhook saml.login_succeeded et saml.login_failed. La fonctionnalité est réservée aux comptes Entreprise.

À quoi sert le SSO

Avec le SSO activé, l'authentification des membres est déléguée à votre fournisseur d'identité. Concrètement, vous y gagnez une authentification centralisée (vos politiques de mot de passe et de MFA s'appliquent), un contrôle des accès unifié (couper l'accès chez le fournisseur coupe l'accès à Coffrify), et une piste d'audit des connexions exploitable via les webhooks. Le SSO se combine naturellement avec l'approvisionnement automatique des comptes (SCIM) pour créer et désactiver les membres sans intervention manuelle.

Scopes requis

Les appels d'administration du SSO sont protégés par deux scopes. Attribuez-les à une clé restreinte dédiée à l'administration plutôt qu'à une clé applicative.

Principe de configuration

La mise en place repose sur un échange de métadonnées entre Coffrify (le fournisseur de service, ou SP) et votre fournisseur d'identité (l'IdP). Le déroulé est le suivant : vous récupérez les métadonnées du SP Coffrify, vous créez une application SAML chez votre fournisseur d'identité en y collant ces métadonnées, puis vous renvoyez à Coffrify l'URL de métadonnées (ou le certificat) de votre IdP et vous activez la connexion. Un test de bout en bout valide l'ensemble avant la mise en production.

Étape 1 : récupérer les métadonnées du fournisseur de service

Coffrify expose ses métadonnées SP au format XML, à importer dans votre fournisseur d'identité. La réponse contient aussi les valeurs clés à saisir manuellement si votre IdP ne lit pas le XML : l'identifiant d'entité (entity_id), l'URL du service de consommation d'assertion (acs_url, parfois appelée URL de callback ou ACS URL) et l'URL de déconnexion unique (slo_url).

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const meta = await coffrify.sso.getMetadata();
console.log(meta.entity_id);
console.log(meta.acs_url);
console.log(meta.slo_url);
// meta.xml : à importer tel quel dans Okta / Entra ID / Google
 

Étape 2 : créer l'application chez votre fournisseur d'identité

Dans la console de votre fournisseur d'identité, créez une nouvelle application SAML 2.0 et renseignez les valeurs obtenues à l'étape précédente.

• Audience / Entity ID : la valeur entity_id renvoyée par Coffrify.
• Single Sign-On URL / ACS URL : la valeur acs_url.
• Single Logout URL (optionnel) : la valeur slo_url.
• Attributs (claims) : transmettez au minimum l'adresse e-mail de l'utilisateur ; ajoutez nom et prénom si votre IdP les fournit.

Étape 3 : déclarer l'IdP et activer le SSO

Renvoyez à Coffrify la configuration de votre fournisseur d'identité avec PATCH /v1/sso/config. Le plus simple est de fournir une URL de métadonnées (idp_metadata_url) : Coffrify y lit le certificat de signature et l'endpoint de connexion. Vous pouvez aussi coller directement le certificat via idp_certificate. Passez enabled à true pour activer la connexion une fois le test concluant.

const config = await coffrify.sso.update({
  idp_metadata_url: 'https://votre-idp.example.com/app/metadata',
  enabled: true,
});
 
console.log(config.configured); // true une fois l'IdP reconnu
console.log(config.enabled);    // true = connexion SSO active
 

Vous pouvez relire la configuration à tout moment avec GET /v1/sso/config. La réponse indique si le SSO est activé (enabled) et correctement configuré (configured), l'URL de métadonnées de l'IdP (idp_metadata_url), un résumé non sensible du certificat (idp_certificate_summary), la date de dernière modification (updated_at), ainsi que l'acs_url et l'entity_id du SP. Pour désactiver temporairement le SSO sans perdre la configuration, faites un PATCH avec enabled: false.

Étape 4 : tester la connexion

Avant de basculer vos équipes, lancez un test de bout en bout. Il vérifie la lecture des métadonnées, l'aller-retour ACS et la correspondance des attributs (claim mapping), et renvoie une liste de contrôles avec un statut ok, warn ou fail pour chacun.

$ cof sso test
ok: true
  metadata        ok    Métadonnées IdP lues
  acs_roundtrip   ok    Assertion reçue et validée
  claim_mapping   warn  Attribut « prénom » absent
 

Surveiller les connexions par webhook

Deux évènements webhook permettent de surveiller l'activité SSO en temps réel. Abonnez-vous-y pour alimenter votre SIEM, déclencher des alertes ou tenir un journal de connexions parallèle.

Le corps des évènements saml.* contient l'identifiant du membre concerné (user_id), son adresse e-mail (email), l'adresse IP de la tentative lorsqu'elle est connue (ip_address), et pour les échecs un motif lisible (reason). Une recrudescence d'évènements saml.login_failed peut signaler une configuration cassée chez l'IdP ou une tentative d'accès anormale ; c'est un bon candidat pour une alerte.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
export async function handler(req, res) {
  const event = coffrify.webhooks.constructEvent(
    req.rawBody,
    req.headers,
    process.env.COFFRIFY_WEBHOOK_SECRET,
  );
 
  switch (event.type) {
    case 'saml.login_succeeded':
      console.log('Connexion SSO', event.data.email, event.data.ip_address);
      break;
    case 'saml.login_failed':
      console.warn('Échec SSO', event.data.email, event.data.reason);
      // alerter au-delà d'un seuil d'échecs
      break;
  }
 
  res.sendStatus(200);
}