Policies
This guide will walk you though the process of assigning, listing and removing policies and also give you a better understanding about policy definition.
Policy represents rights which are assigned by an organization or person to another person. The policies delegation can concern subject which can be an organisation (called here group) or another user represented by a principal (a person in Onegini IdP). Please consider following examples to get better understanding of a policy concept:
Acme (subject - group) represented by Harry (principal - person) allows Lisa (assignee - person) to read financial reports.
Lisa (subject - person) represented by Lisa (principal - person) allows John (assignee - person) to read last financial report.
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
For the sake of this guide we assume that the DUM Engine is available at http://localhost:8080.
Add a policy
To add a policy you need to execute an API call POST api/v1/policies
to DUM Engine endpoint.
This endpoint is meant to be used when a new policy without relation to any other already defined is intended to be created.
curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json" -X POST -d
'{
"name" : "Organisation policy",
"principal" : {
"idp_type" : "LDAP",
"principalId" : "146a47f0-31be-145d-aaef-900abc3753e1"
},
"scopes" : ["READ"],
"subjectId" : "f530f30d-8322-47d1-93ff-19f4fea37c79",
"assigneeId" : "146a47f0-31be-145d-aaef-900abc3753e1"
}'
http://localhost:8080/api/v1/policies
The service responds with HTTP/1.1 201 Created
status code and a Policy representation for operation completed successfully.
Example response
HTTP/1.1 201
Content-Type: application/json;charset=UTF-8
{
"id" : "79db83a6-bb3f-493a-b614-e86a404c2142",
"name" : "Organisation policy",
"principal" : {
"idp_type" : "LDAP",
"principalId" : "146a47f0-31be-145d-aaef-900abc3753e1"
},
"scopes" : ["READ"],
"subjectId" : "f530f30d-8322-47d1-93ff-19f4fea37c79",
"assigneeId" : "146a47f0-31be-145d-aaef-900abc3753e1"
}
To get more information about the endpoint signature please look into the Add new policy documentation.
Remove a policy
To remove a policy you need to execute an API call to DELETE api/v1/policies/{policyId}
DUM Engine endpoint.
curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X DELETE http://localhost:8080/api/v1/policies/0d31a0fa-ac44-45e9-affd-92edf4b1b5b4
The service responds with HTTP/1.1 204 No Content
for operation completed successfully.
To get more information about the endpoint signature please look into the Delete policy documentation.
Assign a policy to a person
To assign a policy to a person you need to execute an API call to POST api/v1/persons/{personId}/policies
DUM Engine endpoint.
curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X POST -d
'{
"principal": {
"idp_type": "LDAP",
"principal_id": "146a47f0-31be-145d-aaef-900abc3753e1"
},
"parent_policy_id": "13db83a6-bb3f-493a-b614-e86a404c2142"
}'
http://localhost:8080/api/v1/persons/f530f30d-8322-47d1-93ff-19f4fea37c79/policies
To get more information about the endpoint signature please look into the Add new child policy documentation.
Assign a policy to a group
To assign a policy to a group you need to execute an API call to POST api/v1/groups/{groupId}/policies
DUM Engine endpoint.
curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X POST -d
'{
"principal": {
"idp_type": "LDAP",
"principal_id": "146a47f0-31be-145d-aaef-900abc3753e1"
},
"parent_policy_id": "13db83a6-bb3f-493a-b614-e86a404c2142"
}'
http://localhost:8080/api/v1/groups/f530f30d-8322-47d1-93ff-19f4fea37c79/policies
To get more information about the endpoint signature please look into the Add new child policy documentation.
Batch update group policies
Batch operation allows you to combine multiple API operations in a single request which may be especially important for end application performance.
One of the batch operations supported by the DUM Engine is group policies update. This method is meant to limit the number of API calls which are sent to the DUM Engine and increase the end-application performance and usability. It's specifically useful when you want to create or remove multiple policies within a context of a given group.
To perform batch group policies update you need to execute an API call POST api/v1/groups/{groupId}/policies/batch
to DUM Engine's endpoint.
curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X POST -d
'{
"create": [
{
"principal": {
"idp_type": "ldap",
"principal_id": "principal-1"
},
"scopes": [
"e6839ae2-c40f-4870-aaab-ba38c05deba0"
],
"subject": {
"type": "GROUP",
"subject_id": "8776d79f-6c73-4d98-ac71-c3bf7ac7841a"
},
"assignee_id": "person-2"
},
{
"principal": {
"idp_type": "ldap",
"principal_id": "principal-1"
},
"scopes": [
"fc938fd7-efbd-44ce-a954-6ad1908f09f5"
],
"subject": {
"type": "PERSON",
"subject_id": "8776d79f-6c73-4d98-ac71-c3bf7ac7841a"
},
"assignee_id": "person-2"
}
],
"delete": [
"927be067-a0b0-43c7-abc7-f4bb3766310c",
"a3bbb8ab-671b-4e87-bb6a-fbe81415fa5b"
]
}'
http://localhost:8080/api/v1/groups/160d8767-b7ea-4706-9738-4dc221658868/policies/batch
The request body can consist of two collections, first create
represents the policies which are meant to be created and assigned to group with identifier specified within the
request path. Second delete
represents a list of policies identifiers which are meant to be removed.
Example response:
HTTP/1.1 200