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.

SCIM Basispfad

/usermanagement/scim

 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, Benutzerbilder und Gruppen 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:

 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:

 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

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:

 Ä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

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

 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

Response

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

 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

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

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

 Ä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

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

 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

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

 Verwalten von Gruppen

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

Als Gruppenmitglieder werden nur Benutzer unterstützt. Über die Benutzeroberfläche kann eine Gruppe auch zu einer globalen Gruppe (Gruppen in Gruppen) geändert werden, jedoch kann diese Gruppe ab diesem Zeitpunkt dann nicht mehr über die API verändert werden.

Besondere IDs

Die administrative Gruppe des Mandanten hat die feste ID '6DB690CB-EA1B-4D45-B00B-63A2E7B21816'. Wenn ein Benutzer Mitglied 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",
            "isGlobalGroup": true
            "members" : [ 
                  {
                    "_links": {
                        "self": {
                            "href": "/usermanagement/user/DF288708-FE65-492C-AD4E-7D747909CB28"
                        }
                    },
                    "type": "user",
                    "id": "DF288708-FE65-492C-AD4E-7D747909CB28"
                },
                {
                    "_links": {
                        "self": {
                            "href": "/usermanagement/group/DFE35E07-4E6D-4B92-ADB5-AD3FE501A0F8"
                        }
                    },
                    "type": "group",
                    "id": "DFE35E07-4E6D-4B92-ADB5-AD3FE501A0F8"
                },
                ...
             ],
            "_links": {
                "self": {
                    "href": "/usermanagement/group/11A5C79F-D9AB-498B-9158-D3034B7E45E5"
                }
            }
        }
    ]
}

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

 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:

 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

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:

 Ä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

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

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

 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

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

 Hinzufügen eines Gruppenmitglieds

Um ein Gruppenmitglied hinzuzufügen, muss deine App eine HTTP PUT-Anforderung an die UserManagement-App senden. Über die API können lediglich einzelne Benutzer als Gruppenmitglied hinzugefügt werden. Globale Gruppen (Gruppen in Gruppen) können nur über die Benutzeroberfläche verändert werden.

Request

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

Hinweise zu den Parametern

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

 Entfernen eines Gruppenmitglieds

Um ein Gruppenmitglied zu entfernen, muss deine App eine HTTP DELETE-Anforderung an die UserManagement-App senden. Über die API können lediglich einzelne Benutzer als Gruppenmitglied entfernt werden. Globale Gruppen (Gruppen in Gruppen) können nur über die Benutzeroberfläche verändert werden.

Request

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

Hinweise zu den Parametern

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