- 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 Plugin Guide for further information.
- 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)
- In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Circles of Trust and click Add Circle of Trust.
- Enter a name (no spaces) for your new COT, for example, ADFSCOT, and click Create.
- Add a description for the COT and click Save Changes.
Creating the hosted SP in Identity Cloud
- In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Hosted.
- 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.
- Select the Services tab and scroll to Assertion Consumer Service.
- 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://openam-<YourTenantName>.forgerock.io/am/AuthConsumer/metaAlias/alpha/idCloudSP
- HTTP-POST: Change Consumer in the location to AuthConsumer. For example, it should now look like this:https://openam-<YourTenantName>.forgerock.io/am/AuthConsumer/metaAlias/alpha/idCloudSP
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:
- Click Save Changes.
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
- Open a PowerShell terminal.
- 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://openam-<YourTenantName>.forgerock.io/am/saml2/jsp/exportmetadata.jsp?entityid=idCloudSP&realm=/alpha"
Create the Relying Party Trust
- Launch your ADFS instance and start the Add Relying Party Trust wizard.
- Progress through the wizard using the following settings:
Import data about the relying party from a fileoption - choose the metadata file you saved above (idcloud-sp.xml).
You can ignore the resulting warning about content in the metadata XML being unsupported.
Configure claims issuance policy for this applicationoption.
Refer to Create a Replying Party Trust for further information.
Add a Claims rule
- Click Add Rule and choose the
Send LDAP Attributes as Claimsoption as the Rule Type template.
- Progress through the wizard using the following settings:
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
- Click Add Rule and choose the
Send Claims Using a Custom Ruleoption as the Rule Type template.
- 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");
- 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
- 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
- Save the FederationMetadata.xml file locally.
- Edit the FederationMetadata.xml file and remove the following sections:
- ds: Signature
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
- In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Remote.
- Import the FederationMetadata.xml file, select the ADFSCOT COT and click Create.
- Select the Assertion Content tab and scroll to NameId Format.
- Add the following NameId format to the list:urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
- 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
- In the Identity Cloud Admin UI, navigate to Journeys and click New Journey.
- Enter a name for your journey, select which identities will authenticate using this journey, and click Save.
- Add the SAML2 Authentication node to the journey, and link the user to the node and the outcomes from the node, for example:
- 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.
- Click Save.
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:
- Navigate to the Identity Cloud protected resource.
- You should then be redirected to ADFS where you can log in with your ADFS credentials.
- 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 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:
- 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