Entitlement with APIs¶
For entitlement management, WSO2 Identity server provides two APIs for Policy Administration and Policy Evaluation.
The following section guides you on invoking the two admin service and describes the operations available in the WSO2 Identity Server Entitlement Mangement APIs.
Before you begin
As admin services are secured to prevent anonymous invocations, you cannot view the WSDL of the admin service by default. Follow the steps below to view and invoke it:
-
Set the
admin_service.wsdlelement totruein<IS_HOME>/repository/conf/deployment.tomlfile.[admin_service.wsdl] enable = true -
Restart the Identity Server.
- If you have started the server in default configurations, use the
following URL in your browser to see the WSDL of the admin service:
eg:
https://localhost:9443/services/EntitlementService?wsdl
For more information on WSO2 admin services and how to invoke an admin service using either SoapUI or any other client program, see Calling Admin Services.
The following section guides you on entitlement management in two different areas,
Policy Administration API¶
Policy administration includes all the actions that should be done to manage a policy. Such as adding and updating policy/policies, publishing policies, removing policies etc. For this, WSO2 Carbon Platform has provided an admin service called EntitlementPolicyAdminService to manage policy administration stuff.
-
You can use the following URL in your browser to see the WSDL of the EntitlementPolicyAdminService admin service.
https://localhost:9443/services/EntitlementPolicyAdminService?wsdlBy using any SoapUI, you can call this admin SOAP service.
Note
All the APIs are secured with basic authentication. Follow the steps below to add a basic auth header when calling these methods.
- Build a string of the form username:password.
- Encode the string you created above using Base64.
- 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 is as follows:
``` java Authorization: Basic YWRtaW46YWRtaW4= ```
Operations included in the EntitlementPolicyAdminService SOAP API¶
The following commonly used operations are available in the EntitlementPolicyAdminService.
addPolicy()¶
getAllPolicyIds()¶
| Description | Retrieve all policy names or policy Ids. |
| Input Parameters | None
|
| Request | |
| Response | Click here to see the response
|
getPolicy()¶
| Description | Retrieve a pre-defined policy. | ||||||
| Input Parameters |
|
||||||
| Request | Click here to see the request |
||||||
| Response | Click here to see the response
|
getPolicyVersions()¶
| Description | Get the version of a given policy. | ||||
| Input Parameters |
|
||||
| Request | Click here to see the request
|
||||
| Responae | Click here to expand
|
getPublisherModuleData()¶
| Description | Get the details of the publisher |
| Input Parameters | None |
| Request | |
| Response | Click here to expand the response
|
publishToPDP()¶
| Description | Publish a policy to PDP | ||||
| Input Parameters |
|
||||
| Request | Click here to expand the request
|
||||
| Response | Click here to expand the response
|
removePolicy()¶
| Description | Remove policy from PDP | ||||
| Input Parameters |
|
||||
| Request | Click here to expand the request
|
||||
| Response | Click here to expand the response
|
updatePolicy()¶
| Description | Publish a policy to PDP | ||||
| Input Parameters |
|
||||
| Request | Click here to expand the request
|
||||
| Response | Click here to expand the response
|
There is no REST API available for the policy management.
Policy Evaluation API¶
Policy evaluation includes all the actions that should be done during the policy evaluation such as getting the decision, getting all entitlement attributes, etc. For this, WSO2 Carbon Platform has provided an admin service called EntitlementService to evaluate a policy.
-
You can use the following URL in your browser to see the WSDL of the EntitlementService admin service.
https://localhost:9443/services/EntitlementService?wsdlBy using any SoapUI, you can call this admin SOAP service.
Note
Note:
All the APIs are secured with basic authentication. Follow the steps below to add a basic auth header when calling these methods.
- Build a string of the form username:password.
- Encode the string you created above using Base64.
- 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 is as follows:
``` java Authorization: Basic YWRtaW46YWRtaW4= ```
Operations included in EntitlementService SOAP API¶
Note
Before you begin,
In order to try this EntitlementService using SOAP UI, You need to publish a Policy to the PDP. For this, you can use EntitlementPolicyAdminService or management console UI.
We use the following sample policy to evaluate using EntitlementService admin service.
<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>The following commonly used operations are available in the EntitlementPolicyAdminService. A sample SOAP request and response will be available with each of the operation.
getDecision()¶
| Description | Get the decision after evaluating the request with the policy. | ||||
| Input Parameters |
|
||||
| Request | Click here to expand the request
|
||||
| Response | Click here to expand the response
|
getBooleanDecision()¶
| Description | Get the decision after evaluating the request with the policy published in a boolean format. | ||||||||
| Input Parameters |
|
||||||||
| Request | Click here to expand the request |
||||||||
| Response |
getDecisionByAttributes()¶
| Description | Get the decision by evaluating attributes with the policy. | ||||||||
| Input Parameters |
|
||||||||
| Request | Click here to expand the request
|
||||||||
| Response | Click here to expand the request
|
getEntitledAttributes()¶
| Description | Get all the details of the entitled attributes. | ||||||||||||
| Input Parameters |
|
||||||||||||
| Request | Click here to expand the request
|
||||||||||||
| Response | Click here to expand the response
|
REST API
WSO2 Identity Server provides a REST API and a REST endpoint for the policy evaluation. Please read more about this REST API from here.