Skip to content

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](https://www.base64encode.org/) 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:

    ``` java
    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
Sample Response
Sample response: JSON

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
Sample Request
Request: JSON
Sample Response
Response: JSON

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
A sample response
Response: JSON

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
A sample response
Response: Boolean

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
A sample response
Response: JSON

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
}
Top