Execute authentication service policies in an Info Map

The AuthSvcClient class can be used to make internal calls to authentication service policies. This allows for extra customization of authentication flows without needing to contact the authentication service through HTTP requests within an Info Map.

There are three pairs of functions that can be called. This is dependent on the calling location. If a context variable is provided, the policy state and context will be stored in that context variable (InfoMap, Access Policy). Otherwise, use the non-context functions which will store the policy state and context in the DMAP.

When you are calling from an InfoMap policy, the following functions should be used with the InfoMap context variable:

executeInInfoMap(Context, String)
executeInInfoMap(Context, String, STSUniversalUser)

When you are calling from an Access Policy, the following functions should be used with the Access Policy context variable:

executeInAccessPolicy(Context, String)
executeInAccessPolicy(Context, String, STSUniversalUser)

When you are calling from other contexts, or for state-less invocation in the outer calling layer, the following functions will store state and context in the DMAP:

execute(String)
execute(String, STSUniversalUser)

See distributedMap to customize the DMAP store and other parameters.

To pass user credential information to the policy, use the functions that take a STSUniversalUser object. This will be required in most cases, for example when performing second factor authentication. Helpers have been provided to build the STSUniversalUser object, see getRequestTokenAttrAsStsuu (Context) and getSimpleSTSUU (String).

executeInInfoMap

public static String executeInInfoMap(
    Context context,
    String payload
)

Execute an authentication policy from within a running InfoMap. The policy request, response, session, and context objects are completely recreated from the given arguments, and stored separately from the objects of the already running policy (for example, the objects of the outer layer of policy execution, which contains the InfoMap).This method will store the policy context within the outer InfoMap context. No user credential information or request tokens are passed to the policy. See executeInInfoMap(Context, String, STSUniversalUser) to include user information.

This method executes the policy specified in the given payload. Use the following parameters:

context: The context variable provided to the Info Map. Required to save the inner policy execution context, and fetch locale for translated messages.
payload: The policy payload as stringified JSON. Must include either the policy ID (PolicyId), or a state ID (StateId), and other request parameters dependent on the policy being run. For example, the 'operation' parameter is required to complete most policies.
Returns:: A stringfied JSON payload that contains 3 parameters, status, page, and response. The status value will be set to one of three values, indicating the status of the policy: "pause", "abort", or "success". The response value will be set to the JSON payload returned from the policy.

executeInInfoMap

public static String execute(
    Context context,
    String payload,
    STSUniversalUser stsuu
)

Execute an authentication policy from within a running InfoMap, with the user identity specified by the input STSUniversalUser. The policy request, response, session, and context objects are completely recreated from the given arguments, and stored separately from the objects of the already running policy (for example, the objects of the outer layer of policy execution, which contains the InfoMap).

This method will store the policy context within the outer InfoMap context. Use the following parameters:

context: The context variable provided to the InfoMap. Required to save the inner policy execution context, and fetch locale for translated messages.
payload: The policy payload as stringified JSON. Must include either the policy ID (PolicyId), or a state ID (StateId), and other request parameters dependent on the policy being run. For example, the 'operation' parameter is required to complete most policies.
stsuu: The user identity to complete the policy with. Can be constructed as per usual for mapping rules, or by using one of the AuthSvcClient helper functions.
Returns:: A stringfied JSON payload that contains 3 parameters, status, page, and response. The status value will be set to one of three values, indicating the status of the policy: "pause", "abort", or "success". The response value will be set to the JSON payload returned from the policy.

executeInAccessPolicy

public static String executeInAccessPolicy(
    Context accessPolicyContext,
    String payload
)

Execute an authentication policy from within a running Access Policy. The policy request, response, session, and context objects are completely recreated from the given arguments, and stored separately from the objects of the already running context (for example, the new request object will not impact the Access Policy request object).

This method will store the policy context within the session from the Access Policy context.

No user credential information or request tokens are passed to the policy. See executeInAccessPolicy(Context, String, STSUniversalUser) to include user information.

Use the following parameters:

accessPolicyContext: The context variable provided to the Access Policy. Required to save the inner policy execution context, and fetch locale for translated messages.
payload: The policy payload as stringified JSON. Must include either policy ID (PolicyId), or a state ID (StateId), and other request parameters dependent on the policy being run. For example, the “operation” parameter is required to complete most policies.
Returns:: A stringfied JSON payload that contains 3 parameters, status, page, and response. The status value will be set to one of three values, indicating the status of the policy: "pause", "abort", or "success". The response value will be set to the JSON payload returned from the policy.

executeInAccessPolicy

public static String executeInAccessPolicy(
    Context accessPolicyContext,
    String payload,
    STSUniversalUser stsuu
)

This method will store the policy context within the session from the Access Policy context.

Use the following parameters:

accessPolicyContext: The context variable provided to the Access Policy. Required to save the inner policy execution context, and fetch locale for translated messages.
payload: The policy payload as stringified JSON. Must include either policy ID (PolicyId), or a state ID (StateId), and other request parameters dependent on the policy being run. For example, the “operation” parameter is required to complete most policies.
Returns:: A stringfied JSON payload that contains 3 parameters, status, page, and response. The status value will be set to one of three values, indicating the status of the policy: "pause", "abort", or "success". The response value will be set to the JSON payload returned from the policy.

execute

public static String execute(
    String payload
)

Execute an authentication policy from within a mapping rule. The policy request, response, session, and context objects are completely recreated from the given arguments, and stored separately from the objects of the already running context.

This method will store the policy context within the DMAP, which can be configured to use multiple different stores (for example, HVDB, Redis). No user credential information or request tokens are passed to the policy. See execute(String, STSUniversalUser) to include user information.

Use the following parameters:

payload: The policy payload as stringified JSON. Must include either the policy ID (PolicyId), or a state ID (StateId), and other request parameters dependent on the policy being run. For example, the 'operation' parameter is required to complete most policies.
Returns:: A stringfied JSON payload that contains 3 parameters, status, page, and response. The status value will be set to one of three values, indicating the status of the policy: "pause", "abort", or "success". The response value will be set to the JSON payload returned from the policy.

execute

public static String execute(
    String payload,
    STSUniversalUser stsuu
)

This method will store the policy context within the DMAP, which can be configured to use multiple different stores (for example, HVDB, Redis).

Use the following parameters:

payload: The policy payload as stringified JSON. Must include either the policy ID (PolicyId), or a state ID (StateId), and other request parameters dependent on the policy being run. For example, the 'operation' parameter is required to complete most policies.
stsuu: The user identity to complete the policy with. Can be constructed as per usual for mapping rules, or by using one of the AuthSvcClient helper functions.
Returns:: A stringfied JSON payload that contains 3 parameters, status, page, and response. The status value will be set to one of three values, indicating the status of the policy: "pause", "abort", or "success". The response value will be set to the JSON payload returned from the policy.

getRequestTokenAttrAsStsuu

public static STSUniversalUser getRequestTokenAttrAsStsuu(
    Context context
)

This method creates a new STSUniversalUser object with the attributes in any identity tokens available in the given InfoMap context.

Use the following parameters:

context: The context variable provided to the Info Map which contains identity attributes.
Returns:: The STSUniversalUser populated with identity attributes.

getSimpleSTSUU

public static STSUniversalUser getSimpleSTSUU(
    String username
)

This method creates a new STSUniversalUser object with the principal name set to the given username. Use the following parameters:

username: The username to set as the principal name of the new STSUniversalUser object.
Returns:: The STSUniversalUser populated with the principal name.

TOTP Example

For example, to perform TOTP authentication within the context of an Info Map, the following mapping rule can be used.

importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);
importClass(Packages.com.tivoli.am.fim.authsvc.local.client.AuthSvcClient);

var result = false;

var otp = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "otp");
IDMappingExtUtils.traceString("TOTP to verify: "+otp);

if(otp != null) {

    var jsonRequest = {
        "PolicyId": "urn:ibm:security:authentication:asf:totp",
        "otp":""+otp,
        "operation":"verify"
    };
    IDMappingExtUtils.traceString("AuthSvcClient JSON request: " + JSON.stringify(jsonRequest));
    var response = AuthSvcClient.executeInInfoMap(context, JSON.stringify(jsonRequest), AuthSvcClient.getSimpleSTSUU("testuser"));
    IDMappingExtUtils.traceString("AuthSvcClient JSON response: " + response);

    var jsonResponse = JSON.parse(response);
    if(jsonResponse.status == "success") {
        // Policy completed successfully, return true.
        result = true;
        context.set(Scope.SESSION, "urn:ibm:security:asf:response:token:attributes", "username", "testuser");
    } else {
        // Policy failed, prompt for TOTP again.
        macros.put("@ERROR_MESSAGE@", jsonResponse.response.message);
        page.setValue("/authsvc/authenticator/totp/login.html");
    }
} else {
    // Return a page to gather the TOTP
    page.setValue("/authsvc/authenticator/totp/login.html");
}

// Set result. Either true for stop running this rule, or false for run the rule again.
success.setValue(result);
IDMappingExtUtils.traceString("Result of mapping rule: "+result);