--- title: "Anleitung: API für DocuWare Benutzerbereitstsellung" slug: "user-provisioning-api-intgration-guide" updated: 2026-04-01T14:21:06Z published: 2026-04-01T14:21:06Z canonical: "knowledgecenter.docuware.com/user-provisioning-api-intgration-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledgecenter.docuware.com/llms.txt > Use this file to discover all available pages before exploring further. # Anleitung: API für DocuWare Benutzerbereitstsellung Der DocuWare Benutzerbereitstellungs-v3-Dienst ist eine SCIM 2.0-konforme REST-API, die eine automatische Benutzerbereitstellung und Gruppenverwaltung von externen Identity Providern (IdPs) wie Azure Entra ID, Okta, Ping Identity oder On-Premise-Verzeichnissen (mithilfe des Tools User Provisioning On-premise directory connector) zu DocuWare-Systemen ermöglicht. ## Basis-URL und Endpunkte ### Struktur der Basis-URL DocuWare Cloud ```xml https://{your-organization}.docuware.cloud/DocuWare/Services/UserProvisioningService/{externalIdp}/scim ``` DocuWare On-Premises ```xml http(s)://{your-server-address}/DocuWare/Services/UserProvisioningService/{externalIdp}/scim ``` Dabei kann `{externalIdp}` folgende Werte annehmen: - `azure` – für Azure Entra ID - `okta `– für Okta - `ping` – für Ping Identity - `onpremise` – für On-Premise-Verzeichnisse - `generic-{identifier}` – für generische Identity Provider ### Verfügbare Endpunkte | **Ressource** | **HTTP-Methode** | **Endpunkt** | **Beschreibung** | | --- | --- | --- | --- | | **Benutzer** | GET | `/{externalIdp}/scim/Users` | Alle externen Benutzer abrufen, mit optionaler Filterung nach userName oder externalId | | | GET | `/{externalIdp}/scim/Users?allDocuWareUsers=true` | Alle Benutzer abrufen, mit optionaler Filterung nach userName oder externalId | | | GET | `/{externalIdp}/scim/Users/{id}` | Bestimmten Benutzer anhand der ID abrufen | | | POST | `/{externalIdp}/scim/Users` | Neuen Benutzer erstellen | | | PUT | `/{externalIdp}/scim/Users/{id}` | Benutzer vollständig ersetzen | | | PATCH | `/{externalIdp}/scim/Users/{id}` | Teilweise Benutzeraktualisierung | | | DELETE | `/{externalIdp}/scim/Users/{id}` | Benutzer löschen | | **Gruppen** | GET | `/{externalIdp}/scim/Groups` | Alle Gruppen abrufen, mit optionaler Filterung nach displayName | | | GET | `/{externalIdp}/scim/Groups/{id}` | Bestimmte Gruppe anhand der ID abrufen | | | POST | `/{externalIdp}/scim/Groups` | Neue Gruppe erstellen | | | PUT | `/{externalIdp}/scim/Groups/{id}` | Gruppe vollständig ersetzen | | | PATCH | `/{externalIdp}/scim/Groups/{id}` | Teilweise Gruppenaktualisierung | | | DELETE | `/{externalIdp}/scim/Groups/{id}` | Gruppe löschen | | **Schemas** | GET | `/{externalIdp}/scim/Schemas` | SCIM-Schemas abrufen | | **Ressourcentypen** | GET | `/{externalIdp}/scim/ResourceTypes` | Unterstützte Ressourcentypen abrufen | | **Integritätsprüfung** | GET | `/AvailabilityCheck` | Prüfung der Dienstverfügbarkeit | ## Authentifizierung ### JWT-Bearer-Authentifizierung Alle Endpunkte (außer der Integritätsprüfung) erfordern eine JWT-Bearer-Token-Authentifizierung: ```json Authorization: Bearer {jwt-token} ``` ### Content-Type Alle Anfragen müssen den SCIM-Content-Type verwenden: ```json Content-Type: application/scim+json ``` ## Benutzerverwaltung ### Benutzer-Schema (Core2EnterpriseUser) ### Benutzer abrufen (GET) Der GET-Users-Endpunkt unterstützt mehrere Varianten zum Abrufen von Benutzerdaten mit optionaler Filterung und Paginierung. Standardmäßig werden nur Benutzer mit externen IDs zurückgegeben (Benutzer von externen Identity Providern). #### 1. Alle externen Benutzer abrufen (Standard) ```json GET /{externalIdp}/scim/Users Authorization: Bearer {token} ``` Gibt alle Benutzer zurück, die eine externalId haben (Benutzer von externen Identity Providern). **Antwort:** ```json {  "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"      ]    }  ] } ``` Hier kommt **Teil 2** (ab „2. Get All DocuWare Users" bis einschließlich „Delete User"): ```html #### 2. Alle DocuWare-Benutzer abrufen ```json GET /{externalIdp}/scim/Users?allDocuWareUsers=true Authorization: Bearer {token} ``` Gibt alle Benutzer im DocuWare-System zurück, einschließlich externer und interner DocuWare-Benutzer. > [!NOTE] > Hinweis: Interne Benutzer haben keine ID > > Interne Benutzer haben in der Antwort keine `id`, da sie nicht extern sind und kein `externalId`-Attribut gesetzt haben, welches als `id` zurückgegeben wird. **Antwort** ```json {  "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. Bestimmten Benutzer anhand der ID abrufen ```json GET /{externalIdp}/scim/Users/{externalId} Authorization: Bearer {token} ``` Gibt einen bestimmten Benutzer anhand seiner externen ID zurück. **Antwort:** ```json {  "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. Benutzer mit Filterung abfragen **Nach Benutzername filtern (in externen Benutzern):** ```json GET /{externalIdp}/scim/Users?filter=userName eq "john.doe" Authorization: Bearer {token} ``` **Nach Benutzername in allen DocuWare-Benutzern filtern:** ```json GET /{externalIdp}/scim/Users?allDocuWareUsers=true&filter=userName eq "john.doe" Authorization: Bearer {token} ``` **Nach externer ID filtern:** ```json GET /{externalIdp}/scim/Users?filter=externalId eq "external-user-id-123" Authorization: Bearer {token} ``` **Benutzer mit Paginierung abrufen:** ```json GET /{externalIdp}/scim/Users?startIndex=2&count=5 Authorization: Bearer {token} ``` ```json GET /{externalIdp}/scim/Users?allDocuWareUsers=true&startIndex=2&count=5 Authorization: Bearer {token} ``` #### Unterstützte Abfrageparameter Paginierung: - startIndex – 1-basierter Index des ersten Ergebnisses (Standard: 1, Minimum: 1) - count – Anzahl der Ergebnisse pro Seite (Standard: alle Ergebnisse, wenn nicht angegeben, Minimum: 0) Filterung: - filter – SCIM-Filterausdruck (unterstützt nur userName eq "value" & externalId eq "value") (Groß-/Kleinschreibung wird nicht berücksichtigt) #### Antwortformat Alle GET /Users-Anfragen geben eine SCIM-ListResponse mit folgender Struktur zurück: **Eigenschaften:** - schemas – Array mit "urn:ietf:params:scim:api:messages:2.0:ListResponse" - totalResults – Gesamtanzahl der übereinstimmenden Benutzer - itemsPerPage – Anzahl der in der aktuellen Antwort zurückgegebenen Benutzer - startIndex – Startindex der aktuellen Seite (1-basiert) - Resources – Array von Benutzerobjekten #### Fehlerantworten 400 Bad Request – Ungültiger Filter: ```json {  "ScimType": "invalidFilter",  "Detail": "Unsupported filter attribute: FirstName",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` ```json {  "ScimType": "invalidFilter",  "Detail": "Unsupported comparison operator: 'ne'",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` Alle GET-`/Users/{externalId}`-Anfragen geben ein Benutzerobjekt mit folgender Struktur zurück: **Eigenschaften des Benutzerobjekts:** - `id` – Externe ID des Benutzers - `userName` – Anmeldename des Benutzers (ohne Domäne, wenn E-Mail bei nicht-generischen IdPs) - `active` – Aktivitätsstatus des Benutzers (boolescher Wert) - `emails` – Array von E-Mail-Objekten mit den Eigenschaften value und primary - `name` – Objekt mit den Eigenschaften givenName und familyName - `meta` – Metadatenobjekt mit resourceType: "User" - `schemas` – Array von SCIM-Schema-Bezeichnern #### Fehlerantworten **404 Not Found – Benutzer nicht gefunden:** ```json {  "Detail": "User with External ID 'external-user-id-404' was not found.",  "Status": 404,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` #### Beispiele Die ersten 5 externen Benutzer abrufen: ```json GET /{externalIdp}/scim/Users?startIndex=1&count=5 ``` Externe Benutzer ab einer bestimmten Position abrufen: ```json GET /{externalIdp}/scim/Users?startIndex=10&count=20 ``` Benutzer nach Benutzername suchen: ```json GET /{externalIdp}/scim/Users?filter=userName eq "john.doe" ``` Benutzer nach Benutzername in allen DocuWare-Benutzern suchen: ```json GET /{externalIdp}/scim/Users?allDocuWareUsers=true&filter=userName eq "jane.smith" ``` Benutzer nach externalId suchen: ```json GET /{externalIdp}/scim/Users?filter=externalId eq "external-user-id-123" ``` Alle DocuWare-Benutzer mit Paginierung abrufen: ```json GET /{externalIdp}/scim/Users?allDocuWareUsers=true&startIndex=1&count=50 ``` ### Benutzer erstellen (POST) #### Funktionsweise der Benutzererstellung Das System implementiert eine intelligente Erstellungs-/Aktualisierungslogik, die folgende Schritte umfasst: 1. Benutzersuche nach externer ID: Zunächst wird versucht, einen vorhandenen Benutzer anhand der angegebenen externalId zu finden. Wird ein Benutzer gefunden, handelt es sich um eine vollständige Übereinstimmung und der vorhandene Benutzer wird mit den Attributen aus der Anfrage aktualisiert. 2. Fallback auf Benutzernamensuche: Wird kein Benutzer anhand der externen ID gefunden, erfolgt die Suche nach dem aus dem Feld `userName` extrahierten Benutzernamen. Wird ein Benutzer gefunden und stimmt die eingehende E-Mail-Adresse mit der E-Mail des vorhandenen Benutzers überein, handelt es sich um eine vollständige Übereinstimmung und der vorhandene Benutzer wird mit den Attributen aus der Anfrage aktualisiert. Stimmen die E-Mail-Adressen nicht überein, kann kein neuer Benutzer erstellt werden, da bereits ein Benutzer mit dem angegebenen `userName` existiert. (Dies führt zu einem 409-Conflict-Fehler.) Logik für Benutzererstellung und -aktualisierung: - **Neuer Benutzer**: Wird kein vorhandener Benutzer anhand von `externalID` oder `userName` gefunden, wird ein neuer Benutzer erstellt. - **Benutzeraktualisierung**: Wird ein vorhandener Benutzer gefunden und entweder über `externalId` oder `userName` + E-Mail zugeordnet, werden die Informationen des Benutzers aktualisiert. - **E-Mail-Validierung**: Bei der Suche nach `userName` wird geprüft, ob die E-Mail des vorhandenen Benutzers mit der angegebenen E-Mail übereinstimmt (Groß-/Kleinschreibung wird nicht berücksichtigt). Stimmen die E-Mails nicht überein, wird eine Ausnahme ausgelöst, um Konflikte zu vermeiden. > [!NOTE] > Hinweise zur Auflösung der E-Mail-Adresse > > Der Dienst ermittelt die E-Mail-Adresse des Benutzers in folgender Prioritätsreihenfolge: > > 1. **Primäre E-Mail**: Verwendet die im E-Mail-Array als primary: true markierte E-Mail-Adresse. > 2. **Erste gültige E-Mail**: Existiert keine primäre E-Mail, wird die erste gültige E-Mail aus dem E-Mail-Array ausgewählt. > 3. **Validierung**: Ist keine der oben genannten Adressen eine gültige E-Mail-Adresse, schlägt die Anfrage mit einem 400 Bad Request fehl. #### Anfrage ```json 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    }  ] } ``` #### Pflicht- und optionale Felder Pflichtfelder: - `schemas` – SCIM-Schema-Bezeichner (muss sowohl das Core- als auch das Enterprise-User-Schema enthalten) - `userName `– Anmeldename des Benutzers (muss eindeutig sein) - `externalId `– Benutzer-ID des externen Identity Providers (muss eindeutig sein) - `active` – Aktivitätsstatus des Benutzers - `emails` – Array von E-Mail-Adressen Optionale Felder: - `name` – Anzeigenameobjekt des Benutzers - `name.givenName` – Vorname - `name.familyName` – Nachname Feldvalidierungsregeln: - **UserName**: Pflichtfeld, Groß-/Kleinschreibung wird beachtet, darf nicht leer sein oder nur Leerzeichen enthalten - **ExternalId**: Pflichtfeld, Groß-/Kleinschreibung wird beachtet, darf nicht leer sein oder nur Leerzeichen enthalten - **Emails**: Mindestens eine gültige E-Mail muss auflösbar sein (bei mehreren E-Mails werden die Regeln zur **Auflösung der E-Mail-Adresse** beachtet) - **Active**: Boolescher Wert - **Name-Felder**: Optionale Zeichenketten für Anzeigezwecke #### Antwort **Erfolg (200 OK):** ```json {  "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"  ] } ``` #### Fehlerantworten 400 Bad Request – Fehlende Pflichtfelder: ```json {  "ScimType": "invalidValue",  "Detail": "Validation failed: UserName: is required",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` 409 Conflict – Benutzer existiert bereits: ```json {  "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"  ] } ``` ### Benutzer aktualisieren (PUT) – Vollständige Benutzerersetzung Die PUT-Operation führt eine vollständige Ersetzung einer Benutzerressource durch. Im Gegensatz zu PATCH, das nur angegebene Felder aktualisiert, ersetzt PUT das gesamte Benutzerobjekt durch die bereitgestellten Daten. #### Einfache PUT-Anfrage ```json PUT /{externalIdp}/scim/Users/{externalId} Content-Type: application/scim+json Authorization: Bearer {token} {  "userName": "john.doe",  "externalId": "external-user-id-123",  "active": true,  "emails": [    {      "value": "john.doe@example.com",      "primary": true    }  ],  "name": {    "givenName": "John",    "familyName": "Doe"  },  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"] } ``` #### **Parameter** - `{externalIdp} `– Bezeichner des externen Identity Providers (azure, okta, ping, onpremise usw.) - `{externalId} `– Die externe ID des zu aktualisierenden Benutzers #### Pflichtfelder für PUT **Alle für die Benutzererstellung obligatorischen Felder müssen angegeben werden:** - `userName `– Anmeldename des Benutzers - `externalId` – Benutzer-ID des externen Identity Providers - `active` – Aktivitätsstatus des Benutzers (boolescher Wert, Standard ist false, wenn nicht angegeben) - `emails` – Array von E-Mail-Adressen (siehe **Auflösung der E-Mail-Adresse**) - `schemas` – SCIM-Schema-Bezeichner (muss sowohl das Core- als auch das Enterprise-User-Schema enthalten) #### Optionale Felder (alte Werte bleiben erhalten, wenn keine neuen angegeben werden) - name – Anzeigenameobjekt des Benutzers - name.givenName – Vorname - name.familyName – Nachname #### Vollständiges PUT-Beispiel ```json PUT /azure/scim/Users/external-user-id-123 Content-Type: application/scim+json Authorization: Bearer {jwt-token} {  "userName": "john.smith",  "externalId": "external-user-id-123",  "active": false,  "name": {    "givenName": "John",    "familyName": "Smith"  },  "emails": [    {      "value": "john.smith@example.com",      "primary": true    }  ],  "schemas": [    "urn:ietf:params:scim:schemas:core:2.0:User",    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"  ] } ``` #### Antwort Erfolg (200 OK): ```json {  "userName": "john.smith",  "active": false,  "emails": [    {      "value": "john.smith@example.com",      "primary": true    }  ],  "name": {    "givenName": "John",    "familyName": "Smith"  },  "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"  ] } ``` #### Fehlerantworten 400 Bad Request – Fehlende Pflichtfelder ```json {  "ScimType": "invalidValue",  "Detail": "Validation failed: UserName: is required",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` 404 Not Found – Benutzer nicht gefunden: ```json {  "Detail": "User with External ID 'external-user-id-404' was not found.",  "Status": 404,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` 409 Conflict – Doppelter Benutzername: ```json {    "ScimType": "uniqueness",    "Detail": "User with username 'john.doe' already exists!",    "Status": 409,    "Schemas": [        "urn:ietf:params:scim:api:messages:2.0:Error"    ] } ``` 409 Conflict – Doppelte ExternalId: ```json {  "ScimType": "uniqueness",  "Detail": "User with External ID 'external-user-id-409' already exists!",  "Status": 409,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` 409 Conflict – Gesperrte Ressource: ```json {  "ScimType": "mutability",  "Detail": "The resource with ID 'external-user-id-409' is immutable.",  "Status": 409,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` #### Validierungsregeln für PUT Alle Validierungsregeln von POST-Operationen gelten auch für PUT-Operationen: - **UserName**: Pflichtfeld, Groß-/Kleinschreibung wird beachtet, darf nicht leer sein oder nur Leerzeichen enthalten - **ExternalId**: Pflichtfeld, Groß-/Kleinschreibung wird beachtet, darf nicht leer sein oder nur Leerzeichen enthalten - **Active**: Boolescher Wert (Standard ist `false`, wenn nicht angegeben) - **Emails**: Mindestens eine gültige E-Mail muss auflösbar sein (bei mehreren E-Mails werden die Regeln zur **Auflösung der E-Mail-Adresse** beachtet) - **Name-Felder**: Optional, aber für die Benutzererfahrung empfohlen - **Schemas**: Muss sowohl das Core- als auch das Enterprise-User-Schema enthalten ### Benutzer-PATCH-Operationen – Leitfaden Die PATCH-Operation ermöglicht teilweise Aktualisierungen von Benutzerattributen mithilfe von SCIM 2.0-Patch-Operationen. Der Dienst unterstützt die Operationen `replace` und `add` für Benutzeraktualisierungen. #### **Grundlegende PATCH-Struktur:** ```json PATCH /{externalIdp}/scim/Users/{id} Content-Type: application/scim+json Authorization: Bearer {token} {  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],  "Operations": [    {      "op": "replace",      "path": "attribute_path",      "value": "new_value"    },    {      "op": "add",      "path": "attribute_path",      "value": "new_value"    }  ] } ``` #### **Unterstützte Operationen** - `replace` – Einen vorhandenen Attributwert aktualisieren - `add `– Einen leeren/vorhandenen Attributwert aktualisieren - `remove` – Wird für Benutzeroperationen nicht unterstützt #### **Unterstützte Attributpfade** Benutzer-Aktivitätsstatus: ```json {  "op": "replace",  "path": "active",  "value": "false" } ``` Aktualisierung des Benutzernamens: ```json {  "op": "replace",  "path": "userName",  "value": "new.username" } ``` Name-Felder: ```json {  "op": "replace",  "path": "name.givenName",  "value": "NewFirstName" } ``` ```json {  "op": "replace",  "path": "name.familyName",  "value": "NewLastName" } ``` E-Mail-Adresse: ```json {  "op": "replace",  "path": "emails",  "value": "new.email@example.com" } ``` ```json {  "op": "replace",  "path": "emails[primary eq true].value",  "value": "new.email@example.com" } ``` **Hinweise:** - Beide Syntaxvarianten für den E-Mail-Pfad sind gültig - Die E-Mail-Adresse muss ein gültiges E-Mail-Format haben Externe ID ```json {  "op": "replace",  "path": "externalId",  "value": "new-external-id-456" } ``` Beispiel mit mehreren Operationen: ```json PATCH /{externalIdp}/scim/Users/{id} Content-Type: application/scim+json Authorization: Bearer {token} {  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],  "Operations": [    {      "op": "replace",      "path": "active",      "value": "false"    },    {      "op": "replace",      "path": "name.givenName",      "value": "Jonathan"    },    {      "op": "replace",      "path": "name.familyName",      "value": "Smith"    },    {      "op": "replace",      "path": "emails",      "value": "jonathan.smith@example.com"    }  ] } ``` > [!NOTE] > Wichtige Hinweise: > > - Alle Operationen werden in der angegebenen Reihenfolge nacheinander verarbeitet > - Die Operation `remove` wird nicht unterstützt und gibt einen Fehler zurück > - Für E-Mail-bezogene Felder wird eine E-Mail-Validierung durchgeführt > - Das Feld `active `erfordert boolesche Zeichenkettenwerte ("true" oder "false") > - Ungültige Attributpfade führen zu einem 400 Bad Request-Fehler > - Wenn die `externalId` oder der `userName` bereits von einem anderen Benutzer belegt ist, führt dies zu einem Conflict-Fehler Fehlerbehandlung: - **400 Bad Request**: Ungültiger Operationstyp, nicht unterstützter Pfad oder Validierungsfehler - **404 Not Found**: Benutzer mit der angegebenen ID nicht gefunden - **409 Conflict**: Die Aktualisierung würde einen Konflikt verursachen (z. B. doppelter Benutzername, externalId) #### Unterstützte Benutzerattribute für PATCH-Operationen - `userName` – Anmeldename des Benutzers - `externalId `– Benutzer-ID des externen Identity Providers - `name.givenName` – Vorname - `name.familyName` – Nachname - `active` – Aktivitätsstatus des Benutzers (true/false) - `emails/emails[].value `– E-Mail-Adresse ### Benutzer löschen (DELETE) Die DELETE-Operation führt eine Soft-Löschung eines Benutzers aus dem DocuWare-System durch. Diese Operation deaktiviert den Benutzer. #### Einfache DELETE-Anfrage ```json DELETE /{externalIdp}/scim/Users/{externalId} Authorization: Bearer {token} ``` Parameter: - `{externalIdp} `– Bezeichner des externen Identity Providers (azure, okta, ping usw.) - `{externalId} `– Die externe ID des zu löschenden Benutzers #### Anfragebeispiel ```json DELETE /azure/scim/Users/external-user-id-123 Authorization: Bearer {jwt-token} ``` #### Antwort Erfolg (204 No Content): ```json HTTP/1.1 204 No Content Content-Type: application/scim+json ``` Die DELETE-Operation gibt bei Erfolg HTTP 204 (No Content) mit einem leeren Antworttext zurück. #### Fehlerantworten 404 Not Found – Benutzer nicht gefunden: ```json {  "Detail": "User with External ID 'ExternalUser112' was not found.",  "Status": 404,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` 409 Conflict – Benutzer ist derzeit gesperrt und kann nicht gelöscht werden: ```json {  "ScimType": "mutability",  "Detail": "The resource 'ExternalUser11' with ID 'ExternalUser11' is immutable.",  "Status": 409,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` Alternative zur Löschung: Anstatt einen Benutzer zu löschen, können Sie ihn alternativ mit einer PATCH- oder PUT-Operation deaktivieren: ```json PATCH /{externalIdp}/scim/Users/{externalId} Content-Type: application/scim+json Authorization: Bearer {token} {  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],  "Operations": [    {      "op": "replace",      "path": "active",      "value": "false"    }  ] } ``` ``` ## Gruppenverwaltung ### Gruppen-Schema (Core2Group) ### Funktionsweise der Gruppenerstellung Das System implementiert eine intelligente Erstellungs-/Aktualisierungslogik für Gruppen, die folgende Schritte umfasst: 1. Gruppensuche nach DisplayName: Zunächst wird versucht, eine vorhandene Gruppe anhand des angegebenen `displayName` zu finden. Wird eine gefunden, wird sie als Gruppenaktualisierung behandelt, andernfalls als Gruppenerstellung. 2. Logik für Gruppenerstellung und -aktualisierung: - Neue Gruppe: Wird keine vorhandene Gruppe anhand des `displayName` gefunden, wird eine neue Gruppe mit den angegebenen Mitgliedern erstellt. - Gruppenaktualisierung: Wird eine vorhandene Gruppe gefunden, werden die Gruppeninformationen aktualisiert und neue Mitglieder zur bestehenden Mitgliedschaft hinzugefügt (vorhandene Mitglieder werden nicht ersetzt). - Mitgliederhinzufügung: Neue Mitglieder werden zu bestehenden Gruppen hinzugefügt, ohne aktuelle Mitglieder zu entfernen. - Duplikatvermeidung: Das System verhindert das Hinzufügen doppelter Mitglieder zu Gruppen. > [!NOTE] > Wichtige Hinweise zur Gruppenerstellung: > > - Eindeutigkeit des Anzeigenamens: Gruppen werden anhand ihres `displayName` identifiziert. > - Mitgliederauflösung: Alle Mitgliedsreferenzen (Feld `value`) müssen gültige `externalId`-Werte vorhandener Benutzer sein. > - Inkrementelle Mitgliedschaft: POST-Operationen auf bestehende Gruppen fügen Mitglieder inkrementell hinzu, anstatt die gesamte Mitgliedschaft zu ersetzen. > - Mitgliedervalidierung: Das System fügt nur vorhandene Mitglieder hinzu. Existiert ein Mitglied mit dem angegebenen `value` (externalId) nicht, wird es ohne Fehlermeldung übersprungen. > - Geltungsbereich des externen Identity Providers: Sie können nur den Teil der Gruppe verwalten, der aus Benutzern des aktuellen `externalIdp` besteht. Benutzer anderer externer Identity Provider oder interne DocuWare-Benutzer bleiben von diesen Operationen unberührt. > - Antwort: Die Antwort enthält nur Gruppenmitglieder, die externe Benutzer sind, die vom angegebenen `externalIdp` (z. B. azure, okta, ping, onpremise oder generic) bereitgestellt wurden. Interne Benutzer oder Benutzer, die von anderen externen Identity Providern erstellt wurden, sind von der Antwort ausgeschlossen. Format der Mitgliedsreferenz: - Mitglieder werden anhand ihrer `externalId` referenziert (nicht die interne DocuWare-Benutzer-ID) - Jedes Mitgliedsobjekt muss ein Feld `value` mit der externen ID des Benutzers enthalten - Das optionale Feld `display` (der `userName` des Benutzers) kann angegeben werden, ist aber für die Mitgliedschaftszuweisung nicht erforderlich ### Gruppe erstellen (POST) ```json 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"    }  ] } ``` #### Antwort ```json {  "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"] } ``` **Erstellung einer leeren Gruppe:** ```json 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": [] } ``` **Pflichtfelder:** - `schemas` – SCIM-Schema-Bezeichner (muss `"urn:ietf:params:scim:schemas:core:2.0:Group"` enthalten) - `displayName` – Anzeigename der Gruppe (wird zur Identifikation verwendet) - `members` – Array von Mitgliedsobjekten (kann bei der Gruppenerstellung leer sein) - `members[].value `– Externe ID des Benutzers (erforderlich, wenn Mitglieder angegeben werden) #### Fehlerantworten **400 Bad Request – Fehlende Pflichtfelder:** ```json {  "ScimType": "invalidValue",  "Detail": "Validation failed: DisplayName: is required",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` ```json {  "ScimType": "invalidValue",  "Detail": "Validation failed: Members: The Members field is required.",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` ```json {  "ScimType": "invalidValue",  "Detail": "Validation failed: Members[0].Value: Member Value is required.",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` ### Gruppen abrufen (GET) Der GET-Groups-Endpunkt unterstützt mehrere Varianten zum Abrufen von Gruppendaten mit optionaler Filterung und Paginierung. Gruppen enthalten Mitglieder, die externe Benutzer des angegebenen externen Identity Providers sind. #### 1. Alle Gruppen abrufen (Standard) ```json GET /{externalIdp}/scim/Groups Authorization: Bearer {token} ``` Gibt alle in DocuWare vorhandenen Gruppen zurück, ohne die Mitglieder einzuschließen. Diese können über die GET-Anfrage /Groups/{groupId} abgerufen werden. Antwort: ```json {  "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. Bestimmte Gruppe anhand der ID abrufen ```json GET /{externalIdp}/scim/Groups/{groupId} Authorization: Bearer {token} ``` Ruft Details für eine bestimmte Gruppe anhand ihrer Gruppen-ID ab. Das Attribut `members` enthält nur externe Benutzer, die vom angegebenen Identity Provider bereitgestellt wurden. **Antwort:** ```json {  "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. Gruppen mit Filterung abfragen Nach Anzeigename filtern: ```json GET /{externalIdp}/scim/Groups?filter=displayName eq "Engineering Team" Authorization: Bearer {token} ``` Gruppen mit Paginierung abrufen: ```json GET /{externalIdp}/scim/Groups?startIndex=1&count=10 Authorization: Bearer {token} ``` ```json GET /{externalIdp}/scim/Groups?startIndex=2&count=5 Authorization: Bearer {token} ``` #### Unterstützte Abfrageparameter Filterung: - `filter `– SCIM-Filterausdruck (unterstützt nur displayName eq "value") (Groß-/Kleinschreibung wird nicht berücksichtigt, exakte Übereinstimmung) **Paginierung:** - `startIndex `– 1-basierter Index des ersten Ergebnisses (Standard: 1, Minimum: 1) - `count `– Anzahl der Ergebnisse pro Seite (Standard: alle Ergebnisse, wenn nicht angegeben, Minimum: 0) #### Antwortformat Alle GET-/`Groups`-Anfragen geben eine SCIM-ListResponse mit folgender Struktur zurück: **Eigenschaften der ListResponse:** - `schemas` – Array mit `"urn:ietf:params:scim:api:messages:2.0:ListResponse"` - `totalResults `– Gesamtanzahl der übereinstimmenden Gruppen - `itemsPerPag`e – Anzahl der in der aktuellen Antwort zurückgegebenen Gruppen - `startIndex` – Startindex der aktuellen Seite (1-basiert) - `resources `– Array von Gruppenobjekten (Attribut members nur verfügbar, wenn nach Gruppen-ID abgerufen) **Eigenschaften des Gruppenobjekts:** - `id` – Externe ID der Gruppe - `displayName` – Anzeigename der Gruppe - `members` – Array von Mitgliedsobjekten (nur externe Benutzer des angegebenen `externalIdp`) - `value `– Externe Benutzer-ID des Mitglieds - `display` – Benutzername des Mitglieds - `meta `– Ressourcentyp des Objekts - `schemas` – Array mit SCIM-Schema-Bezeichnern #### > [!NOTE] > Hinweise zu Gruppenantworten > > **Mitgliederfilterung:** > > - In den Antworten werden nur Mitglieder aufgeführt, die externe Benutzer des angegebenen {`externalIdp`} sind > - Interne DocuWare-Benutzer und Benutzer anderer externer Identity Provider werden ausgeschlossen > - Leere Gruppen (ohne qualifizierende Mitglieder) können dennoch in den Ergebnissen erscheinen, sofern sie existieren > > **Gruppenidentifikation:** > > - Gruppen werden für GET-Operationen anhand ihrer `ID `identifiziert > - Der displayName wird für die Filterung und Gruppensuche bei der Erstellung/Aktualisierung verwendet #### Fehlerantworten 400 Bad Request – Ungültiger Filter: Filterung nach falschem Attribut: ```json {  "ScimType": "invalidFilter",  "Detail": "Unsupported filter attribute: id",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` Filterung mit ungültigem Ausdruck (gültig ist nur filter=displayName eq "groupName"): ```json {  "ScimType": "invalidFilter",  "Detail": "Invalid filter expression: 'displasyname asd \"engineering team\"'",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` Filterung mit nicht unterstütztem Vergleichsoperator: ```json {  "ScimType": "invalidFilter",  "Detail": "Unsupported comparison operator: 'ne'",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` 404 Not Found – Gruppe nicht gefunden: ```json {  "Detail": "Group with identifier 'group-id-404' was not found.",  "Status": 404,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` ### Gruppenmitgliedschaft aktualisieren (PATCH) Die PATCH-Operation ermöglicht teilweise Aktualisierungen von Gruppenattributen mithilfe von SCIM 2.0-Patch-Operationen. Der Dienst unterstützt die Operationen add, remove und replace (nur für den Gruppen-displayName) für die Gruppenverwaltung. #### Grundlegende PATCH-Struktur ```json 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"    }  ] } ``` #### Unterstützte Operationen Mitglieder hinzufügen (`add`): Fügt neue Mitglieder zur Gruppe hinzu, ohne vorhandene Mitglieder zu entfernen. ```json 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"        }      ]    }  ] } ``` Bestimmte Mitglieder entfernen (`remove`): Entfernt angegebene Mitglieder aus der Gruppe. ```json 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"        }      ]    }  ] } ``` Alle Mitglieder entfernen (`remove`): Entfernt alle Mitglieder aus der Gruppe, die Benutzer des angegebenen externalIdp sind (leert die Gruppe). ```json 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"    }  ] } ``` Wenn bei der remove-Operation kein `value `angegeben wird, werden alle externen Mitglieder (des angegebenen externalIdp) entfernt. 1. **Gruppen-Anzeigename ersetzen (**replace**)** Aktualisiert den Anzeigenamen der Gruppe. ```json 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"    }  ] } ``` #### Unterstützte Attributpfade | **Pfad** | **Operationen** | **Beschreibung** | **Wertformat** | | --- | --- | --- | --- | | `displayName` | `replace, add` | Anzeigename der Gruppe | Zeichenkette | | `members` | `add, remove` | Gruppenmitgliedschaft | Array von Mitgliedsobjekten | #### Mehrere Operationen in einer einzelnen Anfrage Sie können mehrere Operationen in einer einzelnen PATCH-Anfrage kombinieren: ```json 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 des Mitgliedsobjekts Verwenden Sie bei der Angabe von Mitgliedern in Operationen folgendes Format: **Pflichtfelder:** - `value` – Die externe ID des Benutzers, der hinzugefügt/entfernt werden soll **Beispiel für ein Mitgliedsobjekt:** ```json {  "value": "external-user-id-123" } ``` #### Details zum Verhalten der Operationen **Add-Operation:** - Fügt angegebene Mitglieder zur Gruppe hinzu - Ignoriert Mitglieder, die bereits in der Gruppe sind (keine Duplikate) - Nicht existierende externe Benutzer-IDs werden stillschweigend ignoriert - Beeinflusst keine vorhandenen Mitglieder **Remove-Operation:** - Mit `value`: Entfernt nur die angegebenen Mitglieder (sofern es sich um Benutzer des angegebenen externalIdp handelt) - Ohne `value`: Entfernt alle Mitglieder (Benutzer des angegebenen externalIdp) aus der Gruppe - Ignoriert externe IDs, die nicht aktuelle Mitglieder sind - Beeinflusst keine nicht angegebenen Mitglieder **Replace-Operation:** - Für `displayName`: Aktualisiert den Gruppennamen #### Antworten - Erfolgreiche PATCH-Antwort (204 No Content) - 400 Bad Request – Ungültige Operation - 400 Bad Request – Ungültiger Pfad - 400 Bad Request – Ungültiges Mitgliedsformat - 404 Not Found – Gruppe nicht gefunden - 409 Conflict – Gruppenname existiert bereits #### Wichtige Hinweise zu PATCH-Operationen **Operationsverarbeitung:** - Operationen werden in der Reihenfolge ihres Auftretens nacheinander verarbeitet **Mitgliedervalidierung:** - Externe Benutzer-IDs müssen auf vorhandene Benutzer verweisen - Ungültige externe IDs werden stillschweigend ignoriert (kein Fehler wird ausgelöst) - Es werden nur externe Benutzer desselben Identity Providers (`externalIdp`) verwaltet **Gruppenstatus:** - Die Antwort enthält nur externe Benutzer des angegebenen `{externalIdp}` - Interne DocuWare-Benutzer und Benutzer anderer Identity Provider werden von den Antworten ausgeschlossen - Leere Gruppen bleiben gültig und werden in den Antworten aufgeführt ### Gruppe aktualisieren (PUT) – Vollständige Gruppenersetzung Die PUT-Operation führt eine vollständige Ersetzung des vom externalIdp bereitgestellten Gruppenteils durch. Im Gegensatz zu PATCH, das nur angegebene Felder aktualisiert, ersetzt PUT das gesamte Gruppenobjekt durch die bereitgestellten Daten. #### Einfache PUT-Anfrage ```json 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"    }  ] } ``` #### Parameter - `{externalIdp} `– Bezeichner des externen Identity Providers (azure, okta, ping usw.) - `{groupId} `– Die ID der zu aktualisierenden Gruppe #### Pflichtfelder für PUT Alle für die Gruppenerstellung obligatorischen Felder müssen angegeben werden: - `schemas` – SCIM-Schema-Bezeichner (muss `"urn:ietf:params:scim:schemas:core:2.0:Group"` enthalten) - `displayName` – Anzeigename der Gruppe - `members` – Array von Mitgliedsobjekten (kann leer sein) #### Vollständiges PUT-Beispiel ```json 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"    }  ] } ``` #### Antwort Erfolg (200 OK): ```json {  "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"  } } ``` > [!NOTE] > Wichtige Hinweise zum PUT-Verhalten > > 1. **Vollständige Mitgliederersetzung**: PUT ersetzt die gesamte Mitgliederliste, die vom aktuellen `externalIdp` verwaltet wird. Jedes Mitglied, das nicht in der Anfrage enthalten ist, wird aus der Gruppe entfernt. > 2. **Aktualisierung des Anzeigenamens**: Der Anzeigename der Gruppe kann über PUT-Operationen geändert werden. > 3. **Mitgliedervalidierung**: Alle angegebenen externen Mitglieds-IDs müssen auf vorhandene Benutzer verweisen. Ungültige externe IDs werden stillschweigend übersprungen. > 4. **Geltungsbereich des externen Identity Providers**: Nur Mitglieder, die externe Benutzer des angegebenen `{externalIdp}` sind, werden durch diese Operation verwaltet. Interne DocuWare-Benutzer und Benutzer anderer Identity Provider bleiben unberührt. > 5. **Gruppenidentifikation**: Die Gruppe wird durch den Parameter `{groupId}` in der URL identifiziert. #### Fehlerantworten 400 Bad Request – Fehlende Pflichtfelder: ```json {  "ScimType": "invalidValue",  "Detail": "Validation failed: DisplayName: is required",  "Status": 400,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` 404 Not Found – Gruppe nicht gefunden: ```json {  "Detail": "Group with identifier 'group-id-404' was not found.",  "Status": 404,  "Schemas": [      "urn:ietf:params:scim:api:messages:2.0:Error"  ] } ``` #### Validierungsregeln für PUT Alle Validierungsregeln von POST-Operationen gelten auch für PUT-Operationen: - **DisplayName**: Pflichtfeld, Groß-/Kleinschreibung wird beachtet, darf nicht leer sein oder nur Leerzeichen enthalten - **Members**: Optionales Array, jedes Mitglied muss ein gültiges value-Feld mit der externen ID eines vorhandenen Benutzers haben - **Externe Mitglieds-IDs**: Müssen auf vorhandene Benutzer desselben externen Identity Providers verweisen - **Schemas**: Muss das Core-Group-Schema enthalten ### Gruppe löschen (DELETE) – Nicht unterstützt Die DELETE-Operation für Gruppen wird vom DocuWare Benutzerbereitstellungs-v3-Dienst **nicht unterstützt**. Der Versuch, eine Gruppe zu löschen, führt zu einer Fehlerantwort. ## HTTP-Statuscodes | **Statuscode** | **Beschreibung** | **Verwendung** | | --- | --- | --- | | 200 OK | Erfolg | GET-, PATCH-Operationen | | 201 Created | Ressource erstellt | POST-Operationen | | 204 No Content | Erfolg, kein Inhalt | DELETE-, einige PATCH-Operationen | | 400 Bad Request | Ungültige Anfrage | Validierungsfehler | | 401 Unauthorized | Authentifizierung erforderlich | Fehlender/ungültiger Token | | 403 Forbidden | Zugriff verweigert | Unzureichende Berechtigungen | | 404 Not Found | Ressource nicht gefunden | Ungültige Ressourcen-ID | | 409 Conflict | Ressourcenkonflikt | Doppelter Benutzername/E-Mail | | 500 Internal Server Error | Serverfehler | Dienstprobleme | | 501 Not Implemented | Nicht unterstützt | Vom Produkt nicht unterstützt | ## Format der Fehlerantworten ```json {  "ScimType": "invalidValue",  "Detail": "Validation failed.",  "Status": 400,  "Schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"] } ``` ## Konfigurationsanforderungen ### Einrichtung des Identity Providers 1. Konfigurieren Sie Ihren IdP so, dass er auf die entsprechende Tenant-URL verweist 2. Richten Sie die OAuth 2.0/OIDC-Authentifizierung mit JWT-Tokens ein 3. Konfigurieren Sie die korrekten Scopes: `docuware.userProvisioning` 4. Stellen Sie sicher, dass der Benutzer, der die API-Operationen ausführt, über ausreichende Berechtigungen verfügt. ### Unterstützte Identity Provider - **Azure Entra ID (Azure AD)**: Verwenden Sie `azure` als externalIdp - **Okta**: Verwenden Sie `okta` als externalIdp - **Ping Identity**: Verwenden Sie `ping` als externalIdp - **On-Premise**: Verwenden Sie `onpremise` als externalIdp - **Generischer IdP** ## Schema-Informationen ### Verfügbare Schemas abrufen ```json GET /{externalIdp}/scim/Schemas Authorization: Bearer {token} ``` ### Ressourcentypen abrufen ```json GET /{externalIdp}/scim/ResourceTypes   Authorization: Bearer {token} ``` ## Integritätsprüfung ### Dienstverfügbarkeit ```json GET /AvailabilityCheck ``` Dieser Endpunkt erfordert keine Authentifizierung und gibt 200 OK zurück, wenn der Dienst ausgeführt wird. ## Beispiel-Integrationsworkflows ### Vollständiger Benutzerbereitstellungs-Workflow 1. **Benutzer erstellen**: POST an `/Users` mit Benutzerdetails 2. **Erstellung überprüfen**: GET `/Users/{id}` zur Bestätigung 3. **Benutzer aktualisieren**: PATCH `/Users/{id}` für Änderungen 4. **Zu Gruppen hinzufügen**: PATCH `/Groups/{groupId}` um den Benutzer hinzuzufügen 5. **Deaktivieren**: PATCH `/Users/{i`d} mit `active: false` ### Gruppenverwaltungs-Workflow 1. **Gruppe erstellen**: POST an `/Groups` mit Gruppendetails 2. **Mitglieder hinzufügen**: PATCH `/Groups/{id}` mit Add-Operationen 3. **Namen aktualisieren**: PATCH `/Groups/{id}` mit displayName-Änderung 4. **Mitglieder entfernen**: PATCH /`Groups/{id}` mit Remove-Operationen Diese API bietet eine robuste, standardkonforme Schnittstelle für die Verwaltung von Benutzern und Gruppen in DocuWare über externe Identity Provider und wahrt dabei bewährte Sicherheits- und Leistungspraktiken. ## Unterstützte Versionen: DocuWare Cloud + 7.15 + 7.14 + 7.13