Scope of functions of the usermanagement app

The usermanagement app lets you manage users and groups. In d.velop cloud, you can also assign administrative rights using the app. You can query and change users and group memberships using a REST API.

For all listed API functions, authentication must be done via bearer token. For more information, see the Authenticating an app with requests outside the user context chapter of the IdentityProvider app API documentation.

Using the API functions

Below, you can learn how to use the programming interface of the usermanagement app. In addition to the classic interface (deprecated), there is an interface according to SCIM 2.0 (RFC 7643).

SCIM 2.0 interface

Using the SCIM 2.0 interface you can manage users and groups or read out information about users and groups. For more information on using the SCIM interface, as well as examples, please refer to the corresponding documentation for RFC 7643.

SCIM base path

/usermanagement/scim

Limitations/special features of the SCIM 2.0 implementation

The base URI for the SCIM interface is <SystembaseUri>/Usermanagement/scim.
In addition to authentication using an IDP API key as a bearer token, a d.ecs identityprovider AuthSessionId can also be passed.
Access is only granted to users who have administrator rights or are members of the SCIM_GROUP.
The user interface shows only a few of the available SCIM attributes, nevertheless these are transmitted to d.ecs identityprovider and are available there.
Supported are HTTP GET, POST, PUT, PATCH and DELETE on the user as well as group resource. For the search the filters "eq" (equality), "sw" (Starts with) and "co" (Contains) filters are supported, logical operators are not supported.
The following user attributes are currently supported:

• Id
• ExternalId
• UserName
• DisplayName
• Name (with FamilyName, GivenName, Formatted, MiddleName, HonorificPrefix, HonorificSuffix)
• Title
• Locale
• PreferredLanguage
• Timezone
• Emails
• Active
• PhoneNumbers (only one of type "work")
• SCIM2.0 Enterprise User Extension

Some attributes are subject to length restrictions, FamilyName and GivenName are limited to 100 characters each, the length of the primary email address is limited to 1000 characters. If there is no primary email address, the first email address is also limited to 1000 characters.
User image information cannot be processed through the interface at this time.

Managing users using the classic interface (deprecated)

The usermanagement app lets you manage individual users, user images and groups.

Retrieving the user list

To retrieve a list of all the users, your app must send an HTTP GET request to the usermanagement app.

Request

GET /usermanagement/user
Accept: application/json

Response The response contains a JSON object with a list of user objects.

{
    "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"
                }
            }
        },
        ...
    ]
}

The following HTTP status codes can be returned:

Creating a user

To create a user, your app must send an HTTP POST request to the usermanagement app.

A complete user object is included in the body in this case.

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

Request

POST /usermanagement/user

Response

The following HTTP status codes can be returned:

Retrieving users

To retrieve a user, your app must send an HTTP GET request to the usermanagement app.

Request

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

Notes on the parameters

Response

The response contains a JSON object with a user object.

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

The following HTTP status codes can be returned:

Changing a user

To change a user, your app must send an HTTP PUT request to the usermanagement app. A complete user object is included in the body in this case. All the values from this body are transferred.

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

Request

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

Notes on the parameters

Response The following HTTP status codes can be returned:

Deleting a user

To delete a user, your app must send an HTTP DELETE request to the usermanagement app.

Request

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

Notes on the parameters

Response

The following HTTP status codes can be returned:

info: If you receive a "Bad Request" status code as the response, it may be that you are not allowed to delete the user because the user is the last user in the administrative group of the tenant. The last user cannot be deleted because it would otherwise no longer be possible to access the cloud instance.

Retrieving a user image

To retrieve a user image, your app must send an HTTP GET request to the usermanagement app.

Request

GET /usermanagement/picture/{id}

Notes on the parameters

Response The response contains the image of the specified user.

The following HTTP status codes can be returned:

Changing the user image

To change the image of a user, your app must send an HTTP PUT request to the usermanagement app. The image must be sent as part of a MultiPart request, using uploadedData as the name.

Request

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

The body of the request must contain the following Content-Disposition entry.

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

Notes on the parameters

Response The following HTTP status codes can be returned:

Deleting a user image

To delete the image of a user, your app must send an HTTP DELETE request to the usermanagement app.

Request

DELETE /usermanagement/picture/{userId}

Notes on the parameters

Response The following HTTP status codes can be returned:

Managing groups

The usermanagement app lets you manage groups and individual group members.

Only users are supported as group members. Via the user interface, a group can also be changed to a global group (groups in groups), but this group can then no longer be changed via the API.

Special IDs

The administrative group of the tenant has the fixed ID '6DB690CB-EA1B-4D45-B00B-63A2E7B21816'. If a user is member this group, the user automatically receives administrative rights in the relevant cloud instance.

Retrieving the group list

To retrieve a list of all the groups, your app must send an HTTP GET request to the usermanagement app.

Request

GET /usermanagement/group
Accept: application/json

Response

The response contains a list of group objects. The group objects also contain all the members of the groups.

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

The following HTTP status codes can be returned:

Creating groups

To create a group, your app must send an HTTP POST request to the usermanagement app. A complete group object is included in the body in this case.

{
    "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 The following HTTP status codes can be returned:

Retrieving a group

To retrieve a group, your app must send an HTTP GET request to the usermanagement app.

Request

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

Notes on the parameters

Response

The response contains a group object.

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

The following HTTP status codes can be returned:

Changing a group

To change a group, your app must send an HTTP PUT request to the usermanagement app.

Request

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

A complete group object is included in the body in this case.

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

Notes on the parameters

A group object is transferred in the body. All the values of this object are transferred.

Response The following HTTP status codes can be returned:

info: The members of the group are replaced by the group members that you specified in the request to change the group. The previous members are lost. To change only the members of the group, use the functions for adding and deleting group members.

Deleting a group

To delete a group, your app must send an HTTP DELETE request to the usermanagement app.

Request

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

Notes on the parameters

Response The following HTTP status codes can be returned:

Adding a group member

To add a group member, your app must send an HTTP PUT request to the usermanagement app. Only individual users can be added as group members via the API. Global groups (groups within groups) can only be changed via the user interface.

Request

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

Notes on the parameters

Response The following HTTP status codes can be returned:

Removing a group member

To remove a group member, your app must send an HTTP DELETE request to the usermanagement app. Only individual users can be removed as group members via the API. Global groups (groups within groups) can only be changed via the user interface.

Request

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

Notes on the parameters

Response The following HTTP status codes can be returned:

info: If you receive a "Bad Request" status code as the response, it may be that you are not allowed to delete the user because the user is the last user in the administrative group of the tenant. The last user cannot be deleted because it would otherwise no longer be possible to access the cloud instance.