Access policy development

You can use JavaScript to define and develop access policies. Access policies are used to decide whether a user is allowed access to a single sign-on federation. Access policies return a decision of either Allow, Deny, or Challenge. To write an access policy in JavaScript, use the Java classes, methods, and handlers that are supplied in ISAM. To view the Javadoc, use the local management interface.

1. Click...
   System > File Downloads > federation > doc

2. Access ISAM-javadoc.zip.

   Expand the Javadoc to view the relevant packages. For example:

   • com.ibm.security.access.policy
   • com.ibm.security.access.policy.decision
   • com.ibm.security.access.policy.saml20
   • com.ibm.security.access.policy.user

Allow

Use the allow decision to allow the single sign-on flow to continue if the requirement is met. The following example code shows a simple access policy that does not check any condition or requirement.

importClass(Packages.com.ibm.security.access.policy.decision.Decision);
var decision = Decision.allow();
context.setDecision(decision);

Another example is to allow the single sign-on flow to continue if the username equals testuser.

importClass(Packages.com.ibm.security.access.policy.decision.Decision);
importClass(Packages.com.ibm.security.access.policy.decision.HtmlPageDenyDecisionHandler);
importPackage(Packages.com.tivoli.am.fim.trustserver.sts.utilities);

//Retrieve the user context
var user = context.getUser(); 
//Retrieve the username
var username = user.getUsername();

if (username == "testuser"){
//Check the condition is username = testuser
    var decision = Decision.allow();
    context.setDecision(decision);
}else{
    //If username is not testuser then deny the SSO flow.
    var handler = new HtmlPageDenyDecisionHandler();
    handler.setMacro("@MESSAGE@", JSON.stringify("Sorry "+username+ " is not allowed to run
    	a successful Single Sign on flow"));
    var decision = Decision.deny(handler);
    context.setDecision(decision);
}

Challenge

Use the challenge decision to force the user to complete an action before the single sign-on flow can proceed. The action might be to be redirected to a service that is running out of the Security Verify Access appliance, or to an HTML page provided by Security Verify Access, or to a custom HTML page, by setting a pageid. When you redirect to an HTML page, we can set macros to display data on the page. The challenge decision can result in one of the following actions.

• HTMLPage Challenge

  This decision results in the display to the user of a default HTML page or a custom HTML. The default page is present under /access_policy, and is called challenge_decision.html. To challenge with a custom page, call the setPageId function with the path where the page is uploaded in Template Files.

  setPageId("/access_policy/Challenge_User.html");

  Macros can be set and retrieved by using the setMacro function.

  setMacro("@MESSAGE@", "Challenge Decision");

  When a challenge decision is called during a single sign-on operation, the single sign-on operation halts for the challenge to be completed. When the challenge is completed, the single sign-on operation must resume. To resume the operation, the page must be a POST operation on the @ACTION@ macro, which resumes the flow.

• Redirect Challenge

  This decision results in an HTTP redirect to an external or third-party service. The user must complete the challenge before single sign-on can resume. In this scenario, the single sign-on flow is halted when a redirect challenge decision is initiated by the third-party server. The third party must be told which URL to redirect the user to, when the user successfully completes the challenge. Following is example code for a redirect challenge.

  setRedirectUri("https://www.service.ibm.com/isam/service&redirectUri=https://www.myidp.ibm.com/isam@ACTION@");

  The URL https://www.service.ibm.com/isam/service is the third-party application or service that sends a challenge to the user. In this example, https://www.myidp.ibm.com/isam is the point of contact for the identity provider federation or OpenID Provider, and @ACTION@ indicates the endpoint to access to resume the single sign-on flow. The Security Verify Access runtime server populates the value for the @ACTION@ macro.

Deny

The Deny decision can result in one of the following actions.

• HTMLPage Deny

  A default HTML page or a custom HTML page displayed to the user. The default page, deny_decision.html, is located under /access_policy. To deny with a custom page, call the setPageId function with the path where the page is uploaded in Template Files.

  setPageId("/access_policy/Deny_User.html");

  You can use the setMacro function to set and retrieve macros.

  setMacro("@MESSAGE@", "Deny Decision");

• Redirect Deny

  HTTP redirect to an external or third-party service. Example code for a redirect is as follows.

  setRedirectUri("https://www.denyService.com");

  The URI https://www.denyService.com is the third-party application to which the user is redirected.

• User context example for access policy
  
• Request context example for access policy
  
• SAML 2.0 protocol context example for access policy
  
• OAuth and OpenID Connect protocol context example for access policy
  
• Session context example for access policy
  
• Reauthentication example for access policy
  

Parent topic: Access policies