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 Security Access Manager. To view the Javadoc, use the local management interface.

  1. Select Manage System Settings > 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 Access Manager appliance, or to an HTML page that is provided by Security Access Manager, or to a custom HTML page, by setting a pageid. When you redirect to an HTML page, you 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 Access Manager runtime server populates the value for the @ACTION@ macro.

Deny

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

  • HTMLPage Deny

    This decision results in a default HTML page or a custom HTML page that is 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

    This decision results in an 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.