Stepping Up the Authentication Level for an AM Session

When you step up the authentication level for an AM session, the authorization is verified and then captured as part of the AM session, and the user-agent is authorized to that authentication level for the duration of the AM session.

This section uses the policies you created in "Enforcing AM Policy Decisions In the Same Domain" and "Enforcing AM Policy Decisions In Different Domains", adding an authorization policy with a Authentication by Service environment condition. Except for the paths where noted, procedures for single domain and cross-domain are the same.

After the user-agent redirects the user to AM, if the user is not already authenticated they are presented with a login page. If the user is already authenticated, or after they authenticate, they are presented with a second page asking for a verification code to meet the AuthenticateToService environment condition.

Set Up an AM Authentication Chain

Before you start, set up one of the following examples:

  1. In the AM console, add an environment condition to the policy:

    1. Select a policy set:

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

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

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

      • All of

      • Type: Authentication by Service

      • Authenticate to Service: VerificationCodeLevel1

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

    1. Select Scripts > Scripted Module - Client Side, and replace the default script with the following script:

      /*
       * 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 verification 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);
      }
      
      spinner.hideSpinner();
      autoSubmitDelay = 60000;
      $(document).ready(function() {
        fs = $(document.forms[0]).find("fieldset");
        strUI = '<div class="form-group"> \
                 <label class="sr-only separator" for="answer"> \
                 Verification Code</label><input onchange="s=$(\'#clientScriptOutputData\')[0]; \
                 if (!s.value) s.value=\'{}\'; d=JSON.parse(s.value); d[\'answer\']=value; \
                 s.value=JSON.stringify(d);" id="answer" class="form-control input-lg" type="text" \
                 placeholder="Enter your verification code" value="" name="answer"></input></div>';
        $(fs).prepend(strUI);
      });

      Leave all other values as default.

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

    2. Select Scripts > Scripted Module - Server Side, and replace the default script with the following script:

      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 !== '123456') {
        logger.error('Authentication Failed !!')
        authState = FAILED;
      } else {
        logger.error('Authenticated !!')
        authState = SUCCESS;
      }

      Leave all other values as default.

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

  3. Add an authentication module:

    1. In the top level realm, select Authentication > Modules, and add a module with the following settings:

      • Name: VerificationCodeLevel1

      • Type: Scripted Module

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

      • Client-side Script: Scripted Module - Client Side

      • Server-side Script: Scripted Module - Server Side

      • Authentication Level: 1

  4. Add the authentication module to an authentication chain:

    1. Select Authentication > Chains, and add a chain called VerificationCodeLevel1.

    2. Add a module with the following settings:

      • Select Module: VerificationCodeLevel1

      • Select Criteria: Required

Test the Setup
  1. Log out of AM.

  2. Access the 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.

    The updated policy requires authentication level 1, which is higher than the AM session's current authentication level. AM issues a redirect with a AuthenticateToServiceConditionAdvice to authenticate at level 1.

  4. In the session upgrade window, enter the verification code 123456.

    AM upgrades the authentication level for the session to 1, and grants access to the sample application. If you try to access the sample application again in the same session, you don't need to provide the verification code.

Read a different version of :