Azure SSO integration with Identity Cloud as SAML service provider

Overview

This article covers the following use cases and scenarios:

• The user credentials are stored in Azure AD, and may be updated by the admin or the user (for example, through a portal or app).
• Identity Cloud uses Azure federation as one authentication factor in an authentication journey.

Steps involved:

1. Create a Circle of Trust (COT)
2. Create the hosted SP in Identity Cloud
3. Configure Azure
4. Create the remote IdP in Identity Cloud
5. Create the end user journey
6. Test the end user experience
7. Troubleshooting

Prerequisites

• You have a working Identity Cloud tenant.
• You have a working Azure AD instance.

Creating a Circle of Trust (COT)

1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Circles of Trust and click Add Circle of Trust.
2. Enter a name (no spaces) for your new COT, for example, ForgeRockCOT, and click Create.
3. Add a description for the COT and click Save Changes.

Creating the hosted SP in Identity Cloud

Create a hosted SP

1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Hosted.
2. Complete the following configuration:
   • Entity ID: Enter an ID (no special characters or spaces) for your hosted service provider, for example, ForgeRockSP.
   • Entity Provider Base URL: Verify the default URL is correct. This URL is used for all SAML2 related endpoints, so ensure other entities in your SAML deployment are able to access the specified URL.
   • Identity Provider Meta Alias: Leave blank because we're only creating a hosted SP.
   • Service Provider Meta Alias: Enter a URL-friendly value to identify the service provider, for example, sp.
   • Circles of Trust: Select the COT created above, for example, ForgeRockCOT.

3. Click Create.
4. Select the Assertion Processing tab and specify the required mappings in the Attribute Mapper to map attributes in the assertion to profile attributes in Identity Cloud. The following mappings will work with the default settings in Azure to get you started:

5. Scroll down to Account Mapper on the same tab and select the Use Name ID as User ID option.
6. Select the Services tab and scroll to Assertion Consumer Service.
7. Update the location for the following services as follows:
   • HTTP-Artifact: Change Consumer in the location to AuthConsumer. For example, it should now look like this:https://<tenant-env-fqdn>/am/AuthConsumer/metaAlias/alpha/sp
   • HTTP-POST: Change Consumer in the location to AuthConsumer. For example, it should now look like this:https://<tenant-env-fqdn>/am/AuthConsumer/metaAlias/alpha/sp
   • Do not update the location for the PAOS service because the SAML2 authentication node does not support the PAOS binding.

8. Click Save Changes.

Generate the hosted SP metadata

You'll use the SP metadata when you configure SAML SSO in Azure.

To export the SP metadata to a file, use a curl command such as the following with the metadata URL in the following format: $ curl --output metadata.xml "https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=[entityID]&realm=/[realmname]"In our example, the [entityID] is ForgeRockIDP and the [realmname] is alpha.

See How do I export and import SAML2 metadata in Identity Cloud? for further information.

Configuring Azure

Configure Azure

1. Sign in to the Azure Active Directory Admin Center.
2. Go to Enterprise applications > New Application > Create your own application and enter a name for your app.
3. Select the Integrate any other application you don’t find in the gallery (Non-gallery) option and click Create.

Refer to Quickstart: Add an enterprise application for further information on creating an enterprise app.

4. Go to Manage > Users and groups and assign users and groups to your enterprise app. Enterprise apps are only available to users who have been assigned to them - either directly or via a group.

Refer to Quickstart: Create and assign a user account and Assign users and groups for further information.

5. Go to Manage > Single sign-on > SAML > Upload metadatafile and upload the SP metadata .xml file you exported from Identity Cloud.
6. Enter the URL used for logging into Identity Cloud in the Sign on URL field. This is the URL the user is redirected to when selecting this app from their My Apps portal for the purpose of creating an Identity Cloud session and determining if any other authentication steps are required such as MFA. Typically, this URL is in the format: https://<tenant-env-fqdn>/login?authIndexType=service&authIndexValue=<login_journey_name>.
7. Check the remaining SSO details are correct; most settings will have been auto-populated when you uploaded the metadata file.

Refer to Quickstart: Enable single sign-on for an enterprise application for further information.

Download and fix the Azure metadata

1. Go to Manage > Single sign-on > SAML Signing Certificate (section 3) and click Download next to Federation Metadata XML.
2. Save the metadata to a file locally, for example, FederationMetadata.xml.
3. Edit the FederationMetadata.xml file and remove the following sections:
   • Signature
   • RoleDescriptor
   • fed:xxxx

This will just leave the IDPSSODescriptor section.

Creating the remote IdP in Identity Cloud

1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Remote.
2. Import the FederationMetadata.xml file, select ForgeRockCOT and click Create.

Creating the end user journey

When Identity Cloud is acting as the SP, you can use the SAML2 authentication node to provide SSO in an SP-initiated flow.

The SAML2 node redirects the user to Azure for authentication when it is invoked. This node can be placed at any point in the authentication journey, which allows for scenarios such as selection between multiple providers based on user selection, conditional invocation of SAML based on user choice, and so on.

The node returns either Account Exists or No Account Exists which corresponds to success or failure for any reason. If successful, the username session state variable is set to the name identifier defined in the SAML configuration.

In a simple deployment where all accounts have been pre-provisioned and linked, you only need to include the SAML2 node in the tree. For more complicated scenarios, you can use additional nodes to provision the corresponding account in Identity Cloud and link the two accounts.

Simple deployment example

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. Add the SAML2 Authentication node to the journey, and link the user to the node and the outcomes from the node, for example:

4. Click the SAML2 Authentication node to display the configuration options and enter values for the following ones related to SP initiated SSO:
   • IdP Entity ID
   • SP MetaAlias

You can leave the other default settings as they are unless you have any specific requirements.

5. Click Save.

Other journeys

Journeys are very customizable and can be used to cater to a variety of use cases. To give an example of a more complicated one, the following journey determines if a user has attempted to log in from the Partner1 domain, Partner2 domain, or from an internal domain, and then redirects the user to a selection of SAML2 providers accordingly:

The User Type node shown in the above image is purely for illustration purposes. If you were re-creating this example journey, the actual node you'd use would depend on your requirements. For example, you could use a Scripted Decision node, which checks the domain name (or other detail such as IP range, cookie and so on) to identify the user and then direct them to the correct authentication method, or you could use a Choice Collector node, where the user simply selects what type of user they are and then authenticates accordingly. 

Testing the end user experience

To log in to Identity Cloud using Azure as the SAML identity provider:

1. Go to the My Apps portal and log in as a user who has been granted access to the app you created.
2. Click the application icon for your app.
3. If successful, you should then be logged into the Identity Cloud protected resource automatically.

Troubleshooting

If you have problems with your SSO not working as expected, refer to the following sections of the Azure documentation:

• Troubleshoot SAML-based single sign-on
• Debug SAML-based single sign-on to applications
• Troubleshoot application sign-in
• An app page shows an error message after the user signs in

Debug information can be found in the logs; specifically, the am-config and am-everything logs. See View audit and debug logs for further information on accessing these debug logs.

See Also

Microsoft SSO integration with Identity Cloud for social authentication/registration

How do I integrate Microsoft Azure AD with Autonomous Identity for SSO?

SAML 2.0 federation in Identity Cloud

Journeys

SAML v2.0

Azure Active Directory documentation