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 <HideAdminServiceWSDLs> element to false in <IS_HOME>/repository/conf/carbon.xml file.

<HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>
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,

1 Policy Administration API
2 Policy Evaluation API

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?wsdl
By using any SoapUI, you can call this admin SOAP service.

Operations included in the EntitlementPolicyAdminService SOAP API

The following commonly used operations are available in the EntitlementPolicyAdminService.

1 addPolicy()
2 getAllPolicyIds()
3 getPolicy()
4 getPolicyVersions()
5 getPublisherModuleData()
6 publishToPDP()
7 removePolicy()
8 updatePolicy()

addPolicy()

Description

Adds a new policy.

Input Parameters

Parameter	Description
`policy`	The policy that should be registered. The XACML policy should be embedded to the SOAP service as a CDATA.
`version`	Version of the policy.
`policyId`	The policy name that should be registered.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.axis2/xsd" xmlns:xsd1="http://dto.entitlement.identity.carbon.wso2.org/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <xsd:addPolicy>
         <!--Optional:-->
         <xsd:policyDTO>
            <!--Optional:-->
            <xsd1:policy><![CDATA[
				   <Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17"  PolicyId="sample_policy_template" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" Version="1.0">
				   <Description>This policy template provides ability to authorize users to a given service provider(defined by SP_NAME) in the authentication flow based on the roles of the user (defined by ROLE_1 and ROLE_2). Users who have at least one of the given roles, will be allowed and any others will be denied.</Description>
				   <Target>
				      <AnyOf>
				         <AllOf>
				            <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
				               <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">SP_NAME</AttributeValue>
				               <AttributeDesignator AttributeId="http://wso2.org/identity/sp/sp-name" Category="http://wso2.org/identity/sp" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="false"></AttributeDesignator>
				            </Match>
				         </AllOf>
				      </AnyOf>
				   </Target>
				   <Rule Effect="Permit" RuleId="permit_by_roles">
				      <Condition>
				         <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:or">
				            <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-is-in">
				               <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">ROLE_1_1_1</AttributeValue>
				               <AttributeDesignator AttributeId="http://wso2.org/claims/role" Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
				            </Apply>
				         </Apply>
				      </Condition>
				   </Rule>
				   <Rule Effect="Deny" RuleId="deny_others"></Rule>
				</Policy>        
				]]>
			</xsd1:policy>
            <!--Optional:-->
            <xsd1:version>1.0</xsd1:version>
            <xsd1:policyId>sample_policy_template</xsd1:policyId>
         </xsd:policyDTO>
      </xsd:addPolicy>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:addPolicyResponse xmlns:ns="http://org.apache.axis2/xsd">
         <ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
      </ns:addPolicyResponse>
   </soapenv:Body>
</soapenv:Envelope>

getAllPolicyIds()

Description	Retrieve all policy names or policy Ids.
Input Parameters	None
Request	`<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.axis2/xsd"> <soapenv:Header/> <soapenv:Body> <xsd:getAllPolicyIds> </xsd:getAllPolicyIds> </soapenv:Body> </soapenv:Envelope>`
Response	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <ns:getAllPolicyIdsResponse xmlns:ns="http://org.apache.axis2/xsd" xmlns:ax2340="http://dto.entitlement.identity.carbon.wso2.org/xsd" xmlns:ax2338="http://entitlement.identity.carbon.wso2.org/xsd"> <ns:return>authn_role_based_policy_template</ns:return> <ns:return>authn_scope_based_policy_template</ns:return> <ns:return>authn_time_and_role_based_policy_template</ns:return> <ns:return>authn_time_and_scope_based_policy_template</ns:return> <ns:return>authn_time_and_user_claim_based_policy_template</ns:return> <ns:return>authn_time_and_user_store_based_policy_template</ns:return> <ns:return>authn_time_based_policy_template</ns:return> <ns:return>authn_user_claim_based_policy_template</ns:return> <ns:return>authn_user_store_based_policy_template</ns:return> <ns:return>provisioning_role_based_policy</ns:return> <ns:return>provisioning_role_based_policy_template</ns:return> <ns:return>provisioning_time_and_role_based_policy_template</ns:return> <ns:return>provisioning_time_and_user_claim_based_policy_template</ns:return> <ns:return>provisioning_time_based_policy_template</ns:return> <ns:return>provisioning_user_claim_based_policy_template</ns:return> <ns:return>samplePolicy</ns:return> <ns:return>samplePolicy1</ns:return> <ns:return>samplepolicy_template</ns:return> </ns:getAllPolicyIdsResponse> </soapenv:Body> </soapenv:Envelope>