Writing simple PIP module for WSO2 Identity Server

One of my previous post, I have discussed about the PIP implementation of the WSO2 Identity Server. Now lets try to write a simple PIP attribute finder module to plug in to the WSO2 Identity Server.

There are two ways that you can write a PIP attribute finder module

  •  By implementing the “PIPAttributeFinder” Interface. You can find the latest interface from here
  •  By extending the “AbstractPIPAttributeFinder” abstract class You can find the latest abstract class  from here

It would much easy for us to extend the “AbstractPIPAttributeFinder” and write a PIP attribute finder module. Lets take following simple example use case.

Think, K-Market is an online trading company. K-Market does some control over online trading based on the customer’s privilege and attribute of customers such as age, email and so on. Therefore to achieve the attribute base access control (ABAC);  user attributes that have been stored in JDBC based user store,  must be retrieved by the PDP of WSO2 Identity Server.

Lets go with step by steps …. Please note this sample project can be found at this svn location

Step 1. Assume K-Market attribute store is a database. Lets say, in mysql database. you can find sample script from here that i used.

Step 2. Write a PIP module by extending “AbstractPIPAttributeFinder”  Please find the “KMarketJDBCAttributeFinder” class from here.

Following are the methods,  you need to implement.

a).  init (Properties properties)   Here you can write the logic to initialize your module. Any properties that are defined in the entitlement.properties file,  can be access here.

JNDI name of the datasource  can be define as property value in entitlement.properties file. And is read here.  Also supported attributes are initialized inside this method.

b).  getAttributeValues (String subject, String resource, String action, String environment, String attributeId, URI issuer)    Here you can write the logic to find your attribute value

subject -> attribute value which can be identify by the following attribute value in the request.

urn:oasis:names:tc:xacml:1.0:subject:subject-id

resource -> attribute value which can be identify by the following attribute value in the request.

urn:oasis:names:tc:xacml:1.0:resource:resource-id

action -> attribute value which can be identify by the following attribute value in the request.

urn:oasis:names:tc:xacml:1.0:action:action-id

environment -> attribute value which can be identify by the following attribute value in the request.

urn:oasis:names:tc:xacml:1.0:environment:environment-id

attributeId  -> attribute id which is defined in the policy  and that is need to be resolved

issuer -> issuer which is related with the attributeId that is need to be resolved

c).   getSupportedAttributes()    Here you can write the logic to find all the attribute ids supported by your module

d)   getModuleName()  name for the module

Step 3. You need to create a jar file from your class. You can build the project using maven 3 and create the jar file.

Step 4. Copy created  org.xacmlinfo.xacml.pip.jdbc-1.0.0.jar in to <IS_HOME>/repository/components/lib directory

Step 5. Copy any dependency libraries for PIP module to <IS_HOME>/repository/components/lib directory.  Here JDBC driver jar file, which helps to create the JDBC connection  (ex- mysql-connector-java-5.1.10-bin.jar) .

Additional Step. Configure new data source configuration using master-datasources.xml file which can be found at <IS_HOME>/repository/conf/datasources directory (Only Applies, If you are defining datasource configuration using  master-datasources.xml file) . Sample configuration would be as follows.

<datasource>
<name>KMARKET_USER_DB</name>
<description>The datasource used for K-Market user store</description>
<jndiConfig>
<name>jdbc/KMARKETUSERDB</name>
</jndiConfig>
<definition type="RDBMS">
<configuration>
<url>jdbc:mysql://localhost:3306/kmarketdb</url>
<username>root</username>
<password>asela</password>
<driverClassName>com.mysql.jdbc.Driver</driverClassName>
<maxActive>50</maxActive>
<maxWait>60000</maxWait>
<testOnBorrow>true</testOnBorrow>
<validationQuery>SELECT 1</validationQuery>
<validationInterval>30000</validationInterval>
</configuration>
</definition>
</datasource>

Step 6. Open the entitlement.properties file which can be found at <IS_HOME>/repository/conf/security  directory  and register your PIP module. Here is my sample configuration

PIP.AttributeDesignators.Designator.2=org.xacmlinfo.xacml.pip.jdbc.KMarketJDBCAttributeFinder
#Define JNDI datasource name as property value
org.xacmlinfo.xacml.pip.jdbc.KMarketJDBCAttributeFinder.1=DataSourceName,jdbc/KMARKETUSERDB

Step 7. Restart the Server if already has been started.

Now You have successfully registered a PIP attribute finder with WSO2 Identity Server…!!!

Once you login in to the management console,  you can see that PIP attribute finder has been registered successfully.  You can re-initialize it in run time.

To test this attribute finder,  you can use this policy and this request.  Please upload the policy in to the WSO2 Identity Server,  then  publish it to PDP and enable it.  You can then try out policy with TryIt PEP.

You can actually debug this sample code by starting the WSO2 Identity Server in the debug mode as follows

wso2server.sh -debug 5005 (UNIX) or wso2server.bat -debug 5005 (Windows)

Then you can clearly see how methods in “KMarketJDBCAttributeFinder” are called by the PDP.