--- title: Session upgrade description: Enable authenticated users to provide additional credentials to access sensitive resources through step-up authentication and session upgrade component: pingam version: 7.5 page_id: pingam:am-sessions:session-upgrade canonical_url: https://docs.pingidentity.com/pingam/8.1/am-sessions/session-upgrade.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Sessions", "Authentication", "Step-up Authentication", "Configuration", "REST API"] page_aliases: ["sessions-guide:session-upgrade.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/am-sessions/session-upgrade.html section_ids: session-upgrade-prerequisites: Session upgrade prerequisites proc-session-upgrade-configuration: Configure the environment for session upgrade proc-session-upgrade-browser: Perform session upgrade with a browser proc-session-upgrade-REST: Perform session upgrade over REST --- # Session upgrade Sessions can be upgraded to provide access to sensitive resources. Consider a website for a university. Some resources, such as courses and degree catalogs, are free for anyone to access and don't need to be protected. The university also provides the students with a portal they can use to access their grades. This portal is protected with a policy that requires users to authenticate. 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. Session upgrade is AM's mechanism to perform step-up authentication. > **Collapse: What triggers a session upgrade?** > > * An authenticated user being redirected to a URL that has the `ForceAuth` parameter set to `true` for the same authentication tree that was used to create the current session. 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 authentication tree in the `alpha` realm even if the current session already satisfies the authentication requirements. > > When a new session is created, the old session should no longer be valid. For client-side sessions, invalidating the old session depends on the value of the [Enable Session Denylisting](session-state-session-termination.html#session-state-configure-denylist) configuration option. If this option is `false` (default), then both the old and new sessions are considered valid after the session upgrade. If this option is `true`, the old session is no longer valid > > * An authenticated user is redirected to a different authentication tree than the one that created their current session. > > For example, the user authenticated through the `Login` tree and later is sent to a URL that specifies a different tree: > > `https://openam.example.com:8443/openam/XUI/?realm=/alpha&service=StepUpMFA#login` > > In this case, AM upgrades the session if the existing authentication doesn't meet the new tree's requirements. You don't need to set `ForceAuth=true` when moving the user to a different tree because the change of tree itself triggers session upgrade. > > * 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 an advice that the user must perform one of the following actions: > > * Authenticate at an authentication level greater than the current level > > * Authenticate to a specific service > > * Authenticate to a specific module > > 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 an authorization decision. > > 3. AM returns an authorization decision that denies access to the resource, and returns an *advice* indicating that the user must 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. > **Collapse: Session upgrade outcomes** > > * **Successful**. AM performs one of the following actions depending on the type of session configured for the realm: > > * If the realm is configured for server-side sessions, the resulting action depends on the mechanism used to perform session upgrade: > > * When using the `ForceAuth` parameter: > > * *(Authentication trees only)* AM issues new session tokens to users on reauthentication, even if the current session already meets the security requirements. > > * *(Authentication chains only)* AM doesn't issue new session tokens on reauthentication, regardless of the security level they are authenticating to. Instead, it updates the session token with the new authentication information, if required. > > * 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. > > * If the realm is configured for client-side sessions, AM 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 fails 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](https://docs.pingidentity.com/auth-node-ref/7.5/anonymous-session-upgrade.html). | ## Session upgrade prerequisites * Configure a 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, you must take advices and session upgrade into consideration. > **Collapse: Resources** > > * [Web Agents documentation](https://docs.pingidentity.com/web-agents/2024.11). > > * [Java Agents documentation](https://docs.pingidentity.com/java-agents/2024.11). > > * [Request policy decisions over REST](../am-authorization/rest-api-authz-policy-decisions.html) (For RESTful PEPs). * Configure an authorization policy to protect a resource protected by the Java or web agent, or a RESTful PEP. > **Collapse: Example** > > The following policy allows GET and POST access to the `*://*:*/sample/*` resource to any authenticated user: > > ![Only authenticated users can access the resource](_images/pre-session-upgrade-config.png) > > Figure 1. Authorization Policy Example | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To track the session through upgrade, enable the [cross-upgrade session reference property](../reference/global-services-configuration.html#global-session-xusref), which retains its value throughout the session lifecycle. Enabling this property ensures the session reference is recorded in the [audit logs](../security/sec-maint-audit-ref.html). | ## Configure the environment for session upgrade 1. Configure an authentication tree or chain to validate users' credentials during session upgrade. Authentication trees and chains don't require additional configuration to perform session upgrade. However, because session upgrade is a mechanism that can be used to grant users access to sensitive information, you should consider configuring a strong authentication method such as multi-factor authentication (MFA). You should also 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 checking the balance of an account, consider implementing [transactional authorization](../am-authorization/transactional-authorization.html) instead. Learn more in [Authentication and SSO](../am-authentication/preface.html). 2. Configure at least one of the following environment conditions in the authentication policy that you created as part of the [prerequisites](#session-upgrade-prerequisites): > **Collapse: Authentication Level (greater than or equal to)** > > Use this condition to present a list of authentication services (trees or 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 services are able to meet the criteria of the condition. For example, the following policy requires a module that provides authentication level `3` or greater: > > ![Session upgrade authentication by authentication level environment condition](_images/session-upgrade-auth-level.png) > > Figure 2. Session upgrade by authentication level > > | | | > | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | You can find more information about configuring the authentication level by authentication module in [Authentication levels for chains](../am-authentication/about-authentication-modules-and-chains.html#about-authentication-levels). | > **Collapse: 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 sign on with the `Example` tree: > > ![Session upgrade authentication by service environment condition](_images/session-upgrade-service.png) > > Figure 3. Session upgrade by service > > The names of the authentication trees and chains are case-sensitive. > **Collapse: Authentication by Module Instance ()** > > Use this condition to enforce that a user has gone through a specific authentication module. For example, the following policy requires the user to sign on with the `DataStore` module: > > ![Session upgrade authentication by module instance environment condition](_images/session-upgrade-module-instance.png) > > Figure 4. Session upgrade by module instance | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The examples show simple policy conditions. You can find more information about configuring policies and environment conditions in [Policies](../am-authorization/policies.html). | 3. Test session upgrade using a browser or REST: * [Perform session upgrade with a browser](#proc-session-upgrade-browser) * [Perform session upgrade over REST](#proc-session-upgrade-REST) ## 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](#session-upgrade-prerequisites) and [Configure the environment for session upgrade](#proc-session-upgrade-configuration). 2. In a browser, go 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 sign on again as the `demo` user. 4. Authenticate as the `demo` user. 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](#session-upgrade-prerequisites) and [Configure the environment for session upgrade](#proc-session-upgrade-configuration). 2. Sign on with an administrative user that has permission to evaluate policies, such as `amAdmin`. For example: ```bash $ 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/realms/alpha/authenticate' { "tokenId":"AQIC5wM…​TU3OQ*", "successUrl":"/am/console", "realm":"/alpha" } ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------- | | | You can also [assign privileges to a user to evaluate policies](../am-authorization/scripted-policy-condition.html#scripted-policy-privilege). | 3. Sign on with the user that should access the resources. For example, sign on as `bjensen`: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: bjensen" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…​TU3OQ*", "successUrl":"/am/console", "realm":"/alpha" } ``` 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 `bjensen`: ```bash $ 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/realms/root/realms/alpha/policies?_action=evaluate" [ { "resource":"http://www.example.com:9090/sample", "actions":{ }, "attributes":{ }, "advices":{ "AuthLevelConditionAdvice":[ "3" ] }, "ttl":9223372036854775807 } ] ``` AM returns an advice, which means that the user must present additional credentials to access that resource. You can find more information about requesting policy decisions in [Request policy decisions over REST](../am-authorization/rest-api-authz-policy-decisions.html). 5. Format the advice as XML, without spaces or line breaks. The following example is spaced and tabulated for readability purposes only: ```xml 3 ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The example shows the XML render of a single advice. Depending on the conditions configured in the policy, the advice may contain several lines. Learn more in [Policy decision advice](../am-authorization/rest-api-authz-policy-decisions.html#rest-api-authz-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: ```bash $ 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/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. You can find a list of possible callbacks, and more information about the `/json/authenticate` endpoint in [Authenticate over REST](../am-authentication/authn-rest.html). 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: ```bash $ 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/realms/alpha/authenticate?authIndexType=composite_advice&authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E…​' { "tokenId":"wpU01SaTq4X2x…​NDVFMAAlMxAAA.*", "successUrl":"/openam/console", "realm":"/alpha" } ``` 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: ```bash $ 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/realms/root/realms/alpha/policies/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.