Rule Based Provisioning

Under Outbound Provisioning in general we have discussed how to provision users to trusted identity providers. In this document we discuss how to provision users based on defined XACML rules.

To get a better understanding of rule based provisoning, let's look a sample scenario where you provision users in the finance role from WSO2 Identity Server to the GoogleIDP. To implement this scenario we define a XACML policy which permit the provisioning operation if the provisioning users is within the finance role.

For that steps given below:

Step 1: Configure outbound provisioning in WSO2 Identity Server.

Start the WSO2 Identity Server and log in to the management console.
Navigate to Add under Identity Providers on the Main tab and create a new identity provider. For more information on creating identity providers, see Adding an Identity Provider.
Expand the Outbound Provisioning Connectors section and configure an outbound provisioning connector (i.e, Google, Salesforce, SCIM or SPML). You can configure Google Outbound Provisioning by reading more information from Configuring Outbound Provisioning Connectors for an Identity Provider.
Click Register to save configurations.
Navigate to Add under Service Providers on the Main tab and create a new service provider. For more information on creating service providers, see Adding a Service Provider.
Expand the Outbound Provisioning Configuration section and select the provisioning connector you just configured above. Lets say we have configured a IDP named "wso2IDP" which used Google outbound provisioning connector.
Click on the + button and add wso2IDP, then select the Enable Rules in order to enable rules during provisioning. Click Update to save.

If you wish to configure outbound provisioning under Resident Service Provider configurations, Click Resident under Service Providers and expand the Outbound Provisioning Configuration section. Select the Enable Rules and Blocking checkboxes and click Update. Blocking will block the provisioning(user creation in the second IDP) till the rule completely evaluate and get the response back to the WSO2 IDP.

Now you are done with configuring outbound provisioning. Since we are enabling rules here, we have to enforce some XACML rules.

For that, you can follow the below steps.

Step2: Set up XACML rules

After setting up the Identity provider, Please follow the below steps to set up the policy according to our requirement.

Click on Policy Administration under the Entitlement>PAP section on the Main tab of the management console.
Since this sample scenario is based on role, we select the policy provisioing_role_based_policy_template.

XACML template policies provide a pre-configured template with placeholders for different types of policies. For a full list of the available XACML policy templates, see Writing an XACML Policy using a Policy Template.
Once you click on "Edit", the XML based policy will appear in the policy editor. There are placeholders in capitals for entering the service provider and role names.
Edit the placeholders accordingly with the relevant values.
1. Change the PolicyId as follows:
```
PolicyId="provisioning_role_based_policy"
```
2. Edit the <Description> tag and enter a description relevant to your custom policy.
```
 <Description>This template policy provides ability to authorize provisioning requests initiated from a given service provider(defined by SP_NAME) to a given identity provider(defined by IDP_NAME) in the outbound provisioning flow based on the roles of the user (ROLE_1, ROLE_2). Provisioning attempts to the users with given role(s) will be allowed and all others will be denied.</Description>
```
3. Locate the IDP_NAME placeholder and replace it with the identity provider name "WSO2IDP".
4. Locate the placeholder ROLE_1 and replace it with the role name "finance".
5. In this example, this policy authenticates users to the specified service provider based on ROLE_1 or ROLE_2. However, you can authenticate using only one role as well. To do this, remove the other role by removing that entire section from the start of the <Apply> tag to the ending </Apply> tag. This should be edited in both POST and PUT sections as the provisioning is initiated when creating the user and when updating the user as well.

Once the changes have been made, the policy should be similar to the following.

Access control policy

<Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17"  PolicyId="provisioning_role_based_policy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" Version="1.0">
   <Description>This template policy provides ability to authorize provisioning requests initiated from a given service provider(defined by SP_NAME) to a given identity provider(defined by IDP_NAME) in the outbound provisioning flow based on the roles of the user (ROLE_1, ROLE_2). Provisioning attempts to the users with given role(s) will be allowed and all 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">WSO2IDP</AttributeValue>
               <AttributeDesignator AttributeId="http://wso2.org/identity/idp/idp-name" Category="http://wso2.org/identity/idp" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="false"></AttributeDesignator>
            </Match>
            <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
               <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">provisioning</AttributeValue>
               <AttributeDesignator AttributeId="http://wso2.org/identity/identity-action/action-name" Category="http://wso2.org/identity/identity-action" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="false"></AttributeDesignator>
            </Match>
         </AllOf>
      </AnyOf>
   </Target>
   <Rule Effect="Permit" RuleId="permit_by_role_when_create">
      <Target>
         <AnyOf>
            <AllOf>
               <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                  <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">POST</AttributeValue>
                  <AttributeDesignator AttributeId="http://wso2.org/identity/provisioning/provision-operation" Category="http://wso2.org/identity/provisioning" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
               </Match>
            </AllOf>
         </AnyOf>
      </Target>
      <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">finance</AttributeValue>
               <AttributeDesignator AttributeId="http://wso2.org/identity/provisioning/claim-group" Category="http://wso2.org/identity/provisioning" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
            </Apply>
         </Apply>
      </Condition>
   </Rule>
   <Rule Effect="Permit" RuleId="permit_by_role_when_update">
      <Target>
         <AnyOf>
            <AllOf>
               <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                  <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">PUT</AttributeValue>
                  <AttributeDesignator AttributeId="http://wso2.org/identity/provisioning/provision-operation" Category="http://wso2.org/identity/provisioning" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
               </Match>
            </AllOf>
         </AnyOf>
      </Target>
      <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">finance</AttributeValue>
               <AttributeDesignator AttributeId="http://wso2.org/claims/role" Category="http://wso2.org/identity/user" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
            </Apply>
         </Apply>
      </Condition>
   </Rule>
   <Rule Effect="Deny" RuleId="deny_others"></Rule>
</Policy>

Click Save Policy to save the changes. You can see the policy you just created on the policy list (the original template policy will remain unchanged for later use).
Click on the Publish to My PDP link corresponding to the new policy.
On the UI that appears, leave the default selected values as they are and click Publish.

For more information on Publishing an XACML policy, click here.
Click on Policy View under the Entitlement>PDP section on the Main tab of the management console.
To ensure that the policy has been published successfully, check if the policy is listed.
To test out whether the policy works, follow the steps in the Try it out section.

If you want to write a more complicated policy you can use our XACML policy editors available. To get more information Read, "How to create XACML Policy"

Step3: Try It

Once the policies are published to PDP, they are ready to execute during outbound provisioning. You can test rule-based provisioning by creating a user in the WSO2 Identity Server side that matches the rules you enforced. That means you can create a user with the role "finance" in the WSO2IDP and it will provision to the Google IDP as well. All the other users will not be provisioned.