Session Upgrade

1. Configure an authentication tree or chain to validate users' credentials during session upgrade.

   Authentication trees and chains do not require additional configuration to perform session upgrade. However, because session upgrade is a mechanism which may be used to grant users access to sensitive information, you should consider configuring a strong authentication method such as multi-factor authentication. Also, you may want to consider how long-lived sessions in your environment are. For example, if users should only have access to the protected resource to perform an operation, such as check the balance of an account, you may want to consider implementing transactional authorization instead.

   • For more information, see Transactional Authorization.

   • For more information about configuring authentication trees and chains, see the Authentication and Single Sign-On Guide.

2. Configure at least one of the following environment conditions in the authentication policy you created as part of the prerequisites:

   Authentication Level (greater than or equal to) (Authentication modules only)

   Use this condition to present a list of authentication chains that provide a greater or equal authentication level to the one specified in the condition. The user selects their service of choice if multiple chains are able to meet the criteria of the condition. For example, the following policy requires a chain that provides authentication level 3 or greater:

   Session Upgrade by Authentication Level (greater than or equal to)

   

   
   

   Tip

   For more information about configuring the authentication level by authentication module, see "About Authentication Levels for Chains".

   Authentication by Service

   Use this condition to specify the chains or authentication trees to which the user needs to use to authenticate. For example, the following policy requires the user to log in with the Example tree:

   Session Upgrade by Service

   

   
   

   Note that the names of the authentication trees and chains are case-sensitive.

   Authentication by Module Instance (Authentication modules only)

   Use this condition to enforce that a user has gone through a specific authentication module. For example, the following policy requires the user to log in with the DataStore module:

   Session Upgrade by Module Instance

   

   
   

   Note

   The examples feature simple policy conditions. For more information about configuring policies and environment conditions, see Configuring Policies.

3. Test session upgrade:

   • To test session upgrade with a browser, see "To Perform Session Upgrade Using a Browser".

   • To test session upgrade with REST, see "To Perform Session Upgrade Using REST".

To upgrade a session using a browser, perform the following steps:

1. Ensure you have performed the tasks in Session Upgrade Prerequisites and "To Configure the Environment for Session Upgrade".

2. In a browser, navigate to your protected resource. For example, http://www.example.com:9090/sample.

   The agent redirects the browser to the AM login screen.

3. Authenticate to AM as the demo user.

   AM requires additional credentials to grant access to the resource. For example, if you set the policy environment condition to Authentication by Service and Example, you will be required to log in again as the demo user.

4. Authenticate as the demo user. Note that providing credentials for a different user will fail.

   You can now access the protected resource.

To upgrade a session using REST, perform the following steps:

1. Ensure you have performed the tasks in Session Upgrade Prerequisites and "To Configure the Environment for Session Upgrade".

   Note

   This example uses composite advice with an authentication level condition, which only applies to authentication chains.

2. Log in with an administrative user that has permission to evaluate policies, such as amAdmin. For example:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: amadmin" \
   --header "X-OpenAM-Password: password" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/authenticate'
        {
       "tokenId":"AQIC5wM2...",
       "successUrl":"/openam/console",
       "realm":"/"
   }

   Tip

   You can also assign privileges to a user to evaluate policies. For more information, see "To Allow a User to Evaluate Policies".

3. Log in with the user that should access the resources. For example, log in as the demo user:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "X-OpenAM-Username: demo" \
   --header "X-OpenAM-Password: Ch4ng31t" \
   --header "Accept-API-Version: resource=2.0, protocol=1.0" \
   'https://openam.example.com:8443/openam/json/realms/root/authenticate'
        {
       "tokenId":"AQIC5wM...TU3OQ*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

4. Request a policy decision from AM for a protected resource, in this case, http://openam.example.com:9090/sample. The iPlanetDirectoryPro header sets the SSO token for the administrative user, and the subject element of the payload sets the SSO token for the demo user:

   $ curl --request POST \
    --header "Content-Type: application/json" \
    --header "iPlanetDirectoryPro: AQIC5wM2..." \
    --header "Accept-API-Version:protocol=1.0,resource=2.1" \
    --data '{
    "resources": [
        "http://www.example.com:9090/sample"
    ],
    "application": "iPlanetAMWebAgentService",
    "subject": { "ssoToken": "AQIC5wM...TU3OQ*"}
   }' \
   "https://openam.example.com:8443/openam/json/policies?_action=evaluate"
        [
      {
         "resource":"http://www.example.com:9090/sample",
         "actions":{
   
         },
         "attributes":{
   
         },
         "advices":{
            "AuthLevelConditionAdvice":[
               "3"
            ]
         },
         "ttl":9223372036854775807
      }
   ]

   AM returns with advice, which means the user must present additional credentials to access that resource.

   For more information about requesting policy decision, see "Requesting Policy Decisions Using REST".

5. Format the advice as XML, without spaces or line breaks. The following example is spaced and tabulated for readability purposes only:

   <Advices>
       <AttributeValuePair>
          <Attribute name="AuthLevelConditionAdvice"/>
          <Value>3</Value>
       </AttributeValuePair>
   </Advices>

   Note

   The example shows the XML render of a single advice. Depending on the conditions configured in the policy, the advice may contain several lines. For more information about advices, see "Policy Decision Advice".

6. URL-encode the XML advice. For example: %3CAdvices%3E%3CAttributeValuePair%3E%3CAttribute%20name%3D%22AuthLevelConditionAdvice%22%2F%3E%3CValue%3E3%3C%2FValue%3E%3C%2FAttributeValuePair%3E%3C%2FAdvices%3E.

   Ensure there are no spaces between tags when URL-encoding the advice.

7. Call AM's authenticate endpoint to request information about the advice. Use the following details:

   • Add the following URL parameters:

     • authIndexType=composite_advice

     • authIndexValue=URL-encoded_Advice

   • Set the iPlanetDirectoryPro cookie as the SSO token for the demo user.

   For example:

   $ curl --request POST \
   --header "Content-Type: application/json" \
   --cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
   --header "Accept-API-Version: protocol=1.0,resource=2.1" \
   'https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=composite_advice&authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E...'
        {
      "authId":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZ...",
      "template":"",
      "stage":"DataStore1",
      "header":"Sign in",
      "callbacks":[
         {
            "type":"NameCallback",
            "output":[
               {
                  "name":"prompt",
                  "value":"User Name:"
               }
            ],
            "input":[
               {
                  "name":"IDToken1",
                  "value":""
               }
            ]
         },
         {
            "type":"PasswordCallback",
            "output":[
               {
                  "name":"prompt",
                  "value":"Password:"
               }
            ],
            "input":[
               {
                  "name":"IDToken2",
                  "value":""
               }
            ]
         }
      ]
   }

   AM returns information about how the user can authenticate in a callback; in this case, providing a username and password. For a list of possible callbacks, and more information about the /json/authenticate endpoint, see Authenticating (REST).

8. Call AM's authenticate endpoint to provide the required callback information. Use the following details:

   • Add the following URL query parameters:

     • authIndexType=composite_advice

     • authIndexValue=URL-encoded_Advice

   • Set the iPlanetDirectoryPro cookie as the SSO token for the demo user.

   • Send as data the complete payload AM returned in the previous step, ensuring you provide the requested callback information.

   In this example, provide the username and password for the demo user in the input objects, as follows:

   $ curl --request POST \
        --header 'Content-Type: application/json' \
        --header "Accept-API-Version: protocol=1.0,resource=2.1" \
        --cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
        --data '{
                   "authId":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZ...",
                   "template":"",
                   "stage":"DataStore1",
                   "header":"Sign in",
                   "callbacks":[
                      {
                         "type":"NameCallback",
                         "output":[
                            {
                               "name":"prompt",
                               "value":"User Name:"
                            }
                         ],
                         "input":[
                            {
                               "name":"IDToken1",
                               "value":"demo"
                            }
                         ]
                      },
                      {
                         "type":"PasswordCallback",
                         "output":[
                            {
                               "name":"prompt",
                               "value":"Password:"
                            }
                         ],
                         "input":[
                            {
                               "name":"IDToken2",
                               "value":"Ch4ng31t"
                            }
                         ]
                      }
                   ]
                }
              }' \
        'https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=composite_advice&authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E...'
        {
      "tokenId":"wpU01SaTq4X2x...NDVFMAAlMxAAA.*",
      "successUrl":"/openam/console",
      "realm":"/"
   }

   Note that AM returns a new SSO token for the demo user.

9. Request a new policy decision from AM for the protected resource. The iPlanetDirectoryPro header sets the SSO token for the administrative user, and the subject element of the payload sets the new SSO token for the demo user:

   $ curl --request POST \
   --header "Content-Type: application/json" \
   --header "iPlanetDirectoryPro: AQIC5wM2..." \
   --header "Accept-API-Version:protocol=1.0,resource=2.1" \
   --data '{
      "resources":[
         "http://www.example.com:9090/sample"
      ],
      "application":"iPlanetAMWebAgentService",
      "subject":{
         "ssoToken":"wpU01SaTq4X2x...NDVFMAAlMxAAA.*"
      }
   }' \
   "https://openam.example.com:8443/openam/json/policies?_action=evaluate"
        [
      {
         "resource":"http://www.example.com:9090/sample",
         "actions":{
            "POST":true,
            "GET":true
         },
         "attributes":{
   
         },
         "advices":{
   
         },
         "ttl":9223372036854775807
      }
   ]

   AM returns that demo can perform POST and GET operations on the resource.