Identity Cloud

Sessions

This guide covers concepts and implementation procedures to manage sessions in your AM environment.

This guide is written for administrators configuring AM’s authentication and authorization components.

ForgeRockĀ® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Sessions and cookies

A session in AM is a token that represents a usually interactive exchange of information between AM and a user or identity.

AM creates an authentication session to track the user’s authentication progress through an authentication chain or tree. Once the user has authenticated, AM creates a session to manage the user’s or entity’s access to resources.

Sessions require the user or client to be able to hold on to cookies. Cookies provided by AM’s session are a reference to where the session is stored; the Core Token Service (CTS) token store.

AM provides a unique, pseudo-random session cookie name for each tenant. Throughout the AM documentation, the tenant session cookie name is referred to as <session-cookie-name> to denote this generated value.

  1. Open the Identity Cloud admin UI.

  2. From the Tenant menu, select Tenant Settings > Global Settings.

  3. View or copy the Cookie field value. This is used in HTTP header values in AM API requests, for example, in the OAuth 2.0 authorization grant flow.

AM session-related services are stateless unless otherwise indicated; they do not hold any session information local to the AM instances. Instead, they store session information either in the CTS token store. This architecture allows you to scale your AM infrastructure horizontally since any server in the deployment can satisfy any session’s request.

CTS-based sessions

CTS-based sessions reside in the CTS token store and can be cached in memory on one or more AM servers to improve system performance.

If the session request is redirected to an AM server that does not have the session cached, that server must retrieve the session from the CTS token store.

AM sends a reference to the session to the client, but the reference does not contain any of the session state information. AM can modify a session during its lifetime without changing the client’s reference to the session.

During authentication, the session reference is returned to the client after a call to the authenticate endpoint and stored in the authId object of the JSON response.

AM maintains the authenticating user’s session in the CTS token store. After the authentication flow has completed, if the realm to which the user has authenticated is configured for client-based sessions, AM returns session state to the client and deletes the CTS-based session.

Authentication session allowlisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks. For more information about the allowlisting setting, see Trees.

Once the user is authenticated, the session reference is known as an SSO token. For browser clients, AM sets a cookie in the browser that contains the session reference. For REST clients, AM returns the session reference in response to calls to the authentication endpoint.

For more information about session cookies, see Sessions and cookies.

Session termination

AM manages active sessions, allowing single sign-on when authenticated users attempt to access system resources in AM’s control.

AM ensures that user sessions are terminated when a configured timeout is reached, or when AM users perform actions that cause session termination. Session termination effectively logs the user out of all systems protected by AM.

With CTS-based sessions, AM terminates sessions in four situations:

  • When a user explicitly logs out.

  • When an administrator monitoring sessions explicitly terminates a session.

  • When a session exceeds the maximum time-to-live.

  • When a user is idle for longer than the maximum session idle time.

Under these circumstances, AM responds by removing CTS-based sessions from the CTS token store and from AM server memory caches. With the user’s session no longer present in CTS, AM forces the user to reauthenticate during subsequent attempts to access resources protected by AM.

When a user explicitly logs out of AM, AM also attempts to invalidate the tenant session cookie in users' browsers by sending a Set-Cookie header with an invalid session ID and a cookie expiration time that is in the past. In the case of administrator session termination and session timeout, AM cannot invalidate the tenant session cookie until the next time the user accesses AM.

Configure session maximum time-to-live

When configuring the maximum session time-to-live, you must balance security and user experience. Depending on your application, it may be acceptable for your users to log in once a month. Financial applications, for example, tend to expire their sessions in less than an hour.

The longer a session is valid, the larger the window during which a malicious user could impersonate a user if they were able to hijack a session cookie.

  1. In the AM admin UI, go to Realms > Realm Name > Services > Session > Dynamic Attributes.

    Note that you can also change maximum session time settings globally for the AM site by going to Configure > Sessions > Dynamic Attributes.

  2. On the Maximum Session Time property, configure a value suitable for your environment.

  3. Save your changes.

Configure CTS-based session idle timeout

Consider a user with a valid session navigating through pages or making changes to the configuration. If for any reason they leave their desk and their computer remains open, a malicious user could take the opportunity to impersonate them.

Session idle timeout can help mitigate those situations, by logging out users after a specified duration of inactivity. Session idle timeout can only be used in realms configured for CTS-based sessions.

  1. In the AM admin UI, go to Realms > Realm Name > Services > Session > Dynamic Attributes.

    Note that you can also change idle timeout settings globally for the AM site by navigating to Configure > Sessions > Dynamic Attributes.

  2. On the Maximum Time Idle property, configure a value suitable for your environment.

  3. Save your changes.

Manage sessions over REST

AM provides REST APIs under /json/sessions for the following use cases:

Get information about sessions over REST

To get information about a session, send an HTTP POST request to the /json/sessions/ endpoint, using the getSessionInfo action. This endpoint returns information about the session token provided in the <session-cookie-name> header by default. To get information about a different session token, include it in the POST body as the value of the tokenId parameter.

The following example shows an administrative user passing in their session token in the <session-cookie-name> header, and the session token of the demo user as the tokenId parameter:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=4.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=getSessionInfo'
{
    "username": "demo",
    "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
    "realm": "/",
    "latestAccessTime": "2020-02-21T14:31:18Z",
    "maxIdleExpirationTime": "2020-02-21T15:01:18Z",
    "maxSessionExpirationTime": "2020-02-21T16:29:56Z",
    "properties": {
        "AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932"
    }
}

The getSessionInfo action does not refresh the session idle timeout. To obtain session information about a CTS-based session and also reset the idle timeout, use the getSessionInfoAndResetIdleTime endpoint, as follows.

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=getSessionInfoAndResetIdleTime'
{
    "username": "demo",
    "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
    "realm": "/",
    "latestAccessTime": "2020-02-21T14:32:49Z",
    "maxIdleExpirationTime": "2020-02-21T15:02:49Z",
    "maxSessionExpirationTime": "2020-02-21T16:29:56Z",
    "properties": {
        "AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932"
    }
}

In order to return the AMCtxId property in the session query response, as in this example, you must set AMCtxId in the Session Properties to return to session queries setting, under Realms > Realm Name > Services > Session Property Whitelist Service.

Validate sessions over REST

To check whether a session token is valid over REST, perform an HTTP POST to the /json/sessions/ endpoint using the validate action. Provide the session token in the POST data as the value of the tokenId parameter. You must also provide the session token of an administrative user in the <session-cookie-name> header.

If you don’t specify the tokenId parameter, the session in the <session-cookie-name> header is validated instead.

The following example shows an administrative user, such as amAdmin, validating a session token for the demo user:

$ curl \
--request POST \
--header "Content-type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=2.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions?_action=validate'

If the session token is valid, the user ID and its realm is returned:

{
  "valid":true,
  "sessionUid":"209331b0-6d31-4740-8d5f-740286f6e69f-326295",
  "uid":"demo",
  "realm":"/"
}

By default, validating a session resets the session’s idle time, which triggers a write operation to the Core Token Service token store. To avoid this, perform a call using the validate&refresh=false action.

Refresh CTS-based sessions over REST

To reset the idle time of a CTS-based session using REST, perform an HTTP POST to the /json/sessions/ endpoint, using the refresh action. The endpoint will refresh the session token provided in the <session-cookie-name> header by default. To refresh a different session token, include it in the POST body as the value of the tokenId query parameter.

The following example shows an administrative user passing their session token in the <session-cookie-name> header, and the session token of the demo user as the tokenId parameter:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=refresh'
{
  "uid": "demo",
  "realm": "/",
  "idletime": 17,
  "maxidletime": 30,
  "maxsessiontime": 120,
  "maxtime": 7106
}

On success, AM resets the idle time for the CTS-based session, and returns timeout details of the session.

Resetting a CTS-based session’s idle time triggers a write operation to the Core Token Service token store. Therefore, to avoid the overhead of write operations to the token store, be careful to use the refresh action only if you want to reset a CTS-based session’s idle time.

Invalidate sessions over REST

To invalidate a session, perform an HTTP POST to the /json/sessions/ endpoint using the logout action. The endpoint will invalidate the session token provided in the <session-cookie-name> header:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=logout'
{
    "result": "Successfully logged out"
}

On success, AM invalidates the session and returns a success message.

If the token is not valid and cannot be invalidated an error message is returned:

{
  "result": "Token has expired"
}

To invalidate a different session token, include it in the POST body as the value of the tokenId parameter.

For example, the following command shows an administrative user passing their session token in the <session-cookie-name> header, and the session token of the demo user as the tokenId parameter:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=logout'
{
    "result": "Successfully logged out"
}

Get or set session properties using REST

AM lets you read and update properties on users' sessions using REST API calls.

Before you can perform operations on session properties using the REST API, you must first define the properties you want to set in the session property allowlist configuration. For information on adding session properties to an allowlist, see Session property whitelist service.

You can use REST API calls for the following purposes:

  • To retrieve the names of the properties that you can read or update. This is the same set of properties configured in the Session Property Whitelist Service.

  • To read property values.

  • To update property values.

Session state affects the ability to set and delete properties as follows:

  • You can set and delete properties on a CTS-based session at any time during the session’s lifetime.

Differentiate the user who performs the operation on session properties from the session affected by the operation as follows:

  • Specify the session token of the user performing the operation on session properties in the <session-cookie-name> header.

  • Specify the session token of the user whose session is to be read or modified as the tokenId parameter in the body of the REST API call.

  • Omit the tokenId parameter from the body of the REST API call if the session of the user performing the operation is the same session that you want to read or modify.

The following examples assume that you configured a property named LoginLocation in the session property allowlist configuration.

To retrieve the names of the properties you can get or set, and their values, perform an an HTTP POST to the sessions endpoint, /json/sessions/, using the getSessionProperties action:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=getSessionProperties'
{
    "LoginLocation": ""
}

To set the value of a session property, perform an HTTP POST to the sessions endpoint, /json/sessions/, using the updateSessionProperties action. If no tokenId parameter is present in the body of the REST API call, the session affected by the operation is the session specified in the <session-cookie-name> header:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation":"40.748440, -73.984559"}' \
'https://<tenant-name>.forgeblocks.com/am/realms/root/json/sessions/?_action=updateSessionProperties'
{
    "LoginLocation": "40.748440, -73.984559"
}

You can set multiple properties in a single REST API call by specifying a set of fields and their values in the JSON data. For example:

--data '{"property1":"value1", "property2":"value2"}'

To set the value of a session property on another user’s session, specify the session token of the user performing the updateSessionProperties action in the <session-cookie-name> header, and specify the session token to be modified in the POST body as the value of the tokenId parameter:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation": "40.748440, -73.984559", "tokenId": "BXCCq…​NX*1*"}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=updateSessionProperties'
{
    "LoginLocation": "40.748440, -73.984559"
}

If the user attempting to modify the session does not have sufficient access privileges, the preceding examples result in a 403 Forbidden error.

You cannot set properties internal to AM sessions. If you try to modify an internal property in a REST API call, a 403 Forbidden error is returned. For example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"AuthLevel":"5", "tokenId": "BXCCq…​NX*1*"}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/sessions/?_action=updateSessionProperties'
{
    "code": 403,
    "reason": "Forbidden",
    "message": "Forbidden"
}

For a list of the default session properties, see Session properties.

Session upgrade

Sessions can be upgraded to provide access to sensitive resources.

Consider a website for a University. Some information, such as courses and degree catalogs, are free for anyone to see and therefore, do not need to be protected. The University also provides the students with a portal they can use to see their grades, which is protected with a policy that requires users to authenticate. However, to pay tuition, students are required to present additional credentials to increase their authentication level and gain access to these functions.

Allowing authenticated users to provide additional credentials to access sensitive resources is called session upgrade, which is AM’s mechanism to perform step-up authentication.

What triggers a session upgrade?
  • An authenticated user being redirected to a URL that has the ForceAuth parameter set to true. For example, https://openam.example.com:8443/openam/XUI/?realm=/alpha&ForceAuth=true#login

    In this case, the user is asked to reauthenticate to the default chain in the realm myRealm.

    Session upgrade using the ForceAuth parameter is only supported for CTS-based sessions.
  • An authenticated user trying to access a resource protected by a web or Java agent (or a custom policy enforcement point (PEP)). In this case, AM sends the agent or PEP advice that the user should perform one of the following actions:

    • Authenticate at an authentication level greater than the current level

    • Authenticate to a service

    The flow of the session upgrade during policy evaluation is as follows:

    1. An authenticated user tries to access a resource.

    2. The PEP, for example a web or Java agent, sends the request to AM for policy decision.

    3. AM returns an authorization decision that denies access to the resource, and returns an advice indicating that the user needs to present additional credentials to access the resource.

    4. The policy enforcement point sends the user back to AM for session upgrade.

    5. The user provides additional credentials. For example, they may provide a one-time password, swipe their phone screen, or use face recognition.

    6. AM authenticates the user.

    7. The user can now access the sensitive resource.

Session upgrade outcomes
  • Successful. One of the following will happen depending on the type of sessions configured for the realm:

    • If the realm is configured for CTS-based sessions, one of the following will happen depending on the mechanism used to perform session upgrade:

      • When using the ForceAuth parameter, AM issues new session tokens to users on reauthentication, even if the current session already meets the security requirements.

      • When using advices, AM copies the session properties to a new session and hands the client a new session token to replace the original one. The new session reflects the successful authentication to a higher level.

  • Unsuccessful. AM leaves the user session as it was before the attempt at stronger authentication. If session upgrade failed because the login page times out, AM redirects the user’s browser to the success URL from the last successful authentication.

Anonymous sessions can also be upgraded to non-anonymous sessions by using the Anonymous Session Upgrade node.

Session upgrade prerequisites

  • Configure a policy enforcement point (PEP), for example, a web or Java agent, that enforces AM policies on a website or application.

    AM web and Java agents handle session upgrade without additional configuration because the agents are built to handle AM’s advices. If you build your own PEPs, however, you must take advices and session upgrade into consideration.

    Resources
  • Configure an authorization policy to protect a resource protected by the Java or web agent, or a RESTful PEP.

    Example

    The following policy allows GET and POST access to the *://*:*/sample/* resource to any authenticated user:

    Only authenticated users can access the resource
    Figure 1. Authorization Policy Example

Configure the environment for session upgrade

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

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

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

    Authentication Level (greater than or equal to)

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

    Session upgrade authentication by authentication level environment condition
    Figure 2. Session Upgrade by Authentication Level (greater than or equal to)

    Configure the authentication level as an authentication tree node. For more information, see Auth Level Decision node.

    Authentication by service

    Use this condition to specify 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 authentication by service environment condition
    Figure 3. Session Upgrade by Service

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

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

  3. Test session upgrade:

Perform session upgrade with a browser

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

  1. Ensure you have performed the tasks in Session upgrade prerequisites and 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.

Perform session upgrade over REST

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

  1. Ensure you have performed the tasks in Session upgrade prerequisites and Configure the environment for session upgrade.

  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://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC5wM2…​",
        "successUrl":"/openam/console",
        "realm":"/alpha"
    }

    You can also assign privileges to a user to evaluate policies. For more information, see Add a user who can 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://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC5wM…​TU3OQ*",
        "successUrl":"/openam/console",
        "realm":"/alpha"
    }
  4. Request a policy decision from AM for a protected resource, in this case, http://www.example.com:9090/sample.

    The <session-cookie-name> 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 "<session-cookie-name>: 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://<tenant-name>.forgeblocks.com/am/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 Request policy decisions over 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>

    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 <session-cookie-name> cookie as the SSO token for the demo user.

      For example:

      $ curl --request POST \
      --header "Content-Type: application/json" \
      --cookie "<session-cookie-name>=AQIC5wM…​TU3OQ*" \
      --header "Accept-API-Version: protocol=1.0,resource=2.1" \
      'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/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 Authenticate using 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 <session-cookie-name> 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 "<session-cookie-name>=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://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate?authIndexType=composite_advice&authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E…​'
      {
         "tokenId":"wpU01SaTq4X2x…​NDVFMAAlMxAAA.*",
         "successUrl":"/openam/console",
         "realm":"/alpha"
      }

      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 <session-cookie-name> 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 "<session-cookie-name>: 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://<tenant-name>.forgeblocks.com/am/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.

Copyright Ā© 2010-2022 ForgeRock, all rights reserved.