Getting start with Balana

Balana is one of open sourceXACML implementation that supports XACML 3.0.  If you need to do some testing on Balana or integrate the Balana with any other component, this blog post would be useful. Here i am going to explain how we can get start of Balana.

Approach 1. This is the easiest way. Just create Balana instance and create PDP instance from the configuration of Balana

Balana balana = Balana.getInstance();

PDP pdp = new PDP(balana.getPdpConfig());

pdp.evaluate(xacmlRequest);

Here Balana instance is created with following default configurations

-> with all standard attribute types
-> with all standard combining algorithms
-> with all standard functions
-> current environment module that supports following attribute Ids

urn:oasis:names:tc:xacml:1.0:environment:current-time
urn:oasis:names:tc:xacml:1.0:environment:current-date
urn:oasis:names:tc:xacml:1.0:environment:current-dateTime

-> attribute selector module to support xpath evaluations
-> file based policy finder module
-> disable multiple decisions

Approach 2. Creating Balana instance by reading configuration file with default configurations

System.setProperty(ConfigurationStore.PDP_CONFIG_PROPERTY, configFileLocation);

Balana balana = Balana.getInstance();

PDP pdp = new PDP(balana.getPdpConfig());

pdp.evaluate(xacmlRequest);

Here before you are creating the Balana instance, you want to specify the configuration file location.

Default configuration file would be as follows.

<config defaultPDP="pdp" defaultAttributeFactory="attr"
 defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
 <pdp name="pdp">
 <attributeFinderModule class="org.wso2.balana.finder.impl.CurrentEnvModule"/>
 <attributeFinderModule class="org.wso2.balana.finder.impl.SelectorModule"/>
 <attributeFinderModule class="org.wso2.balana.finder.impl.SelectorModule"/>
 <policyFinderModule class="org.wso2.balana.finder.impl.FileBasedPolicyFinderModule"/>
 </pdp>
 <attributeFactory name="attr" useStandardDatatypes="true"/>
 <functionFactory name="func" useStandardFunctions="true"/>
 <combiningAlgFactory name="comb" useStandardAlgorithms="true"/>
</config>

If you want to add new extension points, you can do it modifying this configuration file.

As an example, if you are defining new condition function called “TimeInRangeFunction” you can do it as follows,

 <functionFactory name="func" useStandardFunctions="true">
 <condition>
 <function class="org.wso2.balana.cond.TimeInRangeFunction"/>
 </condition>
 </functionFactory>

Approach 3. Creating Balana instance by reading configuration file with specified configurations.

There may be use cases, where you want to have multiple Balana configurations for different application. Then you can create Balana instance by specifying it using a identifier

System.setProperty(ConfigurationStore.PDP_CONFIG_PROPERTY, configFileLocation);

Balana balana = Balana.getInstance(identifier);

PDP pdp = new PDP(balana.getPdpConfig());

pdp.evaluate(xacmlRequest);

Your configuration file would look as follows.

<config defaultPDP="pdp" defaultAttributeFactory="attr"
 defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
 <pdp name="pdp">
 <attributeFinderModule class="org.wso2.balana.finder.impl.CurrentEnvModule"/>
 <attributeFinderModule class="org.wso2.balana.finder.impl.SelectorModule"/>
 <policyFinderModule class="org.wso2.balana.finder.impl.FileBasedPolicyFinderModule"/>
 </pdp>
 <pdp name="myApp">
 <policyFinderModule class="com.my.app.PolicyFinderModule"/>
 </pdp>
 <attributeFactory name="attr" useStandardDatatypes="true"/>
 <functionFactory name="func" useStandardFunctions="true"/>
 <combiningAlgFactory name="comb" useStandardAlgorithms="true"/>
 <combiningAlgFactory name="myApp" useStandardAlgorithms="true">
 <algorithm class="com.my.app.RuleAlg"/>
 </combiningAlgFactory>
 <combiningAlgFactory name="mySecondApp" useStandardAlgorithms="true">
 <algorithm class="com.my.app.SecondRuleAlg"/>
 </combiningAlgFactory>
</config>

There is a configuration called “myApp” So you can init Balana as

Balana.getInstance("myApp");

If you wan to use different configurations for one application, you can init Balana as following

Balana.getInstance(pdpConfigName, attributeFactoryName, functionFactoryName, combiningAlgFactoryName);

So if you are init Balana with “myApp” PDP config and “mySecondApp” combining Algo factory, then it would look as follows

Balana.getInstance("myApp", null, null, "mySecondApp");

Also if you are using default policy store, i.e “FileBasedPolicyFinderModule” you can specify the file path for your policy collection (directory that contains policy files).

Therefore before init the Balana instance you can specify it as following

System.setProperty(FileBasedPolicyFinderModule.POLICY_DIR_PROPERTY, policyDirectoryLocation);

I guess this blog post would be a good start point for Balana.

Discuss this article on Stack Overflow

Comments

  1. Greetings !

    Its nice to see this work progress forward. What is the open source licensing model for the balana code base?

    Thanks,
    prateek

  2. Hello,
    one more question from me! 🙂

    Is is somehow possible to create policy from Java code?
    I would like to avoid holding policies in external XML file!

    Thank you in advance!

    Best regards,
    Jurica

  3. Hi Jurica,

    I am not 100% sure about actual requirements. But it is not worth to holding policy in different way. Because XACML is a standard policy language. Therefore keeping policies as it is would be important. Then you can evaluate same policies set with different implementations that is available. You are defining access control policies, independent of the authorization server. However, if you want to create policies in an easier manner, you can try with WSO2 Identity server UI (v3.2.3) [1]

    [1] http://xacmlinfo.com/2012/05/02/xacml-policy-editor-in-wso2-identity-server/

  4. Hello,
    I have several questions regarding creating an instance of Balana.

    If I use public Balana getInstance(String identifier) method to get an instance, I am supposed to create an instance of Balana class before I call this method.

    It is only possible through public static Balana getInstance(), since there is no default constructor.

    So when I call Balana.getInstance().getInstance(“myApp”), the “myApp” identifier will never be passed to a constructor:
    private Balana(String pdpConfigName, String attributeFactoryName, String functionFactoryName, String combiningAlgFactoryName).

    So I believe that method public Balana getInstance(String identifier) should be static?

    Tell me if I am wrong, or I have a wrong version perhaps?! 🙂

    Thanks in advance!

    Best regards,
    Jurica Krizanic

  5. Hi,

    In my system I need to keep three different policies and use each of them in three different moments.
    Using the Sun implementation I was able to choose the right policy specifying the policy file path. Is it possible to do the same in Balana? Or, differently, keep the policy in a string?
    Is avaiable Balana API?

    Anyway, you did a great job!

    Best regards,
    Gaetano Mancini

  6. Asela,

    Where do I get the latest Balana code. Is the WSO2 Identity Server 4.5 using the same Balana library that is on the svn at this location https://svn.wso2.org/repos/wso2/trunk. I pretty much assume that you have enhanced in WSO2 with lots of caching code. I expect the caching is outside the Balana.

    We have seen few problems like stack overflow error in the balana trunk. We haven’t tested these policies in WSO2 IS but we will in the near short term to see if similar error will occur in wso2 IS for just 2 policies that we wrote..

    Jan 10, 2014 5:29:10 PM org.wso2.balana.finder.impl.FileBasedPolicyFinderModule findPolicy
    Exception in thread “main” java.lang.StackOverflowError
    at java.util.ArrayList$Itr.(ArrayList.java:820)
    at java.util.ArrayList$Itr.(ArrayList.java:820)
    at java.util.ArrayList.iterator(ArrayList.java:814)
    at java.util.Collections$UnmodifiableCollection$1.(Collections.java:1064)
    at java.util.Collections$UnmodifiableCollection.iterator(Collections.java:1063)
    at org.wso2.balana.PDP.processPolicyReferences(PDP.java:336)
    at org.wso2.balana.PDP.processPolicyReferences(PDP.java:339)

    So from WSO2 IS, we like to use only Balana engine library as the company has invested in other identity solutions.

    Thanks for your suggestions.
    Raj@Neustar

  7. Hi Raj,

    Balana latest source is here http://svn.wso2.org/repos/wso2/trunk/commons/balana/.. WSO2IS uses Balana as just a library. WSO2IS has extends the Balana extension points and has implemented caching there. As an example, Attribute cache , policy cache decision cache and so on. Actually we want to keep Balana as a simple library with pure XACML core implementation. The source code of XACML engine of WSO2IS 450 that uses Balana can be found here http://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/components/identity/org.wso2.carbon.identity.entitlement/4.2.0/

  8. Balana bug report:
    The useDefaultFactories function of the ConfigurationStore is never called(so the setDefaultFactory function of the FunctionFactory is never called). So when I defined a new function in the config file just as you mentioned in the post, the newly defined function will not be available, because the FunctionFactory will always use the StandardFunctionFactory initialized in the static block of the FunctionFactory.

    Hope this help anyone intended to define your own function or attribute.

Leave a Reply

Your email address will not be published. Required fields are marked *