IG 7.1.2

Harden Authorization With Advice From AM

To protect sensitive resources, AM policies can be configured with additional conditions to harden the authorization. When AM communicates these policy decisions to IG, the decision includes advices to indicate what extra conditions the user must meet.

Conditions can include requirements to access the resource over a secure channel, access during working hours, or to authenticate again at a higher authentication level. For more information, see AM’s Authorization Guide.

The following sections build on the policies in Enforce Policy Decisions From AM to step up the authentication level:

Step 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 Enforce AM Policy Decisions In the Same Domain and Enforce 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.

Before you start, set up one of the following examples in Enforce AM Policy Decisions In the Same Domain or Enforce AM Policy Decisions In Different Domains.

  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:

      • For AM 6 and later versions

      • For AM 5 and earlier versions

      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. 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

    3. 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

  4. Test the setup:

    1. Log out of AM.

    2. Access the route:

    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.

Increase 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 Step 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.

Before you start, configure AM as described in Step Up the Authentication Level for an AM Session. 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

        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

  4. Test the setup:

    1. Log out of AM.

    2. Access your route:

    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.

Copyright © 2010-2023 ForgeRock, all rights reserved.