How do I make session properties from a journey available in the SAML2 assertion when Identity Cloud is the IdP?

Overview

The process outlined in this article uses a login journey to capture details when a user authenticates and then stores those details in a session property. The advantage of doing this at the login stage versus assertion minting time is that it reduces the number of API calls from once per assertion to once per session. You can then use the Authentication Context Mapper to map your login journey to an authentication context in order to use the stored session property in subsequent SAML2 flows. Finally, you can use the standard IdP and SP Attribute Mappers to extract the information from the stored session property and add it to the assertion.

Summary of steps involved:

1. Create login journey
2. Allowlist the session property
3. Update the hosted IdP to use the login journey
4. Update the hosted IdP to add the session property to the assertion
5. Update the remote SP to add the same session property to the assertion
6. Validate the SAML assertion contains the session property

These examples use a session property called mySessionProperty and a journey called myLoginJourney.

Prerequisites

• You have a working Identity Cloud tenant.
• You have an existing SAML2 integration set up, where Identity Cloud is the hosted IdP.

Creating a login journey

Creating a login journey can be quite straightforward or may need scripting knowledge depending on what you want to set in your session property:

• If you just want to update a session property with static values, you can use the Set Session Properties node. See Set Session Properties node for further information. In the following example journey, the Set Session Properties node would replace the two Scripted Decision nodes to simplify your journey.
• If you want to retrieve a value using some logic and store that value as a session property, you will need to use Scripted Decision nodes and write suitable scripts to achieve it.

To create a login journey:

1. In the Identity Cloud admin UI, go to Journeys and click New Journey.
2. Enter a name for your journey, select which identities will authenticate using this journey, and click Save.
3. Create a login journey, which authenticates the user, retrieves the required piece of information, and then updates a session property. For example, your journey may look similar to this, where the Retrieve Information and Update Session Property nodes are Scripted Decision nodes:

4. Click Save.

See Setting Session Properties and Accessing Existing Session Properties for further information and examples on using Scripted Decision Node scripts to set and access session properties using the Action interface and the existingSession object respectively.

There are example scripts in GitHub that demonstrate retrieving a user's location from their IP address and setting that as a session property. You can refer to these scripts as a starting point for your own scripts (but they are not supported):

• Get user's location from their IP address
• Set session property

Allowlisting the session property

All session properties are considered sensitive and are invisible to everyone, including admins, by default. In order to make them accessible, you must allowlist them.

1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Services > Session Property Whitelist Service.
2. Add the name of your session property to both fields. For example, it would look similar to this after adding a property called mySessionProperty:

3. Click Save Changes.

Updating the hosted IdP to use the login journey

1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
2. Select the Assertion Content tab and scroll to Authentication Context.
3. Modify the default mapping of the PasswordProtectedTransport context as follows:
   • Key - select Service.
   • Value - enter the name of the login journey you created.

For example, it would look similar to this after specifying a login journey called myLoginJourney:

4. Click Save Changes.

Updating the hosted IdP to add the session property to the assertion

1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
2. Select the Assertion Processing tab and scroll to Attribute Mapper.
3. Add a new attribute mapping to map the session property to a SAML attribute (which is the name shown in the assertion). For example, it would look similar to this after specifying your session property (mySessionProperty) and mapping it to a SAML attribute called sessionProperty:

Identity Cloud initially looks for a profile attribute that matches the name specified for the Local Attribute. If a matching profile attribute doesn't exist, it then looks for a session property with that name.

4. Click Save Changes.

Updating the remote SP to add the same session property to the assertion

1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Remote SP.
2. Select the Assertion Processing tab and scroll to Attribute Mapper.
3. Add a new attribute mapping to map the session property to a SAML attribute so that it matches the mapping you added to the IdP.
4. Click Save Changes.

Validating the SAML assertion contains the session property

You can capture a SAML trace to check that the assertion contains the session property. There are free third-party tools you can use, for example, in Firefox®, you can use SAML Tracer.

You should see something similar to the following in the trace for the POST to the login URL if your session property has been successfully added:<saml:AttributeStatement>      <saml:Attribute Name="sessionProperty">           <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"                                xsi:type="xs:string"                                >propertyValue</saml:AttributeValue>       </saml:Attribute>   </saml:AttributeStatement>

See Also

How do I export and import SAML2 metadata in Identity Cloud?

Scripted Decision Node API Functionality

Hosted Identity Provider Configuration Properties

Remote Service Provider Configuration Properties