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, the entitlement endpoint is:

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 and encode it using Base64.

2. Define an authorization header with the term Basic, followed by the encoded string. For example, the basic authorization header for admin user with password admin is:

   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 'content-type: application/json' -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 body 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 }