Person permissions

The DUM Engine allows assigning various permissions to application's end-users. This guide will walk you though the process of assigning, listing and removing permissions and also give you a better understanding about supported permission types.

A permission is an authorization for performing a specific operation on the DUM Engine's REST APIs. Permissions within DUM Engine can be assigned by a person to another person. Please have a look at assigning permission chapter to learn more.

To verify person permission(s) following headers must be added to every REST API call which is executed against DUM Engine:

  • Dum-Person-Id - identifier of the person
  • Dum-Idp-Type - identity provider type

Permissions allows you to keep state of the application consistent by ensuring the person who is performing the action (identified by the Dum-Person-Id and the Dum-Idp-Type headers) is authorized to perform it. Still, it's an optional feature and you are not forced to use it. Validation is executed only if above headers are provided.

For example company Acme allows John to only manage policies by assigning POLICY_MANAGE permission. John is now allowed to access only a subset of the DUM Engine APIs if Dum-Person-Id and Dum-Idp-Type are set and they are pointing to John account.

Supported permissions

Below all the supported permissions are listed with corresponding operations.

Permission Allowed operations
GROUP_MANAGE create, update and remove a group
SCOPE_MANAGE create, update and remove a scope
PERSON_​POLICY_​MANAGE assign policy to a person
GROUP_POLICY_MANAGE assign policy to a group
GROUP_MEMBER_MANAGE add and remove a user to/from a group
PERMISSION_MANAGE assign and unassign permission from a user
POLICY_MANAGE add and remove a policy

What you need

To successfully complete this topic guide you need to ensure following prerequisites:

  • have the DUM Engine application up and running
  • have access to DUM Engine APIs and know the Basic Authentication credentials
  • know the identifier of the person to whom you want to assign the permission, the identifier may come from Onegini's CIM application or external Identity Provider (in this case identity provider type is also needed)
  • know the identifier of the group to which you want to assign the permission

For the sake of this guide we assume that the DUM Engine is available at http://localhost:8080.

Assign permission to a person

To assign permission you need to execute an API call POST api/v1/permissions to DUM Engine endpoint.

curl -i --user username:password 
-H "Content-Type: application/json" 
-H "Accept: application/json" 
-X POST -d 

'{
     "permission": "GROUP_MANAGE",
     "group_id": "e5cfcdd3-f4df-4dc8-b5fd-7cdba345832c",
     "person": {
         "idp_type": "ldap",
         "person_id": "person-id-1"
     }
 }' 

http://localhost:8080/api/v1/persons/person-id-1/permissions

The service responds with HTTP/1.1 201 Created status code and a Permission representation for operation completed successfully.

Example response:

HTTP/1.1 201
Content-Type: application/json;charset=UTF-8

{
    "id": "a2c0bde9-2325-437b-8f8a-77196a9084a2",
    "personId": "person-id-1",
    "permission": "GROUP_MANAGE"
}

To get more information about the endpoint signature please look into the API documentation.

List person permissions

DUM Engine provides two endpoints to get list of person permissions.

To list permissions of Onegini IDP users you need to execute an API call to GET api/v1/persons/{personId}/permissions DUM Engine endpoint. To do the same for custom idp execute an API call to GET api/v1/persons/{idpType}:{personId}/permissions. Both endpoints returns the same response.

curl -i --user username:password
-H "Content-Type: application/json" 
-H "Accept: application/json" 
-X GET http://localhost:8080/api/v1/persons/person-id-1/permissions

The service responds with HTTP/1.1 200 Ok status code and a list of person's permissions for operation completed successfully.

Example response:

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

[
    {
     "id": "a2c0bde9-2325-437b-8f8a-77196a9084a2",
     "person": {
             "idp_type": "CIM",
             "person_id": "person-id-1"
         },
     "permission": "ALL"
    }
]

To get more information about the endpoint signature please look into the Onegini IDP and custom IDP API documentation.

Remove person permission

In order to remove assigned permission first you need to know it's identifier. The identifier can be retrieved either during permission assignment or by listing person's permissions. To remove permission you need to execute an API call to DELETE api/v1/permissions/{permissionId} DUM Engine endpoint.

curl -i --user username:password
-H "Content-Type: application/json" 
-H "Accept: application/json" 
-X DELETE http://localhost:8080/api/v1/permissions/a2c0bde9-2325-437b-8f8a-77196a9084a2

The service responds with HTTP/1.1 200 Ok status code and a list of person's permissions for operation completed successfully.

To get more information about the endpoint signature please look into the API documentation.

Update permissions in batch

Batch operation allows you to combine multiple API operations in a single request which may be especially important for end application performance.

To limit requests to create or delete permissions it is possible to do it in one request by executing an API call to POST api/v1/groups/{groupId}/persons/{idpType}/{personId}/permissions/batch. The endpoint allows to update permissions for a person in a context of a group.

curl -i --user username:password 
-H "Content-Type: application/json" 
-H "Accept: application/json" 

'{
     "create": [
         "GROUP_MANAGE"
     ],
     "delete": [
         "SCOPE_MANAGE"
     ]
 }'

-X POST http://localhost:8080/api/v1/groups/group-id-1/persons/ldap/person-id-1/permissions/batch

The service responds with HTTP/1.1 200 Ok status code and a list of person's permissions for operation completed successfully.

Example response:

HTTP/1.1 200 
Content-Type: application/json;charset=UTF-8

{
    "content": [
        {
            "id": "4b3be347-608b-4a6e-91ef-840800445d01",
            "group_id": "group-id-1",
            "person": {
                "idp_type": "ldap",
                "person_id": "person-id-1"
            },
            "permission": "POLICY_MANAGE"
        },
        {
            "id": "b0e5b817-ce34-40ca-a3dc-42ba8ea58f4d",
            "group_id": "group-id-1",
            "person": {
                "idp_type": "ldap",
                "person_id": "person-id-1"
            },
            "permission": "GROUP_MANAGE"
        }
    ],
    "total_results": 2,
    "offset": 0,
    "page_size": 20
}

Please note that the actual response is wrapped by paging object. You can control the pagination by specifying additional query params which are following org.springframework.data.domain.PageRequest object definition, ex. offset, sort, page and size.

To get more information about the endpoint signature please look into the API documentation.