This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

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

DescriptionGet the API resource list according to XACML 3.0 specification.
Resource Path/home
HTTP MethodGET
Request/Response Formatapplication/json

application/xml

AuthenticationBasic
Usernameadmin
Passwordadmin
Parameters
NameLocated InDescriptionRequiredSchema
AcceptheaderRequest Media TypeYesstring
Auth_TypeheaderAuthentication TypeYesstring
AuthorizationheaderAdd HTTP Basic AuthorizationYesstring
Content-typeheaderResponse Media TypeYesstring
Response
CodeDescriptionSchema
200XACML JSON/XML Response
40010Error in response
ExceptionBean {
	code:integer
	message:string
}
40020Request 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

DescriptionGet a response by evaluating the JSON/XML XACML request.
Resource Path/pdp
HTTP MethodPOST
Request/Response Format

application/json

application/xml

AuthenticationBasic
Usernameadmin
Passwordadmin
Parameters
NameLocated InDescriptionRequiredSchema
AcceptheaderRequest Media TypeYesstring
Auth_TypeheaderAuthentication TypeYesstring
AuthorizationheaderAdd HTTP Basic AuthorizationYesstring
Content-typeheaderResponse Media TypeYesstring
bodybodyXACML JSON/XML RequestYesstring
Response
CodeDescriptionSchema
200XACML JSON/XML Response
40010Error in response
ExceptionBean {
	code:integer
	message:string
}
40020Request 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

DescriptionGet a response by evaluating attributes.
Resource Path/by-attrib
HTTP MethodPOST
Request/Response Formatapplication/json

application/xml

AuthenticationBasic
Usernameadmin
Passwordadmin
Parameters
NameLocated InDescriptionRequiredSchema
AcceptheaderRequest Media TypeYesstring
Auth_TypeheaderAuthentication TypeYesstring
AuthorizationheaderAdd HTTP Basic AuthorizationYesstring
Content-typeheaderResponse Media TypeYesstring
bodybosyDecision Request ModelYes
DecisionRequestModel {
 
	subject:string
	action:string
	resource:string
	environment:[
			string
	]
}
Response
CodeDescriptionSchema
200Method call success HomeResponseModel { }
40010Error in response
ExceptionBean {
	code:integer
	message:string
}
40020Request 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

DescriptionGet a boolean response by evaluating attributes.
Resource Path/by-attrib-boolean
HTTP MethodPOST
Request/Response Format

application/json

application/xml

AuthenticationBasic
Usernameadmin
Passwordadmin
Parameters
NameLocated InDescriptionRequiredSchema
AcceptheaderRequest Media TypeYesstring
Auth_TypeheaderAuthentication TypeYesstring
AuthorizationheaderAdd HTTP Basic AuthorizationYesstring
Content-typeheaderResponse Media TypeYesstring
bodybodyDecision Request ModelYes
DecisionRequestModel {
 
	subject:string
	action:string
	resource:string
	environment:[
			string
	]
}
Response
CodeDescriptionSchema
200XACML JSON/XML Response
40010Error in response
ExceptionBean {
	code:integer
	message:string
}
40020Request 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

DescriptionGet entitled attributes for a given set of parameters.
Resource Path/entitled-attribs
HTTP MethodPOST
Request/Response Format

application/json

application/xml

AuthenticationBasic
Usernameadmin
Passwordadmin
Parameters
NameLocated InDescriptionRequiredSchema
AcceptheaderRequest Media TypeYesstring
Auth_TypeheaderAuthentication TypeYesstring
AuthorizationheaderAdd HTTP Basic AuthorizationYesstring
Content-typeheaderResponse Media TypeYesstring
bodybodyDecision Request ModelYes
EntitledAttributesRequestModel {
	subjectName:string
	resourceName:string
	subjectId:string
	action:string
	enableChildSearch:boolean
}
Response
CodeDescriptionSchema
200Entitled 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
	}
}
40010Error in response
ExceptionBean {
	code:integer
	message:string
}
40020Request 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

DescriptionGet all entitlements for a given set of parameters
Resource Path/entitlements-all
HTTP MethodPOST
Request/Response Format

application/json

application/xml

AuthenticationBasic
Usernameadmin
Passwordadmin
Parameters
NameLocated InDescriptionRequiredSchema
AcceptheaderRequest Media TypeYesstring
Auth_TypeheaderAuthentication TypeYesstring
AuthorizationheaderAdd HTTP Basic AuthorizationYesstring
Content-typeheaderResponse Media TypeYesstring
bodybodyAll Entitlements ModelYes
AllEntitlementsRequestModel {
	identifier:string
	givenAttributes:[
		AttributeDTO {
			attributeValue:string
			attributeDataType:string
			attributeId:string
			category:string
		}
	]
}
Response
CodeDescriptionSchema
200All 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
	}
}
40010Error in response
ExceptionBean {
	code:integer
	message:string
}
40020Request parse exception
ExceptionBean {
	code:integer
	message:string
}