Référence de l'API SCIM

URL de base

XID expose des API SCIM 2.0 limitées à l’organisation sous /scim/v2/organizations/{organization_id}. Les ressources utilisateur et groupe sont adressées avec l’ID d’organisation dans le chemin.

Configurez votre fournisseur d’identité avec l’URL de base https://xid.dev/scim/v2/organizations/{organization_id} et le jeton d’annuaire affiché une seule fois lorsque vous créez ou faites tourner l’annuaire.

curl https://xid.dev/scim/v2/organizations/{organization_id}/Users \
  -H 'Authorization: Bearer scim_xxx' \
  -H 'Content-Type: application/scim+json'

Authentification

Les appels SCIM utilisent un jeton bearer d’annuaire créé depuis l’API de gestion. XID stocke uniquement un hachage du jeton et renvoie le jeton en clair une seule fois lorsqu’il est créé ou renouvelé.

Points de terminaison

Ressource utilisateur

Les ressources utilisateur utilisent userName comme identifiant externe. Les valeurs e-mail, les champs de nom du profil, l’état actif et les champs d’extension entreprise sont conservés dans le profil brut SCIM.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "alice@example.com",
  "active": true,
  "name": { "givenName": "Alice", "familyName": "Lee" },
  "emails": [{ "value": "alice@example.com", "primary": true }]
}

Ressource groupe

Les ressources groupe utilisent displayName comme nom de groupe d’annuaire unique. Les membres référencent des ID utilisateur SCIM et sont synchronisés de façon idempotente.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    { "value": "dir_user_123", "display": "alice@example.com" }
  ]
}

Filtrage, tri et pagination

XID prend en charge la grammaire de filtre SCIM avec and, or, not et les opérateurs de comparaison (eq, ne, co, sw, ew, gt, ge, lt, le, pr). Les expressions non prises en charge renvoient invalidFilter. Les listes utilisent la pagination SCIM base 1 avec startIndex, count, totalResults, plus sortBy et sortOrder optionnels.

Opérations en masse

POST /scim/v2/organizations/{organization_id}/Bulk accepte une BulkRequest jusqu’à 100 opérations et 1 Mio de charge utile. Les réponses renvoient le statut HTTP par opération dans une BulkResponse même en cas d’échecs partiels.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "user1",
      "data": { "userName": "alice@example.com", "active": true }
    }
  ]
}

ETag and If-Match

Les réponses GET de ressource incluent ETag: W/"<meta.version>" depuis meta.version. PUT et PATCH exigent un en-tête If-Match correspondant à la version actuelle ; absence → 428, non-correspondance → 412.

Opérations PATCH

Les requêtes PATCH utilisent urn:ietf:params:scim:api:messages:2.0:PatchOp. XID prend en charge add, replace et remove pour les champs de profil modifiables et les appartenances aux groupes.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

Réponses d’erreur

Les erreurs SCIM renvoient application/scim+json avec le schéma SCIM Error, le statut HTTP, le détail et le champ facultatif scimType.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "userName already exists"
}

Capacités ServiceProviderConfig

• ServiceProviderConfig annonce sort.supported=true, bulk.supported=true et etag.supported=true.
• XID expose des endpoints entrants de fournisseur de services SCIM pour les IdP externes. Les clients de push SCIM vers les SaaS en aval disposent de preuves locales avec un SaaS factice, mais la prise en charge en production requiert toujours un L4 réel d’administration SaaS.

Comportement de désapprovisionnement

• La rotation du jeton d’annuaire garde l’ancien jeton valide pendant une courte période de grâce.
• active=false et DELETE /Users/{id} désapprovisionner l’utilisateur et révoquer les sessions actives.
• Les mises à jour d’appartenance aux groupes sont idempotentes. Les membres inconnus peuvent être résolus après l’arrivée de l’utilisateur depuis le fournisseur d’identité.