Usermanagement-App

Usermanagement-App

 Funktionsumfang der UserManagement-App

Die Usermanagement-App ermöglicht die Verwaltung von Benutzern und Gruppen. In der d.velop cloud kannst du mit der App auch die Administratorrechte vergeben. Du kannst die Benutzer sowie Gruppenzugehörigkeiten mithilfe einer REST-API abfragen und ändern.

Für alle aufgelisteten API-Funktionen muss die Authentifizierung per Bearer-Token erfolgen. Weitere Informationen kannst Du dem Kapitel Authentifizieren einer App mit Anfragen außerhalb des Benutzerkontextes der API-Dokumentation der IdentityProvider-App entnehmen.

 Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle der UserManagement-App verwenden kannst. Neben der klassischen Schnittstelle gibt es eine Schnittstelle nach SCIM 2.0 (RFC 7643).

 SCIM 2.0 Schnittstelle

Mithilfe der SCIM 2.0 Schnittstelle kannst Du Benutzer und Gruppen verwalten oder Informationen zu Benutzern und Gruppen auslesen. Nähere Informationen zur Verwendung der SCIM Schnittstelle, sowie Beispiele findest Du in der entsprechenden Dokumentation zu RFC 7643.

 Einschränkungen/Besonderheiten der SCIM 2.0 Implementierung

Die Basis URI für die SCIM Schnittstelle lautet <SystembaseUri>/Usermanagement/scim.
Neben der Authentifizierung mithilfe eines IDP API Keys als Bearer-Token, kann auch eine d.ecs identityprovider AuthSessionId übergeben werden.
Zugriff haben nur Benutzer die Administrator-Rechte haben oder Mitglied der SCIM_GROUP sind.
Die Benutzeroberfläche zeigt nur wenige der vorhandenen SCIM Attribute an, dennoch werden diese an d.ecs identityprovider übermittelt und stehen dort auch zur Verfügung.
Unterstützt werden HTTP GET, POST, PUT, PATCH und DELETE auf der Benutzer sowie Gruppenressource.
Für die Suche werden die Filter "eq" (Gleichheit), "sw" (Beginnt mit) und "co" (Enthält) unterstützt, logische Operatoren werden nicht unterstützt.
Unterstützt werden derzeit folgende Benutzerattribute:

  • Id
  • ExternalId
  • UserName
  • DisplayName
  • Name (mit FamilyName, GivenName, Formatted, MiddleName, HonorificPrefix, HonorificSuffix)
  • Title
  • Locale
  • PreferredLanguage
  • Emails
  • Active

Einige Attribute unterliegen Längenbeschränkungen, FamilyName und GivenName sind jeweils auf 100 Zeichen begrenzt, die Länge der primären Email-Adresse auf 1000 Zeichen. Sollte es keine primäre Email -Adresse geben, so ist die erste Email-Adresse ebenfalls auf 1000 Zeichen begrenzt.
Informationen zu den Benutzerbildern können über die Schnittstelle derzeit noch nicht verarbeitet werden.

 Verwalten von Benutzern mithilfe der klassischen Schnittstelle

Die UserManagement-App ermöglicht dir einzelne Benutzer und Benutzerbilder zu verwalten.

 Abfrufen der Benutzerliste

Um eine Liste aller Benutzer abzurufen, muss deine App eine HTTP GET-Anforderung an die UserManagement-App senden.

Request


GET /usermanagement/user
Accept: application/json

Response Die Antwort enthält ein JSON-Objekt mit einer Liste von Benutzerobjekten.


{
    "users": [
        {
            "id" : "DF288708-FE65-492C-AD4E-7D747909CB28",
            "mail" : "john.smith@d-velop.de",
            "firstName" : "John",
            "lastName" : "Smith",
            "pictureId" : "DF288708-FE65-492C-AD4E-7D747909CB28",
            "_links": {
                "self": {
                    "href": "/usermanagement/user/DF288708-FE65-492C-AD4E-7D747909CB28"
                }
            }
        },
        ...
    ]
}

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.

 Erstellen eines Benutzers

Um einen Benutzer zu erstellen, muss deine App eine HTTP POST-Anforderung an die UserManagement-App senden.

Hierbei wird ein vollständiges Benutzerobjekt im Body mitgegeben.


{
    "mail" : "john.smith@d-velop.de",
    "firstName" : "John",
    "lastName" : "Smith"
}

Request


POST /usermanagement/user

Response

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
201CreatedDie Anfrage wurde erfolgreich verarbeitet. Im Location-Header findest du die relative URL zur Ressource des neuen Benutzers.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters nicht gültig.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

 Abrufen von Benutzern

Um einen Benutzer abzurufen, muss deine App eine HTTP GET-Anforderung an die UserManagement-App senden.

Request


GET /usermanagement/user/{id}
Accept: application/json

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID des Benutzers, der abgerufen werden soll

Response

Die Antwort enthält ein JSON-Objekt mit einem Benutzerobjekt.


{
    "id" : "DF288708-FE65-492C-AD4E-7D747909CB28",
    "mail" : "john.smith@d-velop.de",
    "firstName" : "John",
    "lastName" : "Smith",
    "pictureId" : "DF288708-FE65-492C-AD4E-7D747909CB28",
    "_links": {
        "self": {
            "href": "/usermanagement/user/DF288708-FE65-492C-AD4E-7D747909CB28"
        }
    }
}

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
404Not FoundDie angegebene ID existiert nicht. Es werden keine Daten übermittelt.

 Ändern eines Benutzers

Um einen Benutzer zu ändern, muss deine App eine HTTP PUT-Anforderung an die UserManagement-App senden. Hierbei wird ein vollständiges Benutzerobjekt im Body mitgegeben. Alle Werte von diesem Body werden übernommen.


{
    "mail" : "john.smith@d-velop.de",
    "firstName" : "John",
    "lastName" : "Smith"
}

Request


PUT /usermanagement/user/{id}
Accept: application/json

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID des Benutzers, der geändert werden soll

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDer Benutzer wurde erfolgreich geändert.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters nicht gültig.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

 Löschen eines Benutzers

Um einen Benutzer zu löschen, muss deine App eine HTTP DELETE-Anforderung an die UserManagement-App senden.

Request


DELETE /usermanagement/user/{id}
Accept: application/json

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID des Benutzers, der gelöscht werden soll

Response

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDer Benutzer wurde erfolgreich gelöscht.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden.
404Not FoundDer Benutzer wurde nicht gefunden.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

Hinweis

Info: Wenn du als Antwort einen "Bad Request"-Statuscode erhältst, kann es sein, dass der Benutzer nicht gelöscht werden darf, weil er der letzte Benutzer in der administrativen Gruppe des Mandanten ist. Der letzte Benutzer kann nicht gelöscht werden, da ansonsten kein Zugriff mehr auf die Cloud-Instanz möglich wäre.

 Abrufen eines Benutzerbilds

Um das Bild eines Benutzers abzurufen, muss deine App eine HTTP GET-Anforderung an die UserManagement-App senden.

Request


GET /usermanagement/picture/{id}

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID des Benutzers, dessen Bild abgerufen werden soll

Response Die Antwort enthält das Bild vom angegebenen Benutzer.

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDas Bild wurde erfolgreich gesendet.
400Bad RequestDie angegebene ID war ungültig.
415Unsupported Media TypeEs wurde eine JSON-Anfrage gestellt, welche nicht unterstützt wird.

 Ändern des Benutzerbilds

Um das Bild eines Benutzers zu ändern, muss deine App eine HTTP PUT-Anforderung an die UserManagement-App senden. Das Bild muss als Teil einer MultiPart-Anfrage geschickt werden, wobei als Name uploadedData verwendet werden muss.

Request


PUT /usermanagement/picture/{id}
Content-Type: multipart/form-data

Der Body der Anforderung muss dabei folgenden Content-Disposition-Eintrag enthalten.


Content-Disposition: form-data; name="uploadedData"; filename="example.png"

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID des Bildes, das geändert werden soll

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDas Bild wurde erfolgreich geändert.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters ungültig.
404Not FoundDer Benutzer wurde nicht gefunden und sein Bild konnte nicht geändert werden.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

 Löschen eines Benutzerbilds

Um das Bild eines Benutzers zu löschen, muss deine App eine HTTP DELETE-Anforderung an die UserManagement-App senden.

Request


DELETE /usermanagement/picture/{userId}

Hinweise zu den Parametern

ParameterBeschreibung
userIdDie ID des Benutzers, dessen Bild gelöscht werden soll

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDas Bild wurde erfolgreich gelöscht.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters ungültig.
404Not FoundDer Benutzer konnte nicht gefunden werden oder der Benutzer hat kein Bild gespeichert. Das Bild wurde nicht gelöscht.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

 Verwalten von Gruppen

Die UserManagement-App ermöglicht dir Gruppen und einzelne Gruppenmitglieder zu verwalten.

Als Gruppenmitglieder werden nur Benutzer unterstützt:

ArtKeyBeschreibung
BenutzeruserId in diesem Element ist die ID eines Benutzers, der Mitglied dieser Gruppe ist

Besondere IDs

Die administrative Gruppe des Mandanten hat die feste ID '6DB690CB-EA1B-4D45-B00B-63A2E7B21816'. Wenn ein Benutzer in dieser Gruppe ist, erhält er automatisch administrative Rechte in der entsprechenden Cloud-Instanz.

 Abrufen der Gruppenliste

Um eine Liste aller Gruppen abzurufen, muss deine App eine HTTP GET-Anforderung an die UserManagement-App senden.

Request


GET /usermanagement/group
Accept: application/json

Response

Die Antwort enthält eine Liste von Gruppenobjekten. Die Gruppenobjekte enthalten auch alle Mitglieder der Gruppen.


{
    "groups": [
        {
            "id" : "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
            "name" : "sales staff",
            "infoText" : "This is the group with all sales employees",
            "members" : [ 
                  {
                    "_links": {
                        "self": {
                            "href": "/usermanagement/user/DF288708-FE65-492C-AD4E-7D747909CB28"
                        }
                    },
                    "type": "user",
                    "id": "DF288708-FE65-492C-AD4E-7D747909CB28"
                },
                ...
             ],
            "_links": {
                "self": {
                    "href": "/usermanagement/group/11A5C79F-D9AB-498B-9158-D3034B7E45E5"
                }
            }
        }
    ]
}

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.

 Erstellen von Gruppen

Um eine Gruppe zu erstellen, muss deine App eine HTTP POST-Anforderung an die UserManagement-App senden. Hierbei wird ein vollständiges Gruppenobjekt im Body mitgegeben.


{
    "id" : "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "name" : "sales staff",
    "infoText" : "This is the group with all sales employees",
    "members" : [ 
        {
            "type": "user",
            "id": "DF288708-FE65-492C-AD4E-7D747909CB28"
        }
        ...
     ]
}

Request


POST /usermanagement/group

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
201CreatedDie Anfrage wurde erfolgreich verarbeitet. Im Location-Header findest du die relative URL zur Ressource der neuen Gruppe.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters nicht gültig.
403ForbiddenDie Gruppe darf nicht erstellt werden. Ein Grund hierfür könnte sein, dass ein reservierter Benutzer als Member angegeben wurde.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

 Abrufen einer Gruppe

Um eine Gruppe abzurufen, muss deine App eine HTTP GET-Anforderung an die UserManagement-App senden.

Request


GET /usermanagement/group/{id}
Accept: application/json

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID der Gruppe, die abgerufen werden soll

Response

Die Antwort enthält ein Gruppenobjekt.


{
    "id" : "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "name" : "sales staff",
    "infoText" : "This is the group with all sales employees",
    "members" : [ 
                  {
                    "_links": {
                        "self": {
                            "href": "/usermanagement/user/DF288708-FE65-492C-AD4E-7D747909CB28"
                        }
                    },
                    "type": "user",
                    "id": "DF288708-FE65-492C-AD4E-7D747909CB28"
                },
                ...
             ],
     "_links": {
        "self": {
            "href": "/usermanagement/group/11A5C79F-D9AB-498B-9158-D3034B7E45E5"
        }
    }
}

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie angegebene ID war ungültig.
404Not FoundDie Gruppe wurde nicht gefunden.

 Ändern einer Gruppe

Um eine Gruppe zu ändern, muss deine App eine HTTP PUT-Anforderung an die UserManagement-App senden.

Request


PUT /usermanagement/group/{id}
Accept: application/json

Hierbei wird ein vollständiges Gruppenobjekt im Body mitgegeben.


{
    "name" : "sales staff",
    "infoText" : "This is the group with all sales employees",
    "members" : [ 
        {
            "type": "user",
            "id": "DF288708-FE65-492C-AD4E-7D747909CB28"
        }
        ...
     ]
}

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID der Gruppe, die geändert werden soll

Im Body wird ein Gruppenobjekt übergeben. Alle Werte dieses Objekts werden übernommen.

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters nicht gültig.
403ForbiddenDie Gruppe darf nicht geändert werden. Ein Grund hierfür könnte sein, dass ein reservierter Benutzer als Member angegeben wurde.
404Not FoundDie Gruppe wurde nicht gefunden.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

Hinweis

Info: Die Mitglieder der Gruppe werden durch die Mitglieder der Gruppe ersetzt, die in der Anforderung zum Ändern der Gruppe angegeben hast. Die vorherigen Mitglieder gehen verloren. Um nur die Mitglieder der Gruppe zu ändern, verwende die Funktionen zum Hinzufügen und Löschen von Gruppenmitgliedern.

 Löschen einer Gruppe

Um eine Gruppe zu löschen, muss deine App eine HTTP DELETE-Anforderung an die UserManagement-App senden.

Request


DELETE /usermanagement/group/{id}
Accept: application/json

Hinweise zu den Parametern

ParameterBeschreibung
idDie ID der Gruppe, die gelöscht werden soll

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters nicht gültig.
403ForbiddenDie Gruppe darf nicht gelöscht werden.
404Not FoundDie Gruppe wurde nicht gefunden.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

 Hinzufügen eines Gruppenmitglieds

Um ein Gruppenmitglied hinzuzufügen, muss deine App eine HTTP PUT-Anforderung an die UserManagement-App senden. Hierbei wird ein vollständiges Benutzerobjekt im Body mitgegeben. Request


PUT /usermanagement/group/{groupId}/member/{userId}
Accept: application/json

Hinweise zu den Parametern

ParameterBeschreibung
groupIdDie ID der Gruppe, zu der ein Mitglied hinzugefügt werden soll
userIdDie ID des Benutzers, der als Mitglied zu der Gruppe hinzugefügt werden soll

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters ungültig oder der Benutzer ist bereits Mitglied der Gruppe.
403ForbiddenDie Gruppe oder der Benutzer darf nicht geändert werden.
404Not FoundDie Gruppe oder der Benutzer wurde nicht gefunden.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

 Entfernen eines Gruppenmitglieds

Um ein Gruppenmitglied zu entfernen, muss deine App eine HTTP DELETE-Anforderung an die UserManagement-App senden.

Request


DELETE /usermanagement/group/{groupId}/member/{userId}
Accept: application/json

Hinweise zu den Parametern

ParameterBeschreibung
groupIdDie ID der Gruppe, aus der ein Mitglied entfernt werden soll
userIdDie ID des Benutzers, der aus der Gruppe entfernt werden soll

Response Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert eines Parameters ungültig.
403ForbiddenDie Gruppe oder der Benutzer darf nicht geändert werden.
404Not FoundDie Gruppe wurde nicht gefunden.
429Too Many RequestsDer Server wurde durch zu viele Anfragen von diesem Mandanten überlastet und konnte diese Anfrage daher nicht in gegebener Zeit bearbeiten.

Hinweis

Info: Wenn du als Antwort einen "Bad Request"-Statuscode erhältst, kann es sein, dass der Benutzer nicht gelöscht werden darf, da er der letzte Benutzer in der administrativen Gruppe des Mandanten ist. Der letzte Benutzer kann nicht gelöscht werden, da ansonsten kein Zugriff mehr auf die Cloud-Instanz möglich wäre.