Package com.tivoli.am.fim.authsvc.local.client

Class AuthSvcClient

java.lang.Object

com.tivoli.am.fim.authsvc.local.client.AuthSvcClient

public class AuthSvcClient
extends java.lang.Object

Use this class to make internal calls to AAC authentication service policies. This allows for extra customisation of authentication flows without needing to contact the authentication service via HTTP.

There are 3 pairs of execute functions that can be called, 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 calling from an InfoMap policy, the following functions should be used with the InfoMap context variable:
#executeInInfoMap(Context, String)
#executeInInfoMap(Context, String, STSUniversalUser)

When 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 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)

Note: See the Advanced Configuration distributedMap configuration entries to customise 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 the majority of cases, for example when performing second factor authentication. Helpers have been provided to build the STSUniversalUser object, see #getRequestTokenAttrAsStsuu(Context) and getSimpleSTSUU(String)

Method Summary

Modifier and Type	Method	Description
static java.lang.String	execute(java.lang.String payload)	Execute an authentication policy from within a mapping rule.
static java.lang.String	execute(java.lang.String payload, STSUniversalUser stsuu)	Execute an authentication policy from within a mapping rule.
static java.lang.String	executeInAccessPolicy(Context accessPolicyContext, java.lang.String payload)	Execute an authentication policy from within a running Access Policy.
static java.lang.String	executeInAccessPolicy(Context accessPolicyContext, java.lang.String payload, STSUniversalUser stsuu)	Execute an authentication policy from within a running Access Policy.
static java.lang.String	executeInInfoMap(Context context, java.lang.String payload)	Execute an authentication policy from within a running InfoMap.
static java.lang.String	executeInInfoMap(Context context, java.lang.String payload, STSUniversalUser stsuu)	Execute an authentication policy from within a running InfoMap.
static STSUniversalUser	getRequestTokenAttrAsStsuu(Context context)	Creates a new STSUniversalUser object with the attributes in any identity tokens available in the given InfoMap context.
static STSUniversalUser	getSimpleSTSUU(java.lang.String username)	Creates a new STSUniversalUser object with the principal name set to the given username.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

execute

public static java.lang.String execute(java.lang.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 (i.e. HVDB, Redis).

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

Example input payload with PolicyId:
{
  "PolicyId": "urn:ibm:security:authentication:asf:totp"
  "operation": "verify",
  "otp": "123456"
}

Example input payload with StateId:
{
  "StateId": "BQ4TUc6sIeuprD3ToVBCumClgcAwtGLlPPbdM0A49BBcCcriF2Pz85H5bQmz8KKPHXp2XAfdQMPB7MYTAJsEqu3Fu2xcN5j..."
  "operation": "verify",
  "otp": "123456"
}

Example response payload:
{
  "status":"pause",
  "page":"\/authsvc\/authenticator\/totp\/login.html",
  "response": {
    "mechanism":"urn:ibm:security:authentication:asf:mechanism:totp",
    "state":"dvsPJX3HPLufKsflRcOEZqwYODt1wpRjjq9n4ewjxeeTlRJCs7d5x7HRa02OD8t9RAzAtqwXU4ILO09RqpeSb6TlulqKxdu...",
    "message":"",
    "exceptionMsg":""
  }
}
 

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 three 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 page value will be set to the template page returned by the policy that was run, or empty string if no template returned. The response value will be set to the JSON payload returned from the policy.

executeInInfoMap

public static java.lang.String executeInInfoMap(Context context,
                                                java.lang.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 (i.e. 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.

Example input payload with PolicyId:
{
  "PolicyId": "urn:ibm:security:authentication:asf:totp"
  "operation": "verify",
  "otp": "123456"
}

Example input payload with StateId:
{
  "StateId": "BQ4TUc6sIeuprD3ToVBCumClgcAwtGLlPPbdM0A49BBcCcriF2Pz85H5bQmz8KKPHXp2XAfdQMPB7MYTAJsEqu3Fu2xcN5j..."
  "operation": "verify",
  "otp": "123456"
}

Example response payload:
{
  "status":"pause",
  "page":"\/authsvc\/authenticator\/totp\/login.html",
  "response": {
    "mechanism":"urn:ibm:security:authentication:asf:mechanism:totp",
    "state":"dvsPJX3HPLufKsflRcOEZqwYODt1wpRjjq9n4ewjxeeTlRJCs7d5x7HRa02OD8t9RAzAtqwXU4ILO09RqpeSb6TlulqKxdu...",
    "message":"",
    "exceptionMsg":""
  }
}
 

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 three 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 page value will be set to the template page returned by the policy that was run, or empty string if no template returned. The response value will be set to the JSON payload returned from the policy.

executeInAccessPolicy

public static java.lang.String executeInAccessPolicy(Context accessPolicyContext,
                                                     java.lang.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 (i.e. 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(com.ibm.security.access.policy.Context, String, STSUniversalUser) to include user information.

Example input payload with PolicyId:
{
  "PolicyId": "urn:ibm:security:authentication:asf:totp"
  "operation": "verify",
  "otp": "123456"
}

Example input payload with StateId:
{
  "StateId": "BQ4TUc6sIeuprD3ToVBCumClgcAwtGLlPPbdM0A49BBcCcriF2Pz85H5bQmz8KKPHXp2XAfdQMPB7MYTAJsEqu3Fu2xcN5j..."
  "operation": "verify",
  "otp": "123456"
}

Example response payload:
{
  "status":"pause",
  "page":"\/authsvc\/authenticator\/totp\/login.html",
  "response": {
    "mechanism":"urn:ibm:security:authentication:asf:mechanism:totp",
    "state":"dvsPJX3HPLufKsflRcOEZqwYODt1wpRjjq9n4ewjxeeTlRJCs7d5x7HRa02OD8t9RAzAtqwXU4ILO09RqpeSb6TlulqKxdu...",
    "message":"",
    "exceptionMsg":""
  }
}
 

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 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 three 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 page value will be set to the template page returned by the policy that was run, or empty string if no template returned. The response value will be set to the JSON payload returned from the policy.

execute

public static java.lang.String execute(java.lang.String payload,
                                       STSUniversalUser stsuu)

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 (i.e. HVDB, Redis).

Example input payload with PolicyId:
{
  "PolicyId": "urn:ibm:security:authentication:asf:totp"
  "operation": "verify",
  "otp": "123456"
}

Example input payload with StateId:
{
  "StateId": "BQ4TUc6sIeuprD3ToVBCumClgcAwtGLlPPbdM0A49BBcCcriF2Pz85H5bQmz8KKPHXp2XAfdQMPB7MYTAJsEqu3Fu2xcN5j..."
  "operation": "verify",
  "otp": "123456"
}

Example response payload:
{
  "status":"pause",
  "page":"\/authsvc\/authenticator\/totp\/login.html",
  "response": {
    "mechanism":"urn:ibm:security:authentication:asf:mechanism:totp",
    "state":"dvsPJX3HPLufKsflRcOEZqwYODt1wpRjjq9n4ewjxeeTlRJCs7d5x7HRa02OD8t9RAzAtqwXU4ILO09RqpeSb6TlulqKxdu...",
    "message":"",
    "exceptionMsg":""
  }
}
 

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 using one of the AuthSvcClient helper functions. See #getRequestTokenAttrAsStsuu(Context) and getSimpleSTSUU(String)

Returns:

A stringfied JSON payload that contains three 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 page value will be set to the template page returned by the policy that was run, or empty string if no template returned. The response value will be set to the JSON payload returned from the policy.

executeInInfoMap

public static java.lang.String executeInInfoMap(Context context,
                                                java.lang.String payload,
                                                STSUniversalUser stsuu)

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 (i.e. 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.

Example input payload with PolicyId:
{
  "PolicyId": "urn:ibm:security:authentication:asf:totp"
  "operation": "verify",
  "otp": "123456"
}

Example input payload with StateId:
{
  "StateId": "BQ4TUc6sIeuprD3ToVBCumClgcAwtGLlPPbdM0A49BBcCcriF2Pz85H5bQmz8KKPHXp2XAfdQMPB7MYTAJsEqu3Fu2xcN5j..."
  "operation": "verify",
  "otp": "123456"
}

Example response payload:
{
  "status":"pause",
  "page":"\/authsvc\/authenticator\/totp\/login.html",
  "response": {
    "mechanism":"urn:ibm:security:authentication:asf:mechanism:totp",
    "state":"dvsPJX3HPLufKsflRcOEZqwYODt1wpRjjq9n4ewjxeeTlRJCs7d5x7HRa02OD8t9RAzAtqwXU4ILO09RqpeSb6TlulqKxdu...",
    "message":"",
    "exceptionMsg":""
  }
}
 

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.

stsuu - The user identity to complete the policy with. Can be constructed as per usual for mapping rules, or using one of the AuthSvcClient helper functions. See #getRequestTokenAttrAsStsuu(Context) and getSimpleSTSUU(String)

Returns:

A stringfied JSON payload that contains three 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 page value will be set to the template page returned by the policy that was run, or empty string if no template returned. The response value will be set to the JSON payload returned from the policy.

executeInAccessPolicy

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

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 (i.e. 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.

Example input payload with PolicyId:
{
  "PolicyId": "urn:ibm:security:authentication:asf:totp"
  "operation": "verify",
  "otp": "123456"
}

Example input payload with StateId:
{
  "StateId": "BQ4TUc6sIeuprD3ToVBCumClgcAwtGLlPPbdM0A49BBcCcriF2Pz85H5bQmz8KKPHXp2XAfdQMPB7MYTAJsEqu3Fu2xcN5j..."
  "operation": "verify",
  "otp": "123456"
}

Example response payload:
{
  "status":"pause",
  "page":"\/authsvc\/authenticator\/totp\/login.html",
  "response": {
    "mechanism":"urn:ibm:security:authentication:asf:mechanism:totp",
    "state":"dvsPJX3HPLufKsflRcOEZqwYODt1wpRjjq9n4ewjxeeTlRJCs7d5x7HRa02OD8t9RAzAtqwXU4ILO09RqpeSb6TlulqKxdu...",
    "message":"",
    "exceptionMsg":""
  }
}
 

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 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 using one of the AuthSvcClient helper functions. See #getRequestTokenAttrAsStsuu(Context) and getSimpleSTSUU(String)

Returns:

A stringfied JSON payload that contains three 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 page value will be set to the template page returned by the policy that was run, or empty string if no template returned. The response value will be set to the JSON payload returned from the policy.

getRequestTokenAttrAsStsuu

public static STSUniversalUser getRequestTokenAttrAsStsuu(Context context)

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

Parameters:

context - The context variable provided to the Info Map. Required to fetch identity tokens.

Returns:

The STSUniversalUser populated with identity attributes

getSimpleSTSUU

public static STSUniversalUser getSimpleSTSUU(java.lang.String username)

Creates a new STSUniversalUser object with the principal name set to the given username.

Parameters:

username - The username to set as the principal name of the new STSUniversalUser object.

Returns:

The STSUniversalUser populated with the principal name