ISAM for Mobile: Javascript Policy Information Points

Since 8.0.0.3 ISAM for Mobile has had the ability to call a Javascript Policy Information Point (PIP) during context based access (CBA, formerly risk based access – RBA) decisions for attribute enrichment. This capability is very flexible and can be used for many different purposes. Some examples include:

  • Manipulating and extracting attributes from request headers.
    This is performed by the out of the box PIP’s including the Trusteer PIP and the Worklight PIP.
  • Manipulating the data type of attributes.
    An example is shown below, converting an attribute from a String to a Integer.
  • Calling an information service.
    The Javascript framework has a number of functions available for both onbox and off box (internal and external) lookups.
  • Even just adding a custom value into your CBA context.

In this post, I’ll show an example using a JavaScript PIP to extract a String value from the ISAM credential, convert it to a Integer and then use it in an CBA policy protecting a resource.

IBM’s documentation for v8.0.1.0 can be found here.

Environment prerequisites

In following this example, I’ve already configured the following:

  • ISAM for Web and ISAM for Mobile have already been fully configured.
  • A junction has been created to a protected resource.
  • The custom attribute SecurityLevel is added to the ISAM credential upon authentication.
    (I’m using an extended attribute added via an EAI, but this could also be performed via loading a custom LDAP attribute.)

Custom Attribute definition

In order to write a policy with an attribute that is not defined from a default installation, it is necessary to define a custom attribute.

A new attribute can be easily defined under Secure Mobile Settings -> Access Control -> Attributes.

javascriptpipattribute

Name: Security Level
Identifier: urn:demo:securitylevel
Issuer: TagValuePIP
Category: Subject
Data Type: Integer
Matcher: exact_match
Type: Policy

Since this attribute is defined by the custom JavaScript PIP, the important values are the Identifier, which we specify in the JavaScript code, the Issuer which labels where the attribute is sourced, the category which tells CBA where the attribute will be stored in the XACML definition, and the data type which allows us to do integer/mathematical comparisons in our CBA policy.

Note: If you don’t select an attribute Type of Policy, you cannot see or use the attribute when writing a new policy.

Context Based Access Policy

The simple CBA policy I will use to demonstrate the use of a PIP is as follows:

javascriptpippolicy

The policy is a simple one, it will only permit access if the Security Level attribute is greater than or equal to 2.

Where possible I like to write my policies with the Precedence of First, this tends to make the policies easier to read with an If, Then, Else methodology.

Define your JavaScript PIP

In order to define a JavaScript PIP, it is necessary to implement two functions to meet the PIP Interface:

  • function hasAttribute (requestedAttribute, category)
    This function will return true if the PIP is capable of servicing the request.
  • function getAttributes (context, requestedAttribute, category)
    This function will add the requested attribute to the context.

This sample requires we import a few libraries so that they are available in our JavaScript.

/** 
 * Import packages necessary for the script to execute.
 */
importPackage(com.tivoli.am.rba.extensions);
importClass(Packages.com.tivoli.am.rba.attributes.AttributeIdentifier);

JavaScript is used in a number of places on the appliance, and each appliance ships with the relevant and most up to date Java Documentation for it in the appliance Manage System Settings -> File Downloads section.

javascriptpipdoc

The most common way that the first mandatory function is implemented is to look at the requestedAttribute Issuer and match that against the defined PIP. In order to be dynamic, its possible to use the global variable instanceName of the PIP as the Issuer.

/**
 * This function will return true if an attribute's issuer matches the 
 * instanceName of this PIP
 */
function hasAttribute (requestedAttribute, category) {

    // Dynamically set the issuerId that that this PIP services to the name
    // of the PIP. (Note this could be hardcoded).
    var issuerId = instanceName;

    // If Issuer matches, this PIP can service the request
    if (issuerId.equals(requestedAttribute.getIssuer()))
    {
        return true;
    }
    // This PIP can't service this request
    return false;
}

The getAttributes function will fire when the hasAttributes function returns true. The getAttributes function is where the logic of attribute enrichment occurs. In this example getAttributes will extract the String attributes supplied in the ISAM credential, and convert them to an integer and add the attributes back into the context.

/**
 * This function extracts the value from the ISAM context, 
 * converts it to an int and adds it back into the context
 */
function getAttributes (context, requestedAttribute, category) {
    PluginUtils.trace("ENTER getTagvalueAttributes [" + instanceName + "]");

    var tagvalueSecurityLevelIdentifier = 
           new AttributeIdentifier("tagvalue_securitylevel", 
           Attribute.DataType.STRING, null);
    var securityLevelString = 
           context.getAttribute(Attribute.Category.SUBJECT, 
           tagvalueSecurityLevelIdentifier)[0];

    // convert string to Integer
    var securityLevelInt = parseInt(securityLevelString);
    
    PluginUtils.trace("securityLevelInt: " + securityLevelInt);

    // write new attribute to context
    var securityLevelIdentifier = 
            new AttributeIdentifier("urn:demo:securitylevel", 
            Attribute.DataType.INTEGER, instanceName);
    context.addAttribute(securityLevelIdentifier, [securityLevelInt]);
    
    // Additional/multiple attributes could be added now too
    // For Example: 
    var philipnyeAttributeIdentifier = 
            new AttributeIdentifier("urn:demo:philipnye", 
            Attribute.DataType.STRING, instanceName);
    context.addAttribute(philipnyeAttributeIdentifier, ["philipnye.com"]);
    
    PluginUtils.trace("EXIT getTagvalueAttributes [" + instanceName + "]");
}

Notes:

  • PluginUtils.trace can be used to create tracing statements. This can be very helpful when performing more complex conversions or callouts. These will appear in the trace.log file:
    javascriptpiplogfileswhen you have the appropriate levels of trace enabled:
    javascriptpiptrace
  • Returned attributes can take many different data formats, the full list of supported Datatypes is in the JavaScript documentation.
    javascriptpipattributedatatypes

Create a new Policy Information Point

Navigate to Secure Mobile Settings -> Information Points.

javascriptpipupload

And create a new JavaScript PIP definition.

javascriptpipnew

Supply the following:

javascriptpipupload

Ensuring the name of the PIP matches the Issuer of the attribute, and upload the script file.

Configuration Parameters

Want to know how to access the config parameters, see this short article:

ISAM AAC CBA PIPs – Accessing config options

Conclusion

This should be all the steps required to write your own custom Policy Information Point using JavaScript. If you still need more examples, remember you can download any of the preloaded JavaScript PIPs that come with the appliance!

Writing CBA policy can be very powerful, and it can also let you keep your users informed, in this example, I’ve created an obligation that can redirect the user to a suitable message page:

javascriptpipobligation

 

 

One thought on “ISAM for Mobile: Javascript Policy Information Points

Add yours

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

WordPress.com.

Up ↑

%d bloggers like this: