Increasing Authorization for a Single Transaction

Transactional authorization improves security by requiring a user to perform additional actions when trying to access a resource protected by an AM policy. For example, they must reauthenticate to an authentication module or respond to a push notification on their mobile device.

Performing the additional action successfully grants access to the protected resource, but only once. Additional attempts to access the resource require the user to perform the configured actions again.

This section builds on the example in "Stepping Up the Authentication Level for an AM Session", adding a simple authorization policy with a Transaction environment condition. Each time the user-agent tries to access the protected resource, the user must reauthenticate to an authentication module by providing a verification code.

This feature is supported with AM 5.5 and later versions.

Use Transactional Authorization

Before you start, configure AM as described in "Set Up an AM Authentication Chain". The IG configuration is not changed.

  1. In the AM console, add a new Environment condition:

    1. Select the policy set:

      • For SSO, select Authorization > Policy Sets > PEP-SSO.

      • For CDSSO, select Authorization > Policy Sets > PEP-CDSSO.

    2. In the IG policy, select Environments and add another environment condition:

      • All of

      • Type: Transaction

      • Authentication strategy: Authenticate To Module

      • Strategy specifier: TxVerificationCodeLevel5

  2. Set up client-side and server-side scripts:

    1. Select Scripts > New Script, and add the following client-side script:

      • Name: Tx Scripted Module - Client Side

      • Script Type: Client-side Authentication

      /*
       * Copyright 2018 ForgeRock AS. All Rights Reserved
       *
       * Use of this code requires a commercial software license with ForgeRock AS.
       * or with one of its affiliates. All use shall be exclusively subject
       * to such license between the licensee and ForgeRock AS.
       */
      autoSubmitDelay = 60000;
      
      function callback() {
          var parent = document.createElement("div");
          parent.className = "form-group";
      
          var label = document.createElement("label");
          label.className = "sr-only separator";
          label.setAttribute("for", "answer");
          label.innerText = "Verification Code";
          parent.appendChild(label);
      
          var input = document.createElement("input");
          input.className = "form-control input-lg";
          input.type = "text";
          input.placeholder = "Enter your TX code";
          input.name = "answer";
          input.id = "answer";
          input.value = "";
          input.oninput = function(event) {
              var element = document.getElementById("clientScriptOutputData");
              if (!element.value || element.value == "clientScriptOutputData") element.value = "{}";
              var json = JSON.parse(element.value);
              json["answer"] = event.target.value;
              element.value = JSON.stringify(json);
          };
          parent.appendChild(input);
      
          var fieldset = document.forms[0].getElementsByTagName("fieldset")[0];
          fieldset.prepend(parent);
      }
      
      if (document.readyState !== 'loading') {
          callback();
      } else {
          document.addEventListener("DOMContentLoaded", callback);
      }

      This client-side script adds a field to the AM form, in which the user is required to enter a TX code. The script formats the entered code as a JSON object, as required by the server-side script.

    2. Select Scripts > New Script, and add the following server side script:

      • Name: Tx Scripted Module - Server Side

      • Script Type: Server-side Authentication

      username = 'demo'
      logger.error('username: ' + username)
      
      // Test whether the user 'demo' enters the correct validation code
      data = JSON.parse(clientScriptOutputData);
      answer = data.answer;
      
      if (answer !== '789') {
        logger.error('Authentication Failed !!')
        authState = FAILED;
      } else {
        logger.error('Authenticated !!')
        authState = SUCCESS;
      }

      This server-side script tests that the user demo has entered 789 as the verification code.

  3. Add an authentication module:

    1. Select Authentication > Modules, and add a module with the following settings:

      • Name: TxVerificationCodeLevel5

      • Type: Scripted Module

    2. In the authentication module, enable the option for client-side script, and select the following options:

      • Client-side Script: Tx Scripted Module - Client Side

      • Server-side Script: Tx Scripted Module - Server Side

      • Authentication Level: 5

Test the Setup
  1. Log out of AM.

  2. Go to your route:

    If you have not previously authenticated to AM, the SingleSignOnFilter redirects the request to AM for authentication.

  3. Log in to AM as user demo, password Ch4ng31t.

    AM creates a session with the default authentication level 0, and IG requests a policy decision.

  4. Enter the verification code 123456 to upgrade the authorization level for the session to 1.

    The authentication module you configured for transactional authorization requires authentication level 5, so AM issues a TransactionConditionAdvice.

  5. In the transaction upgrade window, enter the verification code 789.

    AM upgrades the authentication level for this policy evaluation to 5, and then returns a policy decision that grants a one-time access to the sample application. If you try to access the sample application again, you must enter the code again.

Read a different version of :