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 personDum-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.