User management app

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

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:

Status code	Name	Meaning
200	OK	The request was processed successfully.

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:

Status code	Name	Meaning
201	Created	The request was processed successfully. You can find the relative URL for the resource of the new user in the location header.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid.
401	Unauthorized	Invalid bearer token or no bearer token specified.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
id	The ID of the user to be retrieved

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:

Status code	Name	Meaning
200	OK	The request was processed successfully.
404	Not Found	The specified ID does not exist. No data is transmitted.

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

Parameter	Description
id	The ID of the user to be changed

Response The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The user was changed successfully.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid.
401	Unauthorized	Invalid bearer token or no bearer token specified.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
id	The ID of the user to be deleted

Response

The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The user was deleted successfully.
400	Bad Request	The request could not be processed.
401	Unauthorized	Invalid bearer token or no bearer token specified.
404	Not Found	The user was not found.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
id	The ID of the user whose image is to be retrieved

Response The response contains the image of the specified user.

The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The image was sent successfully.
400	Bad Request	The specified ID was invalid.
415	Unsupported Media Type	A JSON request was sent, which is not supported.

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

Parameter	Description
id	The ID of the image to be changed

Response The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The user picture has been changed successfully.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid.
401	Unauthorized	Invalid bearer token or no bearer token specified.
404	Not Found	The user was not found and the related picture could not be changed.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
userId	The ID of the user whose image is to be deleted

Response The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The image was successfully deleted.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid.
401	Unauthorized	Invalid bearer token or no bearer token specified.
404	Not Found	The user could not be found or the user has not saved an image. The image was not deleted.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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.

Type	Key	Description
User	user	The ID in this element is the ID of a user who is a member of this group.
Group	group	The ID in this element is the ID of a group which is a member of this group.
Group	idpgroup	The ID in this element is the ID of an idp group which is a member of this group. IDP groups are groups which are provided by another provider (e.g. LDAP).

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:

Status code	Name	Meaning
200	OK	The request was processed successfully.

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:

Status code	Name	Meaning
201	Created	The request was processed successfully. You can find the relative URL for the resource of the new group in the location header.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid. Only users can be a member.
401	Unauthorized	Invalid bearer token or no bearer token specified.
403	Forbidden	The group must not be created. One reason for this could be that a reserved user was specified as a member.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
id	The ID of the group to be retrieved

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:

Status code	Name	Meaning
200	OK	The request was processed successfully.
400	Bad Request	The specified ID was invalid.
404	Not Found	The group was not found.

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

Parameter	Description
id	The ID of the group to be changed

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:

Status code	Name	Meaning
200	OK	The request was processed successfully.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid. Only users can be a member.
401	Unauthorized	Invalid bearer token or no bearer token specified.
403	Forbidden	The group must not be modified. One reason for this could be that a reserved user was specified as a member.
404	Not Found	The group was not found.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
id	The ID of the group to be deleted

Response The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The request was processed successfully.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid.
401	Unauthorized	Invalid bearer token or no bearer token specified.
403	Forbidden	The group must not be deleted.
404	Not Found	The group was not found.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
groupId	The ID of the group to which you want to add a member
userId	The ID of the user to be added to the group as a member

Response The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The request was processed successfully.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid or the user may already be a member of the group.
401	Unauthorized	Invalid bearer token or no bearer token specified.
403	Forbidden	The group or the user must not be changed.
404	Not Found	The group or the user was not found.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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

Parameter	Description
groupId	The ID of the group from which you want to remove a member
userId	The ID of the user to be removed from the group

Response The following HTTP status codes can be returned:

Status code	Name	Meaning
200	OK	The request was processed successfully.
400	Bad Request	The request could not be processed. The value of a parameter may be invalid.
401	Unauthorized	Invalid bearer token or no bearer token specified.
403	Forbidden	The group or user must not be changed.
404	Not Found	The group was not found.
429	Too Many Requests	The server was overloaded by too many requests from your client and therefore could not process this request in due time.

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.