How To
ForgeRock Identity Cloud

ADFS SSO integration with Identity Cloud as SAML service provider

Last updated Jan 24, 2023

The purpose of this article is to provide information on how to configure ForgeRock 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).


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.

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 plugins 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


  • 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, 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

  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.
  1. Click Create.
  2. Select the Services tab and scroll to Assertion Consumer Service.
  3. 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.
  1. Click Save Changes.

Configuring ADFS


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 forgerock-sp.xml -uri "https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=ForgeRockSP&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 (forgerock-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 as required, 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 = "", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties[" at"] = "​urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified​", Properties[" qualifier"] = "http://<ADFS deployment URL>/adfs/services/trust​", Properties[" mequalifier"] = "​ForgeRockSP");
  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.
    • ForgeRockSP: 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, 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.
  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:
  1. Click Save Changes.

Creating the end user journey

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

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, 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:
  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:

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



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.

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


SAML 2.0 federation in Identity Cloud

SAML v2.0

Active Directory Federation Services

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