Provisionnement des utilisateurs : guide d’intégration de l’API

Le service de provisionnement des utilisateurs DocuWare est une API REST conforme à SCIM 2.0. Elle permet le provisionnement automatique des utilisateurs et la gestion des groupes depuis des fournisseurs d'identité externes (IdP) tels qu'Azure Entra ID, Okta, Ping Identity ou un annuaire sur site (à l'aide de l'outil User Provisioning On-premise directory connector) vers les systèmes DocuWare.

URL de base et endpoints

Structure de l'URL de base

DocuWare Cloud

https://{your-organization}.docuware.cloud/DocuWare/Services/UserProvisioningService/{externalIdp}/scim

DocuWare sur site

http(s)://{your-server-address}/DocuWare/Services/UserProvisioningService/{externalIdp}/scim

Où {externalIdp} peut être :

• azure – pour Azure Entra ID

• okta – pour Okta

• ping – pour Ping Identity

• onpremise – pour les annuaires sur site

• generic-{identifier} – pour les fournisseurs d'identité génériques

Endpoints disponibles

Authentification

Authentification JWT Bearer

Tous les endpoints (à l'exception du health check) nécessitent une authentification par jeton JWT Bearer :

Authorization: Bearer {jwt-token}

Type de contenu

Toutes les requêtes doivent utiliser le type de contenu SCIM :

Content-Type: application/scim+json

Gestion des utilisateurs

Schéma utilisateur (Core2EnterpriseUser)

Récupérer des utilisateurs (GET)

L'endpoint GET Users prend en charge plusieurs variantes pour récupérer les données utilisateur, avec filtrage et pagination optionnels. Par défaut, il renvoie uniquement les utilisateurs possédant un ID externe (utilisateurs issus de fournisseurs d'identité externes).

1. Récupérer tous les utilisateurs externes (par défaut)

GET /{externalIdp}/scim/Users
Authorization: Bearer {token}

Renvoie tous les utilisateurs possédant un externalId (utilisateurs issus de fournisseurs d'identité externes).

Réponse :

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],

  "totalResults": 2,

  "itemsPerPage": 2,

  "startIndex": 1,

  "resources": [

    {

      "userName": "john.doe",

      "active": true,

      "emails": [

        {

          "value": "john.doe@example.com",

          "primary": true

        }

      ],

      "name": {

        "givenName": "John",

        "familyName": "Doe"

      },

      "id": "external-user-id-123",

      "meta": {

        "resourceType": "User"

      },

      "schemas": [

        "urn:ietf:params:scim:schemas:core:2.0:User",

        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

      ],

    },

    {

      "userName": "jane.smith",

      "active": true,

      "emails": [

        {

          "value": "jane.smith@example.com",

          "primary": true

        }

      ],

      "name": {

        "givenName": "Jane",

        "familyName": "Smith"

      },

      "id": "external-user-id-456",

      "meta": {

        "resourceType": "User"

      },

      "schemas": [

        "urn:ietf:params:scim:schemas:core:2.0:User",

        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

      ]

    }

  ]

}

2. Récupérer tous les utilisateurs DocuWare

GET /{externalIdp}/scim/Users?allDocuWareUsers=true
Authorization: Bearer {token}

Renvoie tous les utilisateurs du système DocuWare, y compris les utilisateurs externes et les utilisateurs internes DocuWare.

Remarque : les utilisateurs internes n'ont pas d'id

Les utilisateurs internes ne possèdent pas de champ id dans la réponse, car ils ne sont pas externes et n'ont pas d'attribut externalId défini (c'est cet attribut qui est renvoyé en tant qu'id).

Réponse

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],

  "totalResults": 2,

  "itemsPerPage": 2,

  "startIndex": 1,

  "resources": [

    {

      "userName": "john.doe",

      "active": true,

      "emails": [

        {

          "value": "john.doe@example.com",

          "primary": true

        }

      ],

      "name": {

        "givenName": "John",

        "familyName": "Doe"

      },

      "id": "external-user-id-123",

      "meta": {

        "resourceType": "User"

      },

      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

    },

    {

      "userName": "jane.smith",

      "active": true,

      "emails": [

        {

          "value": "jane.smith@example.com",

          "primary": true

        }

      ],

      "name": {

        "givenName": "Jane",

        "familyName": "Smith"

      },

      "meta": {

        "resourceType": "User"

      },

      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"]

    }

  ]

}

3. Récupérer un utilisateur spécifique par son ID

GET /{externalIdp}/scim/Users/{externalId}

Authorization: Bearer {token}

Renvoie un utilisateur spécifique identifié par son ID externe.

Réponse :

{

  "userName": "john.doe",

  "active": true,

  "emails": [

    {

      "value": "john.doe@example.com",

      "primary": true

    }

  ],

  "name": {

    "givenName": "John",

    "familyName": "Doe"

  },

  "id": "external-user-id-123",

  "meta": {

    "resourceType": "User"

  },

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

}

4. Interroger les utilisateurs avec filtrage

Filtrer par nom d'utilisateur (parmi les utilisateurs externes) :

GET /{externalIdp}/scim/Users?filter=userName eq "john.doe"

Authorization: Bearer {token}

Filtrer par nom d'utilisateur parmi tous les utilisateurs DocuWare :

GET /{externalIdp}/scim/Users?allDocuWareUsers=true&filter=userName eq "john.doe"

Authorization: Bearer {token}

Filtrer par ID externe :

GET /{externalIdp}/scim/Users?filter=externalId eq "external-user-id-123"

Authorization: Bearer {token}

Récupérer des utilisateurs avec pagination :

GET /{externalIdp}/scim/Users?startIndex=2&count=5

Authorization: Bearer {token}

GET /{externalIdp}/scim/Users?allDocuWareUsers=true&startIndex=2&count=5

Authorization: Bearer {token}

Paramètres de requête pris en charge

Pagination :

• startIndex – index du premier résultat, basé sur 1 (par défaut : 1, minimum : 1)

• count – nombre de résultats par page (par défaut : tous les résultats si non spécifié, minimum : 0)

Filtrage :

• filter – expression de filtre SCIM (prend en charge uniquement userName eq "value" & externalId eq "value") (insensible à la casse)

Format de la réponse

Toutes les requêtes GET /Users renvoient une ListResponse SCIM avec la structure suivante :

Propriétés :

• schemas – tableau contenant "urn:ietf:params:scim:api:messages:2.0:ListResponse"

• totalResults – nombre total d'utilisateurs correspondants

• itemsPerPage – nombre d'utilisateurs renvoyés dans la réponse courante

• startIndex – index de début de la page courante (basé sur 1)

• Resources – tableau d'objets utilisateur

Réponses d'erreur

400 Bad Request – filtre non valide :

{

  "ScimType": "invalidFilter",

  "Detail": "Unsupported filter attribute: FirstName",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

{

  "ScimType": "invalidFilter",

  "Detail": "Unsupported comparison operator: 'ne'",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Toutes les requêtes GET /Users/{externalId} renvoient un objet User avec la structure suivante :

Propriétés de l'objet User :

• id – ID externe de l'utilisateur

• userName – nom de connexion de l'utilisateur (sans le domaine si e-mail, pour les IdP non génériques)

• active – statut actif de l'utilisateur (booléen)

• emails – tableau d'objets e-mail avec les propriétés value et primary

• name – objet contenant les propriétés givenName et familyName

• meta – objet de métadonnées avec resourceType: "User"

• schemas – tableau d'identifiants de schémas SCIM

Réponses d'erreur

404 Not Found – utilisateur introuvable :

{

  "Detail": "User with External ID 'external-user-id-404' was not found.",

  "Status": 404,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Exemples

Récupérer les 5 premiers utilisateurs externes :

GET /{externalIdp}/scim/Users?startIndex=1&count=5

Récupérer les utilisateurs externes à partir d'une position donnée :

GET /{externalIdp}/scim/Users?startIndex=10&count=20

Rechercher un utilisateur par nom d'utilisateur :

GET /{externalIdp}/scim/Users?filter=userName eq "john.doe"

Rechercher un utilisateur par nom d'utilisateur parmi tous les utilisateurs DocuWare :

GET /{externalIdp}/scim/Users?allDocuWareUsers=true&filter=userName eq "jane.smith"

Rechercher un utilisateur par externalId :

GET /{externalIdp}/scim/Users?filter=externalId eq "external-user-id-123"

Récupérer tous les utilisateurs DocuWare avec pagination :

GET /{externalIdp}/scim/Users?allDocuWareUsers=true&startIndex=1&count=50

Créer un utilisateur (POST)

Fonctionnement de la création d'utilisateur

Le système met en œuvre une logique intelligente de création/mise à jour des utilisateurs qui suit les étapes suivantes :

1. Recherche de l'utilisateur par ID externe : le système tente d'abord de trouver un utilisateur existant à l'aide de l'externalId fourni. Si un utilisateur est trouvé, il s'agit d'une correspondance exacte et l'utilisateur existant est mis à jour avec les attributs de la requête.

2. Recherche alternative par nom d'utilisateur : si aucun utilisateur n'est trouvé par ID externe, le système recherche par nom d'utilisateur extrait du champ userName. Si un utilisateur est trouvé et que l'e-mail entrant correspond à l'e-mail existant, il s'agit d'une correspondance exacte et l'utilisateur est mis à jour. En revanche, si les e-mails ne correspondent pas, la création échoue car un utilisateur avec le userName fourni existe déjà (erreur 409 Conflict).

Logique de création ou de mise à jour :

• Nouvel utilisateur : si aucun utilisateur existant n'est trouvé par externalID ou userName, un nouvel utilisateur est créé.

• Mise à jour : si un utilisateur existant est trouvé et associé par externalId ou par userName + e-mail, ses informations sont mises à jour.

• Validation de l'e-mail : lors de la recherche par userName, le système vérifie que l'e-mail de l'utilisateur existant correspond à l'e-mail fourni (insensible à la casse). Si les e-mails ne correspondent pas, une exception est levée pour éviter les conflits.

Remarques sur le service de résolution d'adresse e-mail

Le service détermine l'adresse e-mail de l'utilisateur selon l'ordre de priorité suivant :

1. E-mail principal : utilise l'e-mail marqué comme primary: true dans le tableau emails.

2. Premier e-mail valide : si aucun e-mail principal n'existe, sélectionne le premier e-mail valide du tableau emails.

3. Validation : si aucune des adresses ci-dessus n'est une adresse e-mail valide, la requête échoue avec une erreur 400 Bad Request.

Requête

POST /{externalIdp}/scim/Users

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

  "userName": "john.doe@example.com",

  "externalId": "external-user-id-123",

  "active": true,

  "name": {

    "givenName": "John",

    "familyName": "Doe"

  },

  "emails": [

    {

      "value": "john.doe@example.com",

      "primary": true

    }

  ]

}

Champs obligatoires et optionnels

Champs obligatoires :

• schemas – identifiants de schémas SCIM (doit inclure les schémas Core et Enterprise User)

• userName – nom de connexion de l'utilisateur (doit être unique)

• externalId – ID utilisateur du fournisseur d'identité externe (doit être unique)

• active – statut actif de l'utilisateur

• emails – tableau d'adresses e-mail

Champs optionnels :

• name – objet de nom d'affichage de l'utilisateur

  • name.givenName – prénom

  • name.familyName – nom de famille

Règles de validation des champs :

• UserName : obligatoire, sensible à la casse, ne doit pas être vide ou constitué uniquement d'espaces

• ExternalId : obligatoire, sensible à la casse, ne doit pas être vide ou constitué uniquement d'espaces

• Emails : au moins un e-mail valide doit pouvoir être résolu (en cas d'adresses multiples, les règles de résolution d'adresse e-mail s'appliquent)

• Active : valeur booléenne

• Champs name : chaînes optionnelles utilisées à des fins d'affichage

Réponse

Succès (200 OK) :

{

  "userName": "john.doe",

  "active": true,

  "emails": [

    {

      "value": "john.doe@example.com",

      "primary": true

    }

  ],

  "name": {

    "givenName": "John",

    "familyName": "Doe"

  },

  "id": "external-user-id-123",

  "meta": {

    "resourceType": "User"

  },

  "schemas": [

      "urn:ietf:params:scim:schemas:core:2.0:User",

      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

  ]

}

Réponses d'erreur

400 Bad Request – champs obligatoires manquants :

{

  "ScimType": "invalidValue",

  "Detail": "Validation failed: UserName: is required",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

409 Conflict – l'utilisateur existe déjà :

{

  "ScimType": "uniqueness",

  "Detail": "User with username 'john.doe' already exists with different email address!",

  "Status": 409,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Gestion des groupes

Schéma de groupe (Core2Group)

Fonctionnement de la création de groupe

Le système met en œuvre une logique intelligente de création/mise à jour des groupes qui suit les étapes suivantes :

1. Recherche du groupe par DisplayName :
   le système tente d'abord de trouver un groupe existant à l'aide du displayName fourni. S'il en trouve un, il s'agit d'une mise à jour de groupe. Sinon, un nouveau groupe est créé.

2. Logique de création ou de mise à jour :

   • Nouveau groupe : si aucun groupe existant n'est trouvé par displayName, un nouveau groupe est créé avec les membres fournis.

   • Mise à jour du groupe : si un groupe existant est trouvé, les informations du groupe sont mises à jour et les nouveaux membres sont ajoutés à la liste existante (les membres existants ne sont pas remplacés).

   • Ajout de membres : les nouveaux membres sont ajoutés aux groupes existants sans supprimer les membres actuels.

   • Prévention des doublons : le système empêche l'ajout de membres en double dans les groupes.

Remarques importantes sur la création de groupes :

• Unicité du nom d'affichage : les groupes sont identifiés par leur displayName.

• Résolution des membres : toutes les références de membres (champ value) doivent être des valeurs externalId valides d'utilisateurs existants.

• Appartenance incrémentielle : les opérations POST sur des groupes existants ajoutent des membres de manière incrémentielle au lieu de remplacer la liste complète.

• Validation des membres : le système ajoute uniquement les membres existants. Si un membre avec le value (externalId) fourni n'existe pas, il est simplement ignoré sans erreur.

• Périmètre du fournisseur d'identité externe : vous ne pouvez gérer que la partie du groupe composée d'utilisateurs issus de l'externalIdp courant. Les utilisateurs d'autres fournisseurs d'identité externes ou les utilisateurs internes DocuWare ne sont pas affectés par ces opérations.

• Réponse : la réponse inclut uniquement les membres du groupe qui sont des utilisateurs externes provisionnés par l'externalIdp spécifié (azure, okta, ping, onpremise ou generic). Les utilisateurs internes ou les utilisateurs créés par d'autres fournisseurs d'identité externes sont exclus de la réponse.

Format de référence des membres :

• Les membres sont référencés par leur externalId (et non par l'ID utilisateur interne DocuWare).

• Chaque objet membre doit contenir un champ value avec l'ID externe de l'utilisateur.

• Le champ optionnel display (correspondant au userName de l'utilisateur) peut être fourni mais n'est pas requis pour l'affectation aux groupes.

Créer un groupe (POST)

POST /{externalIdp}/scim/Groups

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

  "displayName": "Engineering Team",

  "members": [

    {

      "value": "external-user-id-123"

    },

    {

      "value": "external-user-id-456"

    }

  ]

}

Réponse

{

  "displayName": "Engineering Team",

  "members": [

    {

      "value": "external-user-id-123",

      "display": "john.doe"

    },

    {

      "value": "external-user-id-456",

      "display": "jane.smith"

    }

  ],

  "id": "12345678-1234-1234-1234-123456789012",

  "meta": {

    "resourceType": "Group"

  },

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"]

}

Création d'un groupe vide :

POST /{externalIdp}/scim/Groups

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

  "displayName": "Future Project Team",

  "members": []

}

Champs obligatoires :

• schemas – identifiants de schémas SCIM (doit inclure "urn:ietf:params:scim:schemas:core:2.0:Group")

• displayName – nom d'affichage du groupe (utilisé pour l'identification)

• members – tableau d'objets membres (peut être vide lors de la création)

  • members[].value – ID externe de l'utilisateur (obligatoire si des membres sont spécifiés)

Réponses d'erreur

400 Bad Request – champs obligatoires manquants :

{

  "ScimType": "invalidValue",

  "Detail": "Validation failed: DisplayName: is required",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

{

  "ScimType": "invalidValue",

  "Detail": "Validation failed: Members: The Members field is required.",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

{

  "ScimType": "invalidValue",

  "Detail": "Validation failed: Members[0].Value: Member Value is required.",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Récupérer des groupes (GET)

L'endpoint GET Groups prend en charge plusieurs variantes pour récupérer les données de groupe, avec filtrage et pagination optionnels. Les groupes incluent les membres qui sont des utilisateurs externes du fournisseur d'identité externe spécifié.

1. Récupérer tous les groupes (par défaut)

GET /{externalIdp}/scim/Groups
Authorization: Bearer {token}

Renvoie tous les groupes existants dans DocuWare, sans inclure les membres. Ces derniers peuvent être récupérés via la requête GET : /Groups/{groupId}

Réponse :

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],

  "totalResults": 2,

  "itemsPerPage": 2,

  "startIndex": 1,

  "resources": [

    {

      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

      "id": "group-id-123",

      "displayName": "Engineering Team",

      "meta": {

        "resourceType": "Group"

      }

    },

    {

      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

      "id": "group-id-456",

      "displayName": "Marketing Team",

      "meta": {

        "resourceType": "Group",

      }

    }

  ]

}

2. Récupérer un groupe spécifique par son ID

GET /{externalIdp}/scim/Groups/{groupId}

Authorization: Bearer {token}

Récupère les détails d'un groupe spécifique à l'aide de son ID. L'attribut members inclut uniquement les utilisateurs externes provisionnés par le fournisseur d'identité spécifié.

Réponse :

{

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

  "displayName": "Engineering Team",

  "members": [

    {

      "value": "external-user-id-123",

      "display": "john.doe",

    },

    {

      "value": "external-user-id-456",

      "display": "jane.smith",

    }

  ],

  "id": "group-external-id-123",

  "meta": {

    "resourceType": "Group"

  }

}

3. Interroger les groupes avec filtrage

Filtrer par nom d'affichage :

GET /{externalIdp}/scim/Groups?filter=displayName eq "Engineering Team"

Authorization: Bearer {token}

Récupérer des groupes avec pagination :

GET /{externalIdp}/scim/Groups?startIndex=1&count=10

Authorization: Bearer {token}

GET /{externalIdp}/scim/Groups?startIndex=2&count=5

Authorization: Bearer {token}

Paramètres de requête pris en charge

Filtrage :

• filter – expression de filtre SCIM (prend en charge uniquement displayName eq "value") (insensible à la casse, correspondance exacte)

Pagination :

• startIndex – index du premier résultat, basé sur 1 (par défaut : 1, minimum : 1)

• count – nombre de résultats par page (par défaut : tous les résultats si non spécifié, minimum : 0)

Format de la réponse

Toutes les requêtes GET /Groups renvoient une ListResponse SCIM avec la structure suivante :

Propriétés de la ListResponse :

• schemas – tableau contenant "urn:ietf:params:scim:api:messages:2.0:ListResponse"

• totalResults – nombre total de groupes correspondants

• itemsPerPage – nombre de groupes renvoyés dans la réponse courante

• startIndex – index de début de la page courante (basé sur 1)

• resources – tableau d'objets de groupe (l'attribut members n'est disponible que lors de la récupération par ID de groupe)

Propriétés de l'objet Group :

• id – ID externe du groupe

• displayName – nom d'affichage du groupe

• members – tableau d'objets membres (uniquement les utilisateurs externes de l'externalIdp spécifié)

  • value – ID externe de l'utilisateur membre

  • display – nom d'utilisateur du membre

• meta – type de ressource de l'objet

• schemas – tableau contenant les identifiants de schémas SCIM

Remarques sur les réponses de groupe

Filtrage des membres :

• Seuls les membres qui sont des utilisateurs externes gérés par l'{externalIdp} spécifié sont inclus dans les réponses.

• Les utilisateurs internes DocuWare et les utilisateurs d'autres fournisseurs d'identité externes sont exclus.

• Les groupes vides (sans membres correspondants) peuvent toujours apparaître dans les résultats s'ils existent.

Identification des groupes :

• Les groupes sont identifiés par leur ID pour les opérations GET.

• Le displayName est utilisé pour le filtrage et la recherche de groupe lors de la création/mise à jour.

Réponses d'erreur

400 Bad Request – filtre non valide :

Filtrage par attribut incorrect :

{

  "ScimType": "invalidFilter",

  "Detail": "Unsupported filter attribute: id",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Filtrage avec une expression non valide (seule la syntaxe filter=displayName eq "groupName" est valide) :

{

  "ScimType": "invalidFilter",

  "Detail": "Invalid filter expression: 'displasyname asd \"engineering team\"'",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Filtrage avec un opérateur de comparaison non pris en charge :

{

  "ScimType": "invalidFilter",

  "Detail": "Unsupported comparison operator: 'ne'",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

404 Not Found – groupe introuvable :

{

  "Detail": "Group with identifier 'group-id-404' was not found.",

  "Status": 404,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Mettre à jour l'appartenance à un groupe (PATCH)

L'opération PATCH permet des mises à jour partielles des attributs de groupe via les opérations de correctif SCIM 2.0. Le service prend en charge les opérations add, remove et replace (uniquement pour le displayName du groupe).

Structure PATCH de base

PATCH /{externalIdp}/scim/Groups/{id}

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

  "Operations": [

    {

      "op": "operation_type",

      "path": "attribute_path",

      "value": "new_value_or_array"

    }

  ]

}

Opérations prises en charge

Ajouter des membres (add) : ajoute de nouveaux membres au groupe sans supprimer les membres existants.

vPATCH /{externalIdp}/scim/Groups/{id}

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

  "Operations": [

    {

      "op": "add",

      "path": "members",

      "value": [

        {

          "value": "external-user-id-789"

        },

        {

          "value": "external-user-id-101"

        }

      ]

    }

  ]

}

Supprimer des membres spécifiques (remove) : supprime les membres spécifiés du groupe.

PATCH /{externalIdp}/scim/Groups/{id}

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

  "Operations": [

    {

      "op": "remove",

      "path": "members",

      "value": [

        {

          "value": "external-user-id-123"

        },

        {

          "value": "external-user-id-456"

        }

      ]

    }

  ]

}

Supprimer tous les membres (remove) : supprime du groupe tous les membres qui sont des utilisateurs créés par l'externalIdp fourni (vide le groupe).

PATCH /{externalIdp}/scim/Groups/{id}

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

  "Operations": [

    {

      "op": "remove",

      "path": "members"

    }

  ]

}

Lorsqu'aucune valeur value n'est fournie avec l'opération remove, tous les membres externes (issus de l'externalIdp fourni) sont supprimés.

1. Remplacer le nom d'affichage du groupe (replace) Met à jour le nom d'affichage du groupe.

PATCH /{externalIdp}/scim/Groups/{id}

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

  "Operations": [

    {

      "op": "replace",

      "path": "displayName",

      "value": "Updated Team Name"

    }

  ]

}

Chemins d'attributs pris en charge

Opérations multiples dans une seule requête

Vous pouvez combiner plusieurs opérations dans une seule requête PATCH :

PATCH /{externalIdp}/scim/Groups/{id}

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

  "Operations": [

    {

      "op": "replace",

      "path": "displayName",

      "value": "DevOps Engineering Team"

    },

    {

      "op": "add",

      "path": "members",

      "value": [

        {

          "value": "external-user-id-new1"

        }

      ]

    },

    {

      "op": "remove",

      "path": "members",

      "value": [

        {

          "value": "external-user-id-old1"

        }

      ]

    }

  ]

}

Format de l'objet membre

Lorsque vous spécifiez des membres dans les opérations, utilisez le format suivant :

Champs obligatoires :

• value – ID externe de l'utilisateur à ajouter/supprimer

Exemple d'objet membre :

{
  "value": "external-user-id-123"
}

Détails du comportement des opérations

Opération Add :

• Ajoute les membres spécifiés au groupe.

• Ignore les membres déjà présents dans le groupe (pas de doublons).

• Les ID externes d'utilisateurs inexistants sont silencieusement ignorés.

• N'affecte pas les membres existants.

Opération Remove :

• Avec value : supprime uniquement les membres spécifiés (s'ils sont des utilisateurs créés par l'externalIdp fourni).

• Sans value : supprime tous les membres (utilisateurs créés par l'externalIdp fourni) du groupe.

• Ignore les ID externes qui ne sont pas des membres actuels.

• N'affecte pas les membres non spécifiés.

Opération Replace :

• Pour displayName : met à jour le nom du groupe.

Réponses

• Réponse PATCH réussie (204 No Content)

• 400 Bad Request – opération non valide

• 400 Bad Request – chemin non valide

• 400 Bad Request – format de membre non valide

• 404 Not Found – groupe introuvable

• 409 Conflict – le nom du groupe existe déjà

Remarques importantes sur les opérations PATCH

Traitement des opérations :

• Les opérations sont traitées séquentiellement dans l'ordre d'apparition.

Validation des membres :

• Les ID externes des utilisateurs doivent référencer des utilisateurs existants.

• Les ID externes non valides sont silencieusement ignorés (aucune erreur levée).

• Seuls les utilisateurs externes du même fournisseur d'identité (externalIdp) sont gérés.

État du groupe :

• La réponse inclut uniquement les utilisateurs externes de l'{externalIdp} spécifié.

• Les utilisateurs internes DocuWare et les utilisateurs d'autres fournisseurs d'identité sont exclus des réponses.

• Les groupes vides restent valides et sont inclus dans les réponses.

Mettre à jour un groupe (PUT) – remplacement complet du groupe

L'opération PUT effectue un remplacement complet de la partie du groupe gérée par l'externalIdp. Contrairement à PATCH, qui met à jour uniquement les champs spécifiés, PUT remplace l'intégralité de l'objet groupe avec les données fournies.

Requête PUT de base

PUT /{externalIdp}/scim/Groups/{groupId}

Content-Type: application/scim+json

Authorization: Bearer {token}

{

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

  "displayName": "Updated Engineering Team",

  "members": [

    {

      "value": "external-user-id-123"

    },

    {

      "value": "external-user-id-456"

    }

  ]

}

Paramètres

• {externalIdp} – identifiant du fournisseur d'identité externe (azure, okta, ping, etc.)

• {groupId} – ID du groupe à mettre à jour

Champs obligatoires pour PUT

Tous les champs obligatoires pour la création de groupe doivent être fournis :

• schemas – identifiants de schémas SCIM (doit inclure "urn:ietf:params:scim:schemas:core:2.0:Group")

• displayName – nom d'affichage du groupe

• members – tableau d'objets membres (peut être vide)

Exemple PUT complet

PUT /azure/scim/Groups/group-id-123

Content-Type: application/scim+json

Authorization: Bearer {jwt-token}

{

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

  "displayName": "DevOps Engineering Team",

  "members": [

    {

      "value": "external-user-id-789"

    },

    {

      "value": "external-user-id-101"

    }

  ]

}

Réponse

Succès (200 OK) :

{

  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

  "id": "group-id-123",

  "displayName": "DevOps Engineering Team",

  "members": [

    {

      "value": "external-user-id-789",

      "display": "john.doe",

    },

    {

      "value": "external-user-id-101",

      "display": "jane.smith",

    }

  ],

  "meta": {

    "resourceType": "Group"

  }

}

Remarques importantes sur le comportement PUT

1. Remplacement complet des membres : PUT remplace l'intégralité de la liste des membres gérée par l'externalIdp courant. Tout membre non inclus dans la requête sera supprimé du groupe.

2. Mise à jour du nom d'affichage : le nom d'affichage du groupe peut être modifié via les opérations PUT.

3. Validation des membres : tous les ID externes de membres spécifiés doivent référencer des utilisateurs existants. Les ID externes non valides sont silencieusement ignorés.

4. Périmètre du fournisseur d'identité externe : seuls les membres qui sont des utilisateurs externes de l'{externalIdp} spécifié sont gérés par cette opération. Les utilisateurs internes DocuWare et les utilisateurs d'autres fournisseurs d'identité ne sont pas affectés.

5. Identification du groupe : le groupe est identifié par le paramètre {groupId} dans l'URL.

Réponses d'erreur

400 Bad Request – champs obligatoires manquants :

{

  "ScimType": "invalidValue",

  "Detail": "Validation failed: DisplayName: is required",

  "Status": 400,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

404 Not Found – groupe introuvable :

{

  "Detail": "Group with identifier 'group-id-404' was not found.",

  "Status": 404,

  "Schemas": [

      "urn:ietf:params:scim:api:messages:2.0:Error"

  ]

}

Règles de validation pour PUT

Toutes les règles de validation des opérations POST s'appliquent aux opérations PUT :

• DisplayName : obligatoire, sensible à la casse, ne doit pas être vide ou constitué uniquement d'espaces

• Members : tableau optionnel ; chaque membre doit avoir un champ value valide contenant l'ID externe d'un utilisateur existant

• ID externes des membres : doivent référencer des utilisateurs existants du même fournisseur d'identité externe

• Schemas : doit inclure le schéma Core Group

Supprimer un groupe (DELETE) – non pris en charge

L'opération DELETE pour les groupes n'est pas prise en charge par le service de provisionnement des utilisateurs DocuWare v3. Toute tentative de suppression d'un groupe entraîne une réponse d'erreur.

Codes de statut HTTP

Format des réponses d'erreur

{

  "ScimType": "invalidValue",

  "Detail": "Validation failed.",

  "Status": 400,

  "Schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"]

}

Exigences de configuration

Configuration du fournisseur d'identité

1. Configurez votre IdP pour qu'il pointe vers l'URL tenant appropriée.

2. Configurez l'authentification OAuth 2.0/OIDC avec des jetons JWT.

3. Configurez les scopes corrects : docuware.userProvisioning

4. Assurez-vous que l'utilisateur effectuant les opérations API dispose des autorisations suffisantes.

Fournisseurs d'identité pris en charge

• Azure Entra ID (Azure AD) : utilisez azure comme externalIdp

• Okta : utilisez okta comme externalIdp

• Ping Identity : utilisez ping comme externalIdp

• Sur site : utilisez onpremise comme externalIdp

• IdP générique

Informations sur les schémas

Récupérer les schémas disponibles

GET /{externalIdp}/scim/Schemas
Authorization: Bearer {token}

Récupérer les types de ressources

GET /{externalIdp}/scim/ResourceTypes  
Authorization: Bearer {token}

Health Check

Disponibilité du service

GET /AvailabilityCheck

Cet endpoint ne nécessite aucune authentification et renvoie 200 OK si le service est opérationnel.

Exemples de workflows d'intégration

Workflow complet de provisionnement d'un utilisateur

1. Créer un utilisateur : POST vers /Users avec les informations de l'utilisateur

2. Vérifier la création : GET /Users/{id} pour confirmer

3. Mettre à jour l'utilisateur : PATCH /Users/{id} pour les modifications

4. Ajouter à des groupes : PATCH /Groups/{groupId} pour ajouter l'utilisateur

5. Désactiver : PATCH /Users/{id} avec active: false

Workflow de gestion des groupes

1. Créer un groupe : POST vers /Groups avec les informations du groupe

2. Ajouter des membres : PATCH /Groups/{id} avec des opérations add

3. Mettre à jour le nom : PATCH /Groups/{id} avec modification du displayName

4. Supprimer des membres : PATCH /Groups/{id} avec des opérations remove

Cette API fournit une interface robuste et conforme aux standards pour gérer les utilisateurs et les groupes dans DocuWare via des fournisseurs d'identité externes, tout en maintenant les meilleures pratiques en matière de sécurité et de performance.

Versions prises en charge : DocuWare Cloud + 7.13