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

Class 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

      All Methods Static Methods Concrete Methods 
      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.
      static void JSONToSession​(java.lang.String jsonString, CleanableSession session)  
      static void prepareContextFromJson​(JSONObject json, AuthSvcClientContextView contextView)  
      static JSONObject sessionToJSON​(CleanableSession session)  

      • 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

      • prepareContextFromJson

        public static void prepareContextFromJson​(JSONObject json,
                                          AuthSvcClientContextView contextView)
                                   throws BadRequestException,
                                          java.io.IOException
        Throws:
        BadRequestException
        java.io.IOException

      • sessionToJSON

        public static JSONObject sessionToJSON​(CleanableSession session)

      • JSONToSession

        public static void JSONToSession​(java.lang.String jsonString,
                                 CleanableSession session)