Single Sign On from Production to Sandbox

Make it oh-so-easy for users to test changes in a sandbox by seamlessly logging in from production!

Summary:
With this approach, your users can login to a sandbox directly from the app launcher in production. This requires no code, just clicks, and you can control exactly which users can use this option via profiles or permission sets.

Here is a gif to show how simple this is for users, in case you have never clicked on an app in the app launcher before.

The Technical Details:
This approach uses production as the identity provider and a sandbox as a service provider. Authentication is managed using an identity-provider initiated oauth flow.

This implementation is a variation on the approach described in this H&T article. The approach in the article requires users to navigate to the sandbox my domain in their browser, where they can click on a button that authenticates against production using Single Sign On. The main difference in my approach is that users can initiate the authentication directly from the app launcher in production. This approach is easier for users as there is no need to remember or bookmark a sandbox mydomain link. And its much easier than the default setup where admins must reset user emails and passwords, and users must login from test.salesforce.com.

The Ingredients:
Your production org is the identity provider which validates that a user is in fact who they say they are

Your sandbox is the service provider which is the system your users want to access.

A connected app will be created in production and will be added to the app launcher. You cannot deploy connected apps from a sandbox - they have to be created in prod.

The Recipe:
Production
Setup Salesforce Identity Provider

• From Setup, in the Quick Find box, enter Identity Provider, and select Identity Provider. Click Enable Identity Provider.
  
• On the Identity Provider page, click Download Certificate. (A certificate is created automatically when you enable Salesforce as an identity provider)
• Copy the Salesforce Identity URL listed under SAML Metadata Discovery Endpoints.

Sandbox
Setup the Salesforce Service Provider

• From Setup, in the Quick Find box, enter Single Sign-On Settings, then select Single Sign-On Settings.
• Click Edit. To see SAML SSO settings, select SAML Enabled. Save the change.
• Click New from Metadata URL. Paste the URL and click Create. This option automatically completes SSO settings including name, issuer, and entity id.
• For Identity Provider Certificate, upload the certificate you downloaded earlier from the identity provider.
• For SAML Identity Type, select Assertion contains the User ID from the User object
• Click save
• Copy login url, entity id, and issuer for future reference

Production
Create new connected app (based on this documentation)

• Setup > App Manager > New Connected App
• Complete the connected app’s basic information. The name that you use is what will show up in the app launcher, so give it a name that will make sense to end users
• Under Web App settings, select Enable SAML.
• For Entity ID, paste the Entity ID from the service provider.
• For the ACS URL, paste the Login URL for the org or site.
• For Subject Type, select User ID.
• Signing Algorithm: 256 is better!
• Save

Give yourself access to the connected app for testing

• Click Manage on the connected apps page.
• Select Manage Profiles or Manage Permission Sets and add the profiles or permission sets you want to use to test access to the service provider.

Enable Connected app in app launcher

• Copy idp-initiated login url from the connected app itself, under SAML login information – NOTE: you have to literally copy the text, not the link, as in lex it is a js redirect blah blah. Just the text on the page is what you need.
• Click ‘edit policies’ button
• Set Start URL for the connected app to the idp-initiated login url for the connected app! Now when the connected app is launched, it hits the IDP initiated login url for itself (prod) which logs you into the service provider (sandbox)
• Save

Test from app launcher

• open app launcher, and type in the name of your connected app
• if there is an error, go into the single sign on settings in the sandbox and review the saml assertion validator, and the users login history. those both can give you clues for debugging.

Adding Encryption
Once your tests are successful, encrypt the assertion to make it more secure

Sandbox:

• create a new certificate in sandbox named assertionDecryptCert
• download the certificate
• edit single sign on settings in sandbox
• set assertion decryption certificate = assertionDecryptCert
• save
• copy the new login url

Production:

• manage connected app - edit
• update ACS url to use the new login url above
• check ‘encrypt saml response’
• upload the assertionDecryptCert
• select 256 - more secure!
• save

Test it out again - with encryption!

• it should work exactly as before, but more securely
• if you run into any errors, go into the single sign on settings in the sandbox and review the saml assertion validator, and the users login history. These should give some clues as to the issue. Reach out to me on twitter and I will try to help!

Give Access to Users
Give access to users via profile or perm set as required. See this trail for details.

THE END!

Notes

• when you refresh the sandbox you will have to re-enable SSO in the sandbox, and update the acs url and the certificate in prod
• using user ID for the SAML Identity Type means this will only work for users who existed in production when the sandbox was created. if you are already using federation id for SSO, or if you want the flexibility to add users in sandbox and map to production, you can use the federation Id field and setup a flow or manual process to ensure that federation Id is populated as required.

EPILOGUE: Sandbox Refresh Details
After refreshing sandbox, these steps should re-establish the connection
in prod

• go to connected app and copy metadata discovery url
• download the idp certificate in use in prod

sandbox

• enable saml (important!!)
• single sign on settings - create from metadata url
• follow the info like you are creating it again, including: – uploading the ipd cert to sandbox – set the identifier, etc as the first time – enable encryption of the assertion (if desired, prob a good idea…) – copy the login url from saml settings in sandbox and replace the acs url on the connected app in prod – you do not need to logout from sandbox to test the updates to the connected app. just test it from prod, and if there are errors they should show up in the saml assertion validator. once that seems to be working, logout from sb and test again.