Scripting Design
This section introduces Client side and Server side scripts in OpenAM 13. These can be glued together to create Scripted Authentication modules that serve to create powerful authentication workflows as shown later in the Examples section.
Client Side Script
Authentication modules can use Client Side scripts and Server Side scripts using either JavaScript or Groovy. Note that the use of a Client side script is optional. If there is a requirement to collect information from the user, or browser plugins, fonts, screen resolution of a device, or even geolocation then by all means use the Client side script to collect and return the data to the Server side script.
The collected data is returned in the clientScriptOutputData object. You can use the .split() method to pull the client side data and parse accordingly.
An example Client side script is shown below.
Server Side Script
The Server side script handles authentication and is the place to put authentication workflow business logic. The Server side script has access to clientScriptOutputData and OpenAM’s powerful Scripting API. This script must set the authentication state to either success of failed, for example:
An example of using Server side scripts is as follows:
Chaining Scripted Authentication in OpenAM
You would setup your scripted module similar to any other authentication module in OpenAM, such as:
In this particular example, I have required DataStore to be a requisite module, followed immediately by a Scripted module that requires the authenticated user’s userId. See the following code snippet:
This Server side script is written in Groovy. The script reads the username and password from Shared State – a protected and shared area in memory – and uses the credential to make REST-based Policy calls to another OpenAM server (which could be a central policy hub in your enterprise, for example).
Scripting API
HTTP Commons Framework
OpenAM 13 introduces the HTTP Commons Framework. The following packages are available to developers:
org.forgerock.http.protocol.* – Request, Cookie, Entity, Header, Headers, and Response objects
org.forgerock.util.promise.* – Promise objects that represent the result of an asynchronous task in OpenAM
groovy.json.JsonSlurper – a very useful JSON parser that can be used in the scripts.
The API documentation is at http://commons.forgerock.org/bom/apidocs/index.html
You can use the new HTTP Commons Framework to create a new Request, and invoke REST API calls from the Server Side Script. For example: httpClient.send(Request), returns a Promise. Promise.get(), returns a Response. You may then parse the Response using JsonSlurper. The Server side script can access the Authentication State via the authState, and sharedState objects, as mentioned earlier.
Note that you will need to add the JsonSlurper, or any other class you wish to use, to the whitelist. Otherwise you will get a Security Exception stating use of the class is prohibited. You can whitelist a class using instructions documented here:
Logging
The logger object provides error(), message() and warning() methods for logging requirements.
Entity Profile
You are able to access user, group or device profile data via the idRepository object that provides the getAttribute(), setAttribute() and addAttribute() methods.
Original Request
You can also access the original login request using the requestData object, that provides the getHeader(s) and getParameter(s) methods.
Examples
Included here are some examples of using the Scripting API.
SSOToken
You can acquire an ssoToken object over REST
Policy Evaluation
Given the following two policies:
AuthnPolicy:
and AuthnPolicyY:
You can evaluate policy for the resource “authn/self’ and “authn/view”.
A policy decision is returned:
Check the policy decision and permit authentication if requested actions are ALLOWED:
Finally, logout the service account used for policy invocation using another REST call:
Comments are closed.
Hello Javed,
Thanks for the nice post. I am using OpenAM 13. I am also trying to write a server-side Groovy script.
I added the relevant packages in the whitelist (in $path/config/xml/amAuthScripted.xml) and updated the iPlanetAMAuthScriptedService, and restarted OpenAM.
I added the following entries in auAuthScripted.xml:
org.forgerock.http.protocol.*
org.forgerock.util.promise.*
groovy.json.JsonSlurper
However, I am unable to login after restarting OpenAM. I start getting this error:
amAuth:03/04/2016 08:29:28:861 AM EST: Thread[http-bio-8443-exec-5,5,main]: TransactionId[a935529a-81d7-49f9-a9e0-c72716b1a0ba-68]
ERROR: JAAS module for config: ORGANIZATION=dc=myhost,dc=net;CLIENT=html, No Configuration found|noConfig.jsp
In fact, the login URL is always redirecting me to “…/XUI/#failedLogin”.
Any help is greatly appreciated.
Thanks,
Soumya Kanti
Thanks, I found the solution.
Ok, cool :)
Let me know if you have any other questions
@javed do you know if it’s possible to add other Java classes? e.g. java.sql? I’ve added this class to the whitelist but the script doesn’t seem to recognize it.
@brad-tumy As long as the library is in the classpath, it should be picking it up.
Hi there,
thanks for posting this article.
Could you explain me what i have to amend (and where) if want to hide the “collect data” message from the user browser?
Thanks