Session upgrade
Sessions can be upgraded to provide access to sensitive resources.
Some resources, 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. 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.
What triggers a session upgrade?
-
An authenticated user being redirected to a URL that has the
ForceAuth
parameter set totrue
. For example,\<tenant-env-fqdn>/am/XUI/?realm=/alpha&ForceAuth=true#login
In this case, the user is asked to reauthenticate to the default authentication tree in the
alpha
realm. -
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 must authenticate to a service.
The flow of the session upgrade during policy evaluation is as follows:
-
An authenticated user tries to access a resource.
-
The PEP, for example a web or Java agent, sends the request to AM for policy decision.
-
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.
-
The policy enforcement point sends the user back to AM for session upgrade.
-
The user provides additional credentials. For example, they may provide a one-time password, swipe their phone screen, or use face recognition.
-
AM authenticates the user.
-
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 server-side 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:Figure 1. Authorization Policy Example
Configure the environment for session upgrade
-
Configure an authentication tree 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.
-
For details, refer to Transactional authorization.
-
For information about configuring authentication trees, refer to Authentication and SSO.
-
-
Configure the following environment condition in the authentication policy that you created as part of the prerequisites:
Authentication by Service
Specify the trees that the user must use to authenticate. For example, the following policy requires the user to log in with the
Example
tree:Figure 2. Session upgrade by serviceNote 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.
-
Test session upgrade:
-
To test session upgrade with a browser, refer to Perform session upgrade with a browser.
-
To test session upgrade with REST, refer to Perform session upgrade over REST.
-
Perform session upgrade with a browser
To upgrade a session using a browser, perform the following steps:
-
Ensure you have performed the tasks in Session upgrade prerequisites and Configure the environment for session upgrade.
-
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.
-
Authenticate to AM. This example uses a user with the ID
demo
.AM requires additional credentials to grant access to the resource. For example, if you set the policy environment condition to
Authentication by Service
andExample
, you will be required to log in again as thedemo
user. -
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:
-
Ensure you have performed the tasks in Session upgrade prerequisites and Configure the environment for session upgrade.
-
Log in as an administrative user that has permission to evaluate policies. For this example, the administrative user has the ID
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-env-fqdn>/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, refer to Add a user who can evaluate policies.
-
Log in as the user that should access the resources. For this example, the user has the ID
bjensen
.$ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: bjensen' \ --header 'X-OpenAM-Password: Secret12!' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…TU3OQ*", "successUrl": "/enduser/?realm=/alpha", "realm":"/alpha" }
-
Request a policy decision from AM for a protected resource; in this case,
http://www.example.com:9090/sample
.Set the
<session-cookie-name>
header to the SSO token for the administrative user, and thesubject
to the SSO token forbjensen
:$ 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-env-fqdn>/am/json/realms/root/realms/alpha/policies?_action=evaluate" [ { "resource":"http://www.example.com:9090/sample", "actions":{ }, "attributes":{ }, "advices":{ "AuthenticateToServiceConditionAdvice":[ "/alpha:Example" ] }, "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.
-
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="AuthenticateToServiceConditionAdvice"/> <Value>/alpha:Example</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.
-
URL-encode the XML advice.
For example:
%3CAdvices%3E%3CAttributeValuePair%3E%3CAttribute%20name%3D%22AuthenticateToServiceConditionAdvice%22%2F%3E%3CValue%3E%2Falpha%3AExample%3C%2FValue%3E%3C%2FAttributeValuePair%3E%3C%2FAdvices%3E
.Ensure there are no spaces between tags when URL-encoding the advice.
-
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 thedemo
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-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=composite_advice&authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E…' { "authId":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZ…", "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.
-
-
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 thedemo
user. -
Set
data
to contain the complete payload AM returned in the previous step, and include the requested callback information.In this example, provide the username and password for the
demo
user ininput
, 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…", "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":"Secret12!" } ] } ] } }' \ 'https://<tenant-env-fqdn>/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.
-
-
Request a new policy decision from AM for the protected resource.
Set the
<session-cookie-name>
header to the SSO token for the administrative user, and thesubject
to the new SSO token returned for thedemo
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-env-fqdn>/am/json/realms/root/realms/alpha/policies?_action=evaluate" [ { "resource":"http://www.example.com:9090/sample", "actions":{ "POST":true, "GET":true }, "attributes":{ }, "advices":{ }, "ttl":9223372036854775807 } ]
AM returns that
demo
can performPOST
andGET
operations on the resource.