JavaScript access policies

This document covers all the interfaces for access policy JavaScript.

The two main objects supported for access policy JavaScript are context and Decision.

1. Context

The context object represents an access policy context. It has four main methods.

1.1. ProtocolContext

This object represents a protocol context and allows access to OAuth/OIDC protocol context, such as client, definition, and request parameters.

1.1.1. AuthenticationRequest

This object represents an authentication request.

1.1.2. AuthenticationContext

This object represents an authentication context and allows access to selected authorization request parameters.

1.1.3. Claim

This object represents a particular claim under the claims request parameter.

1.2. Request

This object represents the request of the current user interaction and allows access to the incoming HTTP request.

1.2.1. Cookie

This object represents an HTTP cookie.

1.3. PolicyUser

This object allows access to the authenticated user information.

1.3.1. Attribute

This object represents a user attribute.

Note: since the getValue() return any type, including JS slices or JS object, the getValues() is no longer supported.

1.3.2. Group

This object represents a user group.

1.4. Session

This interface represents the session of the current user access. By storing data in the session, the data is available even after a redirection.

Example of usage:

  var guessedNumber = context.getRequest().getParameter("user_guess");
  if (guessedNumber == undefined || guessedNumber == null) { // Challenge user
    context.getSession().setAttribute("storedNumber", 75);
    ...
    context.setDecision(Decision.challenge(handler)); // send challenge handler to guess the storedNumber
  } else {
    var storedNumber = context.getSession().removeAttribute("storedNumber"); // load number
    if (storedNumber == guessedNumber) { // guessed correctly, allow it
      context.setDecision(Decision.allow());
    } else {
      ...
      context.setDecision(Decision.deny(handler)); // send deny response
    }
  }

2. Decision

The Decision object represents a decision. It has three main methods.

The decision is then passed to the context object by calling the context.setDecision() method. This statement is the last statement of any path in the access policy JavaScript.

Typically, Decision object is created (by calling one of the methods) just before it is set into the context. As such, ISVA OIDC Provider does not support getType() and getHandler() methods.

2.1. HtmlPageDenyDecisionHandler

Use this handler to do deny decision by showing a template page.

Example usage:

  var handler = new HtmlPageDenyDecisionHandler();
  handler.setMacro("@MESSAGE@", "The request is denied.");
  handler.setPageId("error.html");
  context.setDecision(Decision.deny(handler));

2.2. HtmlPageChallengeDecisionHandler

Use this handler to do challenge decision by showing a template page.

Example usage:

  var handler = new HtmlPageChallengeDecisionHandler();
  handler.setMacro("@MESSAGE@", "Please guess a number between 0 and 99");
  handler.setMacro("@ACTION@", "https://myidp.com/oauth2/authorize");
  handler.setPageId("challenge.html");
  context.setDecision(Decision.challenge(handler));

2.3. RedirectDenyDecisionHandler

Use this handler to do deny decision by redirection.

Example usage:

  var handler = new RedirectDenyDecisionHandler();
  handler.setRedirectUri("https://www.tpp.com/denied.html");
  context.setDecision(Decision.deny(handler));

2.4. RedirectChallengeDecisionHandler

Use this handler to do challenge decision by redirection.

Example usage:

  var handler = new RedirectChallengeDecisionHandler();
  handler.setRedirectUri("https://www.myidp.com?PolicyId=urn:ibm:security:authentication:asf:totp");
  context.setDecision(Decision.challenge(handler));

3. Differences with ISVA Java implementation

Some differences exist in the methods that are supported for Attribute and Decision between ISVA OIDC Provider and ISVA.
The ISVA OIDC Provider implementation uses a JS object and slices instead of java.util.Map or java.util.List. Methods that are associated with java.util.Map or java.util.List are not available.

4. Redirection and Page Challenge Callback URL

Currently, in ISVA during a page challenge or redirection, users are expected to form the callback URL themselves.

  // Redirect challenge with Target URL
  var handler = new RedirectChallengeDecisionHandler(); 
  handler.setRedirectUri("https://www.myidp.com?PolicyId=urn:ibm:security:authentication:asf:totp&Target=https%3A%2F%2Fwww.myidp.com%2Foauth2%2Fauthorize?stateId=abcdefghijklmnopq");

  // Html challenge with Action macro
  var handler = new HtmlPageChallengeDecisionHandler();
  handler.setMacro("@MESSAGE@", "Please guess a number between 0 and 99");
  handler.setMacro("@ACTION@", "https://myidp.com/oauth2/authorize?stateId=abcdeghijklmnopq");

In ISVA OIDC Provider, users do not need to do so. For redirection, the Target is added automatically as one of the query strings.
For page handlers, two extra macros that are called @SELF_URL@ and @SELF_ENCODED_URL@ are added automatically. The difference between these two macros is that @SELF_ENCODED_URL@ is URL-encoded can be added into query string. These two macros can be used in the template page like any other macro.

For example,:

<html>
    <body>
        <h1>Page Challenge:</h1>
        <form method="POST" action="@SELF_URL@">
            @MESSAGE@ : <input type="number" name="guess">
            <br>
            <input type="submit" value="Submit">
        </form>
        <form method="GET" action="https://www.challenge.com?Target=@SELF_ENCODED_URL@">
            @MESSAGE@ : <input type="number" name="guess">
            <br>
            <input type="submit" value="Submit">
        </form>
    </body>
</html>