Custom XACML functions for WSO2 Identity Server 5.10.0

XACML (eXtensible Access Control Markup Language) is an XML-based language for access control that has been standardized by the Technical Committee of the OASIS consortium.

I assume that you are familiar with XACML. If you want a quick recap on what is XACML and how to use XACML with WSO2 IS, you may refer to my previous blogs of this series of blogs; “XACML with WSO2 Identity Server”.

1. “A beginner’s guide to XACML”
2. “WSO2 Identity Server as an XACML Engine”
3. “Customizing XACML Policy Information Point of WSO2 Identity Server 5.10.0”

In this fourth blog, let’s see how you can write a custom XACML function for the policy evaluation of the WSO2 Identity Server.

WSO2 Identity Server is implemented with much extensibility that has standard extension points for defining new functions, data types and attribute-finders to manage your own policies and plugin them to the existing infrastructure.

XACML Functions

WSO2 IS provides standard XACML support for a wide variety of functions from simple boolean operations (like integer-equal, and/or/not, date-less-than) to complex Set and Bag-related functions. There are even functions that let you do set mappings using other functions as transforms. This fairly large set of functions would be sufficient for most of the generic usecases. However, you can write new functions and make them available for any policy to use.

All the functions implement the Function interface. And also there is the FunctionBase helper class which supplies several useful methods, making it easier to implement a function. The JavaDocs of these classes explains more about what each of the classes and the methods are supposed to do. Basically, a function can be evaluated against a set of inputs, can be asked if a set of inputs is acceptable, and provides information about its return type and identity.

Custom XACML Functions with WSO2 Identity Server

Deploying a custom XACML function in the WSO2 Identity Server requires three main steps.

1. Write the custom function as a component for WSO2 IS
2. Add the custom component to the WSO2 IS
3. Configure the custom component in the WSO2 IS

Let’s look at each of these steps in detail and then I will discuss how you can use this custom XACML function in an XACML policy. Before moving to the customization details, let’s identify the scenario that we are going to implement.

Scenario:

1. Users may belong to one or more roles based on their departments and job levels. The following are some examples for the role name.
   (iam-engineer, iam-lead, iam-intern, apim-engineer, apim-lead, apim-intern)
2. The XACML policy should identify all the departments where the user belongs to a given job level
3. Therefore the XACML function should be written to trim the role name and return the departments of the user.

Implementing the custom function

You can refer to the pom.xml file for the project from the sample given. This has the dependencies relevant to the WSO2 IS 5.10.0. I have attached the complete source code for your reference and check the inline comments for more details.

Write the custom XACML function by extending the FunctionBase.

In the Constructor of the custom XACML function, you can call the constructor of the superclass passing the required attributes. There are several constructors for the superclass with a different number of arguments. You can use the constructor based on your requirement. I will explain one of the constructors so that you can get an idea of the other constructors as well.

In this sample, we are using the constructor,

public FunctionBase(String functionName, 
int functionId, String[] paramTypes, boolean[] paramIsBag, String returnType, boolean returnsBag)

• String functionName: The name of the custom XACML function
• int functionId: id for the custom XACML function
• String[] paramTypes: This argument states the attribute type of each of your input parameters. It is an array and contains an element corresponding to each of the input parameters in the order of them.
• boolean[] paramIsBag: This argument states whether each of the input parameters in a bag of elements
• String returnType: The attribute type of the return value
• boolean returnsBag: States whether the returning value is a bag of elements.

In our sample XACML function, we have two inputs.

1. The list of roles of the user
2. The required job level

Therefore,

• String[] paramTypes = [“http://www.w3.org/2001/XMLSchema#string”, “http://www.w3.org/2001/XMLSchema#string”]
• boolean[] paramIsBag = [true, false]

The sample XACML function should return the list of departments where the user has the given job level. Therefore,

• String returnType = “http://www.w3.org/2001/XMLSchema#string”
• boolean returnsBag = true

And then you need to override the evaluate(List inputs, EvaluationCtx context) function to have the logic of the custom XACML function.

Deploying the custom XACML function

1. When the implementation is done, go to the project home(sample-xacml-function) and run the command,

mvn clean install

2. When the compilation completes, you can find the com.pamtech.xacml.function-1.0.0.jar inside the sample-xacml-function/target. Copy the jar file to the directory <IS_HOME>/repository/components/lib.

3. Register the custom XACML function in the WSO2 Identity Server by adding class path of the function implementation in the balana-config.xml in <IS_HOME>/repository/conf/security folder under the <functionFactory> tag.

<functionFactory name="func" useStandardFunctions="true">
   <condition>
      <function class="org.wso2.carbon.identity.entitlement.extension.EvalPermissionTreeFunction"/>
      <function class="com.pamtech.xacml.function.SampleXacmlFunction"/>
   </condition>
</functionFactory>

Try out the custom XACML function

Deploy the following XACML policy.

<Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17"  PolicyId="custom_function" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" Version="1.0">
   <Description>Custom XACML Function</Description>
   <Target></Target>
   <Rule Effect="Permit" RuleId="view_rule">
      <Condition>
         <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-is-in">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">iam</AttributeValue>
            <Apply FunctionId="string-custom-xacml-function">
               <AttributeDesignator AttributeId="http://wso2.org/claims/role" Category="urn:oasis:names:tc:xacml:3.0:subject-category:access-subject" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"></AttributeDesignator>
               <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">lead</AttributeValue>
            </Apply>
         </Apply>
      </Condition>
   </Rule>
   <Rule Effect="Deny" RuleId="deny_others"></Rule>
</Policy>

You may follow the WSO2 official document or my previous blog to deploy the XACML policy and with sample XACML requests using the TryIt Tool of the product.

WSO2 Identity Server comes with amble extensible capabilities. So you can plug in custom XACML functions as required and use in the authorization rules. Try out custom XACML functions with WSO2 Identity Server and share your thoughts.

Thanks for reading.

References

Sample Source Code:

https://github.com/pamodaaw/sample-entitlement-service

My other blogs on XACML:

1. A beginner’s guide to XACML
2. WSO2 Identity Server as an XACML Engine
3. Customizing XACML Policy Information Point of WSO2 Identity Server 5.10.0

Official WSO2 documentation: https://is.docs.wso2.com/en/5.10.0/develop/writing-a-custom-policy-info-point/