Salesforce SSO integration with Identity Cloud as SAML identity provider
The purpose of this article is to provide information on how to configure ForgeRock Identity Cloud to integrate with Salesforce® using SAML2 federation for Single Sign-On (SSO). It assumes Identity Cloud is acting as the identity provider (IdP) and Salesforce as the service provider (SP).
Overview
This article describes how to enable your users to sign in to Salesforce with Identity Cloud using SAML2 SSO in an SP-initiated flow. It assumes Identity Cloud is acting as the SAML IdP and Salesforce as the SP.
Once configured, Salesforce end users will be presented with the ForgeRock Sign In screen to authenticate before being redirected back to Salesforce. Users who do not already exist in your Salesforce domain will be automatically provisioned when they first log in (providing you enable user provisioning in Salesforce).
Note
Salesforce as an SP is not available for all Salesforce editions. See the Salesforce documentation for further details.
Steps involved:
- Create a Circle of Trust (COT)
- Create the hosted IdP in Identity Cloud
- Configure Salesforce
- Create the remote SP in Identity Cloud
- Create the end user journey
- Test the end user experience
- Troubleshooting
Prerequisites
- You have a working Identity Cloud tenant.
- You have a Salesforce developer edition account. See Salesforce Developers for further information.
- You have registered a remote site in Salesforce. The remote site's URL must point to your Identity Cloud tenant, for example,
https://<tenant-env-fqdn>
. - Identity Cloud users who already exist in Salesforce must have a Federation ID configured in Salesforce. This is usually their email address.
Creating a Circle of Trust (COT)
- In the Identity Cloud admin UI, go 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, ForgeRockCOT, and click Create.
- Add a description for the COT and click Save Changes.
Creating the hosted IdP in Identity Cloud
This step involves creating the hosted IdP in Identity Cloud and then generating the IdP metadata. The metadata contains information about the IdP which is required when configuring Salesforce.
Create a hosted IdP
- In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Hosted.
- Complete the following configuration:
- Entity ID: Enter an ID (no special characters or spaces) for your hosted identity provider, for example, ForgeRockIDP.
- 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: Enter a URL-friendly value to identify the identity provider, for example, idp.
- Service Provider Meta Alias: Leave blank because we're only creating a hosted IdP.
- Circles of Trust: Select the COT you created, for example, ForgeRockCOT.
- Click Create.
- In the Assertion Content tab, configure the signing and encryption options as follows:
- Enable the following options for request/response signing:
-
Authentication Request
-
Artifact Resolve
-
- Scroll to Secret ID And Algorithms, and add the required algorithms. The suggested ones below have been tested by ForgeRock for Salesforce integrations:
-
Digest Algorithm: Select the required digest algorithm, for example,
http://www3.org/2001/04/xmlenc#sha256
-
Encryption Algorithm: Select the required encryption algorithm, for example,
http://www3.org/2009/xmlenc11#rsa-oaep
-
Digest Algorithm: Select the required digest algorithm, for example,
- Enable the following options for request/response signing:
- Scroll to NameID Format and configure the mapping as follows:
- Enter
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
in the Key field. - Enter
mail
in the Value field. This will use the email address from the identity in Identity Cloud. - Click Add.
- Enter
The NameID Value Map appears like this:
- Scroll down and click Save Changes.
- Select the Assertion Processing tab and configure the attribute mapping for your assertion. You need to specify the name of a SAML attribute to send to Salesforce that maps to the
mail
attribute (this will use the email address from the identity in Identity Cloud), and you also need to map Salesforce fields to Identity Cloud attributes so that Salesforce can create the user. For example:
SAML Attribute | Local Attribute |
---|---|
SSOID (the name of the SAML attribute to send to Salesforce) |
mail |
User.Email |
mail |
User.ProfileID |
"Standard User" |
User.LastName |
sn |
User.Username |
mail |
- Click Add.
The Attribute Map appears similar to this:
- Scroll down and click Save Changes.
Generate the hosted IdP metadata
You'll use the IdP metadata when you configure SAML SSO in Salesforce.
To access the IdP metadata, navigate to the metadata URL in your browser, in the following format:
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 Salesforce
Disclaimer
ForgeRock assumes no responsibility for errors or omissions in the third-party software or documentation.
Configure SAML SSO
Refer to the Salesforce documentation for guidance on configuring Salesforce as the SP with SAML SSO.
Use the following configuration for Identity Cloud:
- Choose New from Metadata URL and enter the metadata URL you used to test your hosted IdP metadata in Identity Cloud, for example: https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=ForgeRockIDP&realm=/alphaThe settings in this metadata are applied when you create the configuration.
- Other settings:
-
SAML Identity Type: Select
Assertion contains the Federation ID from the User object
. Identity Cloud will pass a user identifier in the SAML assertion. -
SAML Identity Location: Select
Identity is in an Attribute element
. - Attribute Name: Enter the attribute name you configured in the hosted IdP, for example, SSOID.
-
Service Provider Initiated Request Binding: Select
HTTP POST
. -
Single Logout Request Binding: Select
HTTP POST
. - User Provisioning Enabled: Select to allow users to be just-in-time provisioned the first time they log in.
-
SAML Identity Type: Select
Once you've saved the configuration, download the metadata. This creates an XML file of your SAML configuration settings. You'll need this metadata later when you complete the remote SP configuration in Identity Cloud.
Enable the SAML login
To enable Salesforce users to log in using SAML SSO you will need to add the Identity Cloud identity provider (for example, ForgeRockIDP) to your Salesforce domain as an authentication service.
Creating the remote SP in Identity Cloud
- In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Remote.
- Import the metadata file that you exported from Salesforce, select the COT you created (for example, ForgeRockCOT), and click Create.
- In the list of entity providers, click the name of the remote SP entity provider you just created.
- Select the Assertion Processing tab and configure the attribute mapping for your assertion. You should create attribute mappings to match the ones you created for the hosted IdP. For example:
SAML Attribute | Local Attribute |
---|---|
SSOID (the name of the SAML attribute to send to Salesforce) |
mail |
User.Email |
mail |
User.ProfileID |
"Standard User" |
User.LastName |
sn |
User.Username |
mail |
- Click Add.
The Attribute Map appears similar to this:
- Click Save Changes.
Testing the end user experience
To log in to Salesforce using Identity Cloud as the SAML identity provider:
- Go to your Salesforce instance login screen and click the Identity Cloud SAML IdP, for example, ForgeRockIDP.
- In the ForgeRock Sign In screen, enter your username and password, and click Next.
After successful authentication, you are logged into Salesforce.
Troubleshooting
If your users are unable to log in to Salesforce, review the SAML login history to determine why. You can use the SAML Assertion Validator to troubleshoot errors in the SAML assertion.
See Also
SAML 2.0 federation in Identity Cloud
Salesforce SSO integration with Identity Cloud as OIDC identity provider
Salesforce SSO integration with Identity Cloud for social authentication/registration