Enable SSO in Salesforce with Auth0 as the IdP and Salesforce as the Service Provider
Single Sign-on (SSO) is the three letter acronym that should make everyone’s life easier by enabling users to authenticate with multiple systems with a single set of credentials.
This article details integrating Salesforce as a Service Provider (SP) with Auth0 as an Identity Provider (IdP) using SAML2.
Configure Auth0
Auth0 has many preconfigured SSO Service Providers (SP). There is one for Salesforce but it lacks any customization like setting the SAML response or assertion values. The instructions for manually configuring an SP are pretty straight forward. Start with Creating an application in Auth0.
This one is eponymously namedSalesforce and it’s been assigned a client id and a client secret by Auth0. Scrolling to the bottom we need to get the certificate. The Salesforce documentation does not specify the format of the certificate it requires and Auth0 provides three options.
The correct format of the certificate for Salesforce is CER. Download this and we’ll use it in the Salesforce configuration section later.
Finally, select the tab Endpoints tab, scroll down to the SAML section and copy the SAML Protocol URL.
You will need this value in the last step of configuring Salesforce. We’ll come back to this application in Auth0 after we configure Salesforce.
Configure Salesforce
Salesforce has extensive documentation for multiple scenarios based on your needs. This covers Salesforce as a Service Provider specifically the configuration section. As admin, navigate in Salesforce to the Single Sign-On Settings in setup and click Edit. Select the SAML Enabled checkbox then click save.
Under the SAML Single Sign-On Settings select New and create a new SAML config.
Reviewing the Salesforce as Service Provider page the following information is needed:
- Issuer — The unique URL that identifies your identity provider in SAML assertions sent to Salesforce.
- Entity ID — A unique URL that identifies your identity provider as the recipient of SAML requests that Salesforce sends. This entity ID must be the same as the
<saml:Issuer>attribute in the SAML assertion. - Identity Provider Certificate — The authentication certificate issued by your identity provider. The certificate size can’t exceed 4 KB. If it does, try using a DER encoded file to reduce the size.Request Signing CertificateThe certificate to generate the signature on a SAML request to the identity provider for a service provider-initiated login. This certificate is saved in your Certificate and Key Management settings. If you haven’t saved a signing certificate, Salesforce uses the global proxy certificate. A signing certificate is preferred because it provides more control over events, such as certificate expiration.
- Request Signature Method — The hashing algorithm for signed requests, either
RSA-SHA1orRSA-SHA256. - Assertion Decryption Certificate — If the identity provider encrypts SAML assertions, select the assertion decryption certificate saved in your Certificate and Key Management settings. This field is available only if your org supports multiple SSO configurations. For more information, see Set Up an Identity Provider to Encrypt SAML Assertions.
- SAML Identity Type — The SAML assertion element that contains the string identifying a Salesforce user. Values include:
Assertion contains User’s Salesforce username — Use this option if your identity provider passes the Salesforce username in SAML assertions.
Assertion contains the Federation ID from the User object — Use this option if your identity provider passes a user identifier for customers or partners in the SAML assertion
Assertion contains the User ID from the User object — Use this option if your identity provider passes a user identifier for users from your org in the SAML assertion. - SAML Identity Location — The SAML assertion element that specifies where to locate the user’s identity. Values include:
Identity is in the NameIdentifier element of the Subject statement — The Salesforce Username or FederationIdentifier is in the<Subject>statement of the assertion.
Identity is in an Attribute element — The Salesforce Username or FederationIdentifier is specified in an<AttributeValue>in the assertion’s<Attribute>.
Looking at the image below, we can see where these attributes map based on my configuration with Auth0
The first field that I had some trouble with was Issuer. Initially I believed that this would be the value topcoder.auth0.com. After some initial testing I was able to determine that the value should be urn:topcoder.auth0.com. I was able to confirm this after checking the SAML Validator output in Salesforce (This test was done after all my configuration was complete. You won’t be able to use the validator until your setup is finished).
This is a little confusing because the documentation for Issuer reads:
The unique URL that identifies your identity provider in SAML assertions sent to Salesforce.
But the very next field Entity ID reads
Entity ID — A unique URL that identifies your identity provider as the recipient of SAML requests that Salesforce sends. This entity ID must be the same as the
<saml:Issuer>attribute in the SAML assertion.
I’ll revisit this confusion again when I go back to the Auth0 configuration and generate the SAML assertion. I later determined that the correct values are urn:topcoder.auth0.com for issuer and https://saml.salesfoce.com for the Entity ID. It seems that I’m not the only one confused about these values.
Next upload the certificate you downloaded in the previous section configuring the Auth0 application. Once you save your configuration, you should see the the CN and expiration date of the uploaded certificate. I left the request signature method as the default of RSA-SHA256. I left the checkbox unchecked for Use digest algorithm based on Request Signature Method and I did not require the assertion to be encrypted.
For the SAML Identity Type I’m using the Federation ID from the user object. We are using the identity database for Topcoder that defines users handles. User handles are Id’s that are immutable, reducing the possibility of incorrect provisioning. We had to upsert handles for all the existing users. The next section is related, where to find the SAML Identity Locationin the SAML response. With the customization in the next step, this will be set to the NameIdentifier element in the subject of the response. The final configuration for the SP request is the binding POST or Redirect, I’ve configured this for POST.
The last value we need to configure in Salesforce is the Identity Provider Login URL. This was the value copied above from SAML Protocol URL in Auth0 and has the form https://<DOMAIN>.auth0.com/samlp/<some random string>.
Once you save these values you should be able to select the configuration you just created and see endpoints at the bottom of this record
You will need the Login URL for the next section.
Configure Auth0 SAML2 WEB APP
Back on the application you created in Auth0, navigate to the Addons page and select the add on SAML2 WEB APP.
You should now see a screen similar to this
Here we see several useful parameters including the issuer value that I struggled to find earlier. Select the Settings tab at the top.
Take the Login URL from above and use that as your Application Callback URL. The Settings section provides the ability to map fields and and values in the response. The JSON below is what I used to map nickname or the topcoder handle to nameIdentifier. Nickname holds the handle of the authenticated user.
{
"mappings": {
"nickname": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
}
}Now save the configuration and click debug. You should see a screen similar to the one below that provides the SAML response.
Review your response and ensure that you have setup any other parameters needed in the settings section. Notice the value of issuer, this was how I confirmed the value that Salesforce was expecting above. You may need to review the settings and pass additional parameters based on your business requirements.
At this point, you should be able to test the login process following the Login URL from the Salesforce SAML configuration.
Configure Salesforce to allow for SSO authentication
Now that we have configure both Salesforce and Auth0, we need to make it easy for the users to use SSO. This is accomplished by adding an identity provider to the login page, then preventing password logins.
To configure the login page to show our new identity provider navigate to the My Domain setup page and scroll to the bottom. There you will see authentication configuration settings. Edit this section and toggle the authentication service you added in previous steps. In my case, I named my configuration service Auth0 so that name shows up in the list. Toggle the checkbox next to the name you created and click Save.
If you navigate to your vanity URL you should now see a button that will redirect you to your IdP. You should now see a login page similar to this.
Preventing password logins is pretty simple, navigate back to My Domain in setup and edit the policies section. Select the Prevent login from https://loign.salesforce.com option and click save.
Lastly, in the Single Sign-On settings, edit the config, toggle the Disable login with Salesforce credentials checkbox and save.
Recommendations
- Create a sandbox in Salesforce to test the SSO configuration. This will ensure that you can verify various configuration parameters before you move to production. I used an external Id and the SSO Federation Id that made user mapping SFDC environment agnostic. You will have to consider your SAML Identity Type as you test in your sandbox.
- For Entity ID I ran across this documentation that leads me to believe that the value should be your vanity URL. My configuration works and may need to be updated in the future.
- When choosing an identifier from a federated source, if you have a choice, choose an immutable one. I could have chosen to use the email address as an example. The problem with that is that the user can change their email. Not only would this change break the integration with SSO, it presents a security risk. Topcoder handles are immutable, they can’t be changed by the user.
- Disabling login through login.salesforce.com should also be enabled. Step #1 in the procedure at that URL. I didn’t do this initially which left an a security hole. We use a vanity URL topcoder.my.salesforce.com typically to login, however, a user could also login directly at login.salesforce.com bypassing this and any policy defined for that access method.
- We had to upsert our Federated ID into the user object for all of our existing users.
- I love https://www.planttext.com/ and use it exclusively for drawings. The diagram at the top of this is from planttext and also in this gist.
