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