Entitlement with REST APIs

Entitlement management is the process that grants, resolves, enforces, revokes and administers fine-grained access privileges. The WSO2 Identity Server supports REST APIs for entitlement management via the https://{IS_IP}:{IS_PORT}/api/identity/entitlement/decision/ endpoint

If your WSO2 Identity Server is running on localhost (127.0.0.1) and on the default port (without offset), the entitlement endpoint is as follows:
Endpoint
```
https://localhost:9443/api/identity/entitlement/decision/
```

Note: The REST APIs are secured with basic authentication. Follow the steps below to add a basic auth header when calling these methods.

1. Build a string of the form username:password.
2. Encode the string you created above using Base64.
3. Define an authorization header with the term "Basic ", followed by the encoded string. For example, the basic auth authorization header using "admin" as both username and password (admin:admin) is as follows:
```
Authorization: Basic YWRtaW46YWRtaW4=
```

Get API resource list

Description

Get the API resource list according to XACML 3.0 specification.

Resource Path

/home

HTTP Method

GET

Request/Response Format

application/json

application/xml

Authentication

Basic

Username

admin

Password

admin

Parameters

Name	Located In	Description	Required	Schema
Accept	header	Request Media Type	Yes	string
Auth_Type	header	Authentication Type	Yes	string
Authorization	header	Add HTTP Basic Authorization	Yes	string
Content-type	header	Response Media Type	Yes	string

Response

Code	Description	Schema
200	XACML JSON/XML Response
40010	Error in response	ExceptionBean { code:integer message:string }
40020	Request parse exception	ExceptionBean { code:integer message:string }

A sample request and response is as follows:

Sample request

GET Request: Curl

curl -X GET   https://localhost:9443/api/identity/entitlement/decision/home   -H 'accept: application/json'   -H 'authorization: Basic YWRtaW46YWRtaW4='   -H 'cache-control: no-cache'   -H 'content-type: application/json'   -H 'postman-token: e83be84b-61fa-f608-4e22-c22b0812cc8c'  -k

Sample Response

Sample response: JSON

{
    "xmlns": "http://ietf.org/ns/home-documents",
    "resources": [
        {
            "link": {
                "href": "/pdp"
            },
            "rel": "http://docs.oasis-open.org/ns/xacml/relation/pdp"
        }
    ]
}

Evaluate XACML request

Description

Get a response by evaluating the JSON/XML XACML request.

Resource Path

/pdp

HTTP Method

POST

Request/Response Format

application/json

application/xml

Authentication

Basic

Username

admin

Password

admin

Parameters

Name	Located In	Description	Required	Schema
Accept	header	Request Media Type	Yes	string
Auth_Type	header	Authentication Type	Yes	string
Authorization	header	Add HTTP Basic Authorization	Yes	string
Content-type	header	Response Media Type	Yes	string
body	body	XACML JSON/XML Request	Yes	string

Response

Code	Description	Schema
200	XACML JSON/XML Response
40010	Error in response	ExceptionBean { code:integer message:string }
40020	Request parse exception	ExceptionBean { code:integer message:string }

A sample request and response is as follows:

XACML Policy Evaluated

XACML Policy

<Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicyId="samplePolicy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:3.0:rule-combining-algorithm:deny-overrides" Version="1.0">
	<Target>
		<AnyOf>
			<AllOf>
				<Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
					<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">read</AttributeValue>
					<AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
				</Match>
			</AllOf>
		</AnyOf>
	</Target>
	<Rule Effect="Permit" RuleId="permit"/>
</Policy>

Sample Request

Request: JSON

{
    "Request": {
             "AccessSubject": {
                     "Attribute": [
                           {
                                  "AttributeId": "urn:oasis:names:tc:xacml:1.0:subject:subject-id",
                                  "Value": "Andreas"
                           }
           ]
              },        "Action": {
            "Attribute": [
                {
                    "AttributeId": "urn:oasis:names:tc:xacml:1.0:action:action-id",
                    "Value": "read"
                }
            ]
        },
        "Resource": {
            "Attribute": [
                {
                    "AttributeId": "urn:oasis:names:tc:xacml:1.0:resource:resource-id",
                    "Value": "http://127.0.0.1/service/very_secure/"
                }
            ]
        }
    }
}

Sample Response

Response: JSON

{
  "Response": [
    {
      "Decision": "Permit",
      "Status": {
        "StatusCode": {
          "Value": "urn:oasis:names:tc:xacml:1.0:status:ok"
        }
      }
    }
  ]
}

Evaluate XACML request by attributes

Description Get a response by evaluating attributes.

Resource Path /by-attrib

HTTP Method POST

Request/Response Format

application/json

application/xml

Authentication Basic

Username admin

Password admin

Parameters

Name	Located In	Description	Required	Schema
Accept	header	Request Media Type	Yes	string
Auth_Type	header	Authentication Type	Yes	string
Authorization	header	Add HTTP Basic Authorization	Yes	string
Content-type	header	Response Media Type	Yes	string
body	bosy	Decision Request Model	Yes	DecisionRequestModel { subject:string action:string resource:string environment:[ string ] }

Response

Code	Description	Schema
200	Method call success	`HomeResponseModel { }`
40010	Error in response	ExceptionBean { code:integer message:string }
40020	Request parse exception	ExceptionBean { code:integer message:string }

A sample request and response are as follows,

A sample request

Request: Curl

curl --request POST \
  --url https://localhost:9443/api/identity/entitlement/decision/by-attrib \
  --header 'accept: application/json' \
  --header 'authorization: Basic YWRtaW46YWRtaW4=' \
  --header 'content-type: application/json' \
  --data '{
  "action":"read",
  "resource":"http://127.0.0.1/service/very_secure/",
  "subject" : "admin"
}' -k

A sample response

Response: JSON

{
  "Response": [
    {
      "Decision": "Permit",
      "Status": {
        "StatusCode": {
          "Value": "urn:oasis:names:tc:xacml:1.0:status:ok"
        }
      }
    }
  ]
}

Evaluate XACML request by attributes and receive boolean response

Description

Get a boolean response by evaluating attributes.

Resource Path

/by-attrib-boolean

HTTP Method

POST

Request/Response Format

application/json

application/xml

Authentication

Basic

Username

admin

Password

admin

Parameters

Name	Located In	Description	Required	Schema
Accept	header	Request Media Type	Yes	string
Auth_Type	header	Authentication Type	Yes	string
Authorization	header	Add HTTP Basic Authorization	Yes	string
Content-type	header	Response Media Type	Yes	string
body	body	Decision Request Model	Yes	DecisionRequestModel { subject:string action:string resource:string environment:[ string ] }

Response

Code	Description	Schema
200	XACML JSON/XML Response
40010	Error in response	ExceptionBean { code:integer message:string }
40020	Request parse exception	ExceptionBean { code:integer message:string }

A sample request and response are as follows,

A sample request

Request: Curl

curl --request POST \
  --url https://localhost:9443/api/identity/entitlement/decision/by-attrib-boolean \
  --header 'accept: application/json' \
  --header 'authorization: Basic YWRtaW46YWRtaW4=' \
  --header 'content-type: application/json' \
  --data '{
  "action":"read",
  "resource":"http://127.0.0.1/service/very_secure/",
  "subject" : "admin"
}' -k

A sample response

Response: Boolean

true

Get entitled attributes

Description

Get entitled attributes for a given set of parameters.

Resource Path

/entitled-attribs

HTTP Method

POST

Request/Response Format

application/json

application/xml

Authentication

Basic

Username

admin

Password

admin

Parameters

Name	Located In	Description	Required	Schema
Accept	header	Request Media Type	Yes	string
Auth_Type	header	Authentication Type	Yes	string
Authorization	header	Add HTTP Basic Authorization	Yes	string
Content-type	header	Response Media Type	Yes	string
body	body	Decision Request Model	Yes	EntitledAttributesRequestModel { subjectName:string resourceName:string subjectId:string action:string enableChildSearch:boolean }

Response

Code

Description

Schema

200

Entitled attributes response

EntitledAttributesResponseModel {
	entitledResultSetDTO:EntitledResultSetDTO {
		entitledAttributesDTOs:[
			EntitledAttributesDTO {
				resourceName:string
				action:string
				environment:string
				allActions:boolean
				allResources:boolean
				attributeDTOs:[
					AttributeDTO {
						attributeValue:string
						attributeDataType:string
						attributeId:string
						category:string
					}
				]
			}
		]
		advanceResult:boolean
		message:string
		messageType:string
	}
}

40010

Error in response

ExceptionBean {
	code:integer
	message:string
}

40020

Request parse exception

ExceptionBean {
	code:integer
	message:string
}

A sample request and response are as follows,

A sample request

Request: Curl

curl --request POST \
  --url https://localhost:9443/api/identity/entitlement/decision/entitled-attribs \
  --header 'accept: application/json' \
  --header 'authorization: Basic YWRtaW46YWRtaW4=' \
  --header 'content-type: application/json' \
  --data '{
  "subjectName" : "admin",
  "enableChildSearch" : "false"
}' -k

A sample response

Response: JSON

{
   "entitledResultSetDTO": {
      "entitledAttributesDTOs": [
         {
            "resourceName": null,
            "action": "read",
            "environment": null,
            "allActions": false,
            "allResources": true,
            "attributeDTOs": []
         }
      ],
      "advanceResult": false,
      "message": null,
      "messageType": null
   }
}

Get all entitlements

Description

Get all entitlements for a given set of parameters

Resource Path

/entitlements-all

HTTP Method

POST

Request/Response Format

application/json

application/xml

Authentication

Basic

Username

admin

Password

admin

Parameters

Name	Located In	Description	Required	Schema
Accept	header	Request Media Type	Yes	string
Auth_Type	header	Authentication Type	Yes	string
Authorization	header	Add HTTP Basic Authorization	Yes	string
Content-type	header	Response Media Type	Yes	string
body	body	All Entitlements Model	Yes	AllEntitlementsRequestModel { identifier:string givenAttributes:[ AttributeDTO { attributeValue:string attributeDataType:string attributeId:string category:string } ] }

Response

Code

Description

Schema

200

All entitlements response

AllEntitlementsResponseModel {
	entitledResultSetDTO:EntitledResultSetDTO {
		entitledAttributesDTOs:[
			EntitledAttributesDTO {
				resourceName:string
				action:string
				environment:string
				allActions:boolean
				allResources:boolean
				attributeDTOs:[
					AttributeDTO {
						attributeValue:string
						attributeDataType:string
						attributeId:string
						category:string
					}
				]
			}
		]
		advanceResult:boolean
		message:string
		messageType:string
	}
}

40010

Error in response

ExceptionBean {
	code:integer
	message:string
}

40020

Request parse exception

ExceptionBean {
	code:integer
	message:string
}