Approvisionner les comptes par SCIM

Le service d'approvisionnement d'un fournisseur d'identité — Microsoft Entra ID, Okta, OneLogin — tient les comptes d'une organisation à jour sans attendre leur première connexion, par le protocole SCIM 2.0 (RFC 7643 et RFC 7644). Docage en est le serveur : le fournisseur appelle, et une application écrite pour l'occasion peut faire de même, aux mêmes règles. L'approvisionnement complète l'authentification unique de l'organisation : il ne la remplace pas.

Adresse et jeton

L'adresse de base est https://staging-api.docage.com/scim/v2, la même pour toutes les organisations : c'est le jeton qui désigne la vôtre. Il se crée dans l'onglet Connexion de la fiche de l'organisation, sous Approvisionnement SCIM — voir Connecter Microsoft Entra —, et n'est montré qu'une fois. Chaque appel le porte dans l'en-tête Authorization: Bearer scim_…. Remplacer le jeton en crée un nouveau, qui coupe l'ancien ; Révoquer le jeton coupe l'approvisionnement.

Le serveur ne répond qu'à un jeton en service, quand le module de l'authentification unique est ouvert à l'organisation et que sa connexion n'est pas suspendue : sinon, 401. Il ne crée un compte qu'une fois la connexion reliée à son annuaire (consentement, ou premier essai réussi). Les corps et les réponses sont en application/scim+json.

Les ressources

Sous l'adresse de base :

Une liste se lit par startIndex et count. Un filtre se limite à une égalité, ou deux reliées par and : userName, externalId, emails.value et id pour un compte (userName eq "camille.martin@example.com"), displayName, externalId et id pour un groupe. Tout autre filtre est refusé en 400, avec invalidFilter : un filtre élargi en silence rendrait d'autres comptes que ceux demandés.

Les comptes

Un compte se lit et s'écrit par userName, externalId, name.givenName, name.familyName, displayName, emails, active et preferredLanguage (ou locale) ; tout autre attribut est ignoré. L'adresse est l'email principal, sinon celui de travail, sinon le premier, sinon userName s'il en a la forme.

• Créer : l'adresse doit être sur un domaine prouvé de l'authentification unique de l'organisation, sinon 400. Un compte de cette adresse qui existe déjà dans l'organisation est adopté : il est lié au fournisseur, puis aligné. Une adresse prise dans une autre organisation est refusée en 409. Un compte créé est facturé comme un utilisateur créé par un administrateur, n'a pas de mot de passe et n'est jamais administrateur par lui-même : il se connecte par le fournisseur.
• Désactiver : active à false bloque le compte et ferme ses sessions ; un DELETE fait de même, et ne supprime rien. Un compte désactivé par le fournisseur revit quand il remet active à true, jamais au déblocage de son organisation. Le dernier administrateur actif de l'organisation n'est jamais désactivé : le serveur refuse en 400, avec mutability.
• Les comptes de secours de l'organisation ne sont jamais modifiés par l'approvisionnement : le serveur refuse en 400, avec mutability.

Une erreur se rend dans le format de SCIM : status, detail et, quand il s'applique, scimType (invalidValue, uniqueness, mutability, invalidFilter, invalidSyntax).

Les groupes

Un groupe porte displayName, externalId et ses members, désignés par l'identifiant SCIM des comptes — celui que rend leur création. Quand l'organisation a allumé Les équipes viennent du fournisseur, chaque groupe relié à une équipe dans l'onglet Connexion en tient les membres. Supprimer un groupe le retire de l'organisation ; l'équipe reliée reste, sans ses membres venus du fournisseur.