How To
ForgeRock Identity Cloud
Integrations

ADFS SSO integration with Identity Cloud as SAML service provider

Last updated Oct 27, 2021

The purpose of this article is to provide information on configuring Identity Cloud to integrate with Active Directory Federation Services (ADFS) using SAML2 federation for Single Sign-On (SSO). It assumes Identity Cloud is acting as the service provider (SP) and ADFS as the identity provider (IdP).


Overview

This article describes the steps required to configure ForgeRock Identity Cloud to federate with an on-prem or cloud-hosted Microsoft® Windows® ADFS instance using the SAML 2.0 standard, and covers the following use cases and scenarios: 

  • The user credentials are stored in Active Directory®, and may be updated by the admin or the user (for example, through a portal, app or the login panel on a domain attached PC).
  • Identity Cloud uses ADFS federation as one authentication factor in an authentication journey.
Note

In some cases, it is possible to use the Active Directory password synchronization plugin to intercept password changes as an alternative to using SAML2 federation. See Password Synchronization Plugin Guide for further information.

Steps involved:

  1. Create a Circle of Trust (COT)
  2. Create the hosted SP in Identity Cloud
  3. Configure ADFS
  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 ADFS instance (either installed on your Microsoft Windows server or cloud hosted).

Creating a Circle of Trust (COT)

  1. In the Identity Cloud Admin UI, navigate 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, ADFSCOT, and click Create.
  3. Add a description for the COT and click Save Changes.
 

Creating the hosted SP in Identity Cloud

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Hosted.
  2. Complete the following details and click Create:
    • Entity ID: Enter an ID (no special characters or spaces) for your hosted service provider, for example, idCloudSP.
    • 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, idCloudSP.
    • Circles of Trust: Select the COT created above, for example, ADFSCOT.
 
  1. Select the Services tab and scroll to Assertion Consumer Service.
  2. 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-name>.forgeblocks.com/am/AuthConsumer/metaAlias/alpha/idCloudSP
    • HTTP-POST: Change Consumer in the location to AuthConsumer. For example, it should now look like this:https://<tenant-name>.forgeblocks.com/am/AuthConsumer/metaAlias/alpha/idCloudSP
    • Do not update the location for the PAOS service because integrated mode does not support the PAOS binding.

The results will resemble the following in the UI:

 
  1. Click Save Changes.

Configuring ADFS

Note

The following steps download the metadata and then import data from that file (Import data about the relying party from a file option). If you want to avoid downloading the metadata locally (Import data about the relying party published online or on a local network​ option), you will need to reconfigure ADFS to use modern security protocols. Otherwise, the Identity Cloud will reject the request for metadata because ADFS defaults to an insecure protocol. See Managing SSL/TLS Protocols and Cipher Suites for AD FS for further information.

ForgeRock assumes no responsibility for errors or omissions in the third-party software or documentation.

Download the hosted SP metadata

  1. Open a PowerShell terminal.
  2. Run the following command to download the SAML metadata into the specified file (outfile); ensure the URL and entityID are correct for your Identity Cloud tenant and configuration:Invoke-WebRequest -outfile idcloud-sp.xml -uri "https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=idCloudSP&realm=/alpha"

Create the Relying Party Trust

  1. Launch your ADFS instance and start the Add Relying Party Trust wizard.
  2. Progress through the wizard using the following settings:
    • The Claims Aware option.
    • The Import data about the relying party from a file option - choose the metadata file you saved above (idcloud-sp.xml). You can ignore the resulting warning about content in the metadata XML being unsupported.
    • The ​Permit Everyone​ policy.
    • The ​Configure claims issuance policy for this application option.

Refer to Create a Replying Party Trust for further information.

Add a Claims rule

  1. Click Add Rule and choose the ​Send LDAP Attributes as Claims option as the Rule Type template.
  2. Progress through the wizard using the following settings:
    • Select ​Active Directory​ as the Attribute Store.
    • Map LDAP attributes to the outgoing claim types per your requirements, for example: LDAP Attribute                    Outgoing Claim Type --------------                      ------------------- SAM-Account-Name                    samAccountName E-Mail-Addresses                    mail Department                          department Given-Name                          givenName Surname                             snOne of the Outgoing Claims is used as the SAML NameId. We suggest you use ​samAccountName​ unless you have specific requirements.

Refer to Create a Rule to Send LDAP Attributes as Claims for further information.

Add a NameId rule

  1. Click Add Rule and choose the ​Send Claims Using a Custom Rule option as the Rule Type template.
  2. Create a custom rule using the following rule as a starting point:c: [Type == "​samAccountName​"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/form at"] = "​urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified​", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/name qualifier"] = "http://<ADFS deployment URL>/adfs/services/trust​", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spna mequalifier"] = "​idCloudSP");
  3. Update the following items in this custom rule to match your configuration:
    • samAccountName​: This is the outgoing claim specified in the first rule. This will be the value of the NameId element.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified​: The format being used - this indicates we'll be using the unspecified NameId format.
    • http://<ADFS deployment URL>/adfs/services/trust:​ The URL of the ADFS Federation Service Identifier.
    • idCloudSP: The Entity ID of the hosted SP in the Identity Cloud.

Refer to Create a Rule to Send Claims Using a Custom Rule for further information.

Creating the remote IdP in Identity Cloud

Download and fix the ADFS metadata

  1. Generate the ADFS metadata by navigating to the metadata link, ensuring you specify the correct ADFS deployment URL. For example: https://<ADFS deployment URL>/FederationMetadata/2007-06/FederationMetadata.xml
  2. Save the FederationMetadata.xml file locally.
  3. Edit the FederationMetadata.xml file and remove the following sections:
    • ds: Signature
    • RoleDescriptor
    • SPSSODescriptor

This will just leave the IDPSSODescriptor section. Be careful editing this file, as ADFS generates the XML all on one line.

Create the remote IdP

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Remote.
  2. Import the FederationMetadata.xml file, select the ADFSCOT COT and click Create.
 
  1. Select the Assertion Content tab and scroll to NameId Format.
  2. Add the following NameId format to the list:urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  3. Reorder the list so this new NameId format is first.
 

Creating the end-user journey

When Identity Cloud is acting as the SP, you can use the SAML2 authentication node to provide single sign on initiated by the SP.

The SAML2 node redirects the user to ADFS 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, navigate 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:
 
  1. 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. For ADFS, you should use the default bindings: HTTP-Redirect request binding and HTTP-Artifact response binding. 

  1. 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:

 

Testing the end-user experience

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

  1. Navigate to the Identity Cloud protected resource.
  2. You should then be redirected to ADFS where you can log in with your ADFS credentials.
  3. If successful, you should then be logged into the Identity Cloud protected resource automatically.

Troubleshooting

Debugging

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

Disable Encrypted Assertions

By default, ADFS is configured to encrypt the assertions it generates. It can be helpful to disable this encryption when troubleshooting.

You can disable this encryption as follows:

  1. Open an administrator level Powershell window and enter the following:set-ADFSRelyingPartyTrust -TargetName "<RelyingPartyTrust>" -EncryptClaims $FalseWhere the TargeName parameter should match the value of your Relying Party Trust Display Name defined in ADFS, for example:set-ADFSRelyingPartyTrust -TargetName "IDCloud" -EncryptClaims $False

See Also

Manage Journeys

Active Directory Federation Services


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.