Anleitung: API für DocuWare Benutzerbereitstsellung

Prev Next

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

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

DocuWare On-Premises

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:

Authorization: Bearer {jwt-token}

Content-Type

Alle Anfragen müssen den SCIM-Content-Type verwenden:

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)

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

Gibt alle Benutzer zurück, die eine externalId haben (Benutzer von externen Identity Providern).

Antwort:

{

  "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

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

Gibt alle Benutzer im DocuWare-System zurück, einschließlich externer und interner DocuWare-Benutzer.

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

{

  "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

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

Authorization: Bearer {token}

Gibt einen bestimmten Benutzer anhand seiner externen ID zurück.

Antwort:

{

  "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):

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

Authorization: Bearer {token}

Nach Benutzername in allen DocuWare-Benutzern filtern:

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

Authorization: Bearer {token}

Nach externer ID filtern:

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

Authorization: Bearer {token}

Benutzer mit Paginierung abrufen:

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

Authorization: Bearer {token}
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:

{

  "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"

  ]

}

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:

{

  "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:

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

Externe Benutzer ab einer bestimmten Position abrufen:

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

Benutzer nach Benutzername suchen:

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

Benutzer nach Benutzername in allen DocuWare-Benutzern suchen:

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

Benutzer nach externalId suchen:

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

Alle DocuWare-Benutzer mit Paginierung abrufen:

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.

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

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):

{

  "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:

{

  "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:

{

  "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

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

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):

{

  "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

{

  "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:

{

  "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:

{

    "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:

{

  "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:

{

  "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:

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:

{
  "op": "replace",
  "path": "active",
  "value": "false"
}

Aktualisierung des Benutzernamens:

{
  "op": "replace",
  "path": "userName", 
  "value": "new.username"
}

Name-Felder: 

{
  "op": "replace",
  "path": "name.givenName",
  "value": "NewFirstName"
}
{

  "op": "replace",

  "path": "name.familyName", 

  "value": "NewLastName"

}

E-Mail-Adresse:

{
  "op": "replace",
  "path": "emails",
  "value": "new.email@example.com"
}
{
  "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

{
  "op": "replace",
  "path": "externalId",
  "value": "new-external-id-456"
}

Beispiel mit mehreren Operationen:

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"

    }

  ]

}

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

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

DELETE /azure/scim/Users/external-user-id-123

Authorization: Bearer {jwt-token}

Antwort

Erfolg (204 No Content):

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:

{

  "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:

{

  "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:

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.

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)


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



{

  "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:

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:

{

  "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"

  ]

}

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)

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:

{

  "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

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:

{

  "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:

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

Authorization: Bearer {token}

Gruppen mit Paginierung abrufen:

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

Authorization: Bearer {token}
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

  • itemsPerPage – 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

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:

{

  "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"):

{

  "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:

{

  "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:

{

  "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

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.

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.

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).

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.

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:

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:

{
  "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

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

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):

{

  "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"

  }

}

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:

{

  "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:

{

  "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

{

  "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

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

Ressourcentypen abrufen

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

Integritätsprüfung

Dienstverfügbarkeit

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/{id} 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.13