The main goal of this blog is to show how to integrate Salesforce Sandbox environment with Azure Active Directory, using the Windows Azure AD single Sign-On configuration option.
Before continuing, you should meet the following requirements:
- A valid Azure Active Directory Subscription
- A Sandbox environment on Salesforce .com with a System Admin user on this environment.
NB: In this blog, i used the ‘.uisandbox’ as a suffix. You should replace it by the suffix attributed to your sandbox platform
1- Why do not use the same integration procedure with Salesforce (non-Sandbox) ?
A question one may ask is why not use the same Azure Active Directory integration procedure with a (non-Sandbox) Salesforce environment (Described here in a Microsoft Article). The reason is simple : When you get a Salesforce Sandbox environment, your Salesforce production user accounts are cloned to the Salesforce Sandbox environment (Automatically on the refresh process), but a ‘.uisandbox’ suffix is added to the UserName for each user. This is intentional since a user will know that he is using a Sandbox environment and to avoid confusion just by looking to his username. The email address is also modified to a strange format : Example : Samir.Farhat@Ent.com –> Samir.Farhat=Ent.email@example.com. I personally recommend modifying the email address of a user to match its real email address, but it’s not a must. So, the integration procedure for a production SalesForce environment is not valid for the Sandbox one (The users identifiers changed) . A tuning must be brought in order to achieve the integration. This is the blog’s purpose.
There is an Official Microsoft article about configuring salesforce ‘sandbox’ environment with Azure AD, but, it seems that the content is not accurate and you will not be able to successfully configure the integration.
2- How this will work ?
It’s simple. Thanks to the Azure Active Directory new SAML attributes option (Currently In preview) , we will tell Azure Active Directory to add, every time that an authentication is requested, the suffix ‘.uisandbox’ to the UserName claim. Great !
3- Steps for Integrating Salesforce Sandbox environment with Azure Active Directory
3.1- Configure the Salesforce ‘Sandbox’ application on Azure AD
Where : Azure Management portal
A- Deploy the Salesforce sandbox application
First, connect to the Azure Management portal with an Active Directory tenant administrator account. Go to Active Directory –> Domain Name –> Applications and Click on the Add button
Choose Add an application form the gallery
On the Search bar, type salesforce. Choose the Salesforce Sandbox. Type a Display Name for this application (Example : MySalesforceSandbox) and click Okay
Wait for the application to be successful added. Now we can begin configuring our SSO with Azure AD
B- Configure Single Sign-ON
In this phase, we will configure Azure AD to ‘accept’ authentication requests from Salesforce. In other words, we will configure Azure AD as an identity Provider for Salesforce ‘sandbox’.
Click on Configure Single sign-ON
Select ‘Microsoft Azure AD single sign-On’
Type the Sign ON URL. The sign-on URL is the Salesforce ‘custom’ Sandbox domain URL. Go to step ‘3.2.A- Create and switch to a custom domain’ if you are not aware of this information. The URL must begin with https:// and ends with my.salesforce.com
This step is very important, since it contains ‘required information’ for setting up the SAML settings in Salesforce. Keep the following information:
- Download the Certificate in a local location. You can name it ‘AzureADSalesforcesandboxsso.cert’
- Save the following URL to a text file for example (Of course you can retrieve them later)
- Issuer URL
- Remote Login URL
- Remote Logout URL
Type an Email address to receive information about SSO events with this application.
This phase is completed, now we will pass to the next step, a very crucial configuration.
C- Change the SAML attributes claims to match the Salesforce ‘Sandbox’ users settings
Go to Attributes (Even if this feature is currently on preview, it works as expected)
The goal is tell Azure AD that the Name it will receive during the SAML handshake, is not the UserName is AzureAD, but it’s a concatenation of the UserName is AzureAD and the ‘.uisandbox’ expression.
For this, we will edit the ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name’ attribute like the following.
Click on the Edit symbol for the ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name’ attribute
Change it like the following:
Attribute Value : Join()
STRING1 : User.userPrincipalName
String2 : uisandbox
Separator : .
Click OK then Click Apply Changes
NB: In my example, I used the Name as a claim attribute, you can use the email address if you want. But, you have to also to change it in the SAML settings configuration on salesforce on Step ‘3.2.B- Create a new SAML SSO settings’
3.2- Configure the Salesforce ‘Sandbox’ SSO on Salesforce
Where : Salesforce Sandbox portal
Go to https://test.salesforce.com and login with a ‘sandbox’ user account (This user must have System Admin rights on this environment). NB: As discussed, The sandbox user account by default ends with .uisandbox
A- Create and switch to a custom domain
First step to do is to switch to the sandbox domain if it’s already created, or create a new domain for your environment (For users not familiar with Salesforce domains, a Salesforce domain is just a domain name to be used when connecting to your Salesforce environment, this will make you use a domain name like ‘MysalesforcedomainName.salesforce.com’ instead of ‘test.salesforce.com’).
Go to Setup –> Domain Management –> Domains
If you did not already created a domain, create a new one.
Now, go to Setup –> Domain Management –> My Domain and login to your domain by clicking on Click here to login
Once connected, you will be switched to the custom domain
B- Create a new SAML SSO settings
Now, it’s the main part, where we will configure the settings that will allow the SSO to Azure AD and the matching between the user in Azure AD and in the Salesforce ‘sandbox’.
Go to Setup –> Security Controls –> Single Sign-On Settings and click New
You will have to provide the following information:
|Name||A name for your SSO configuration (Will be shown for users so choose a descriptive Name)||AzureADSSOSandbox|
|API Name||Used by SalesForce, keep it the same as the Name||AzureADSSOSandbox|
|Identity Provider Certificate||The Certificate that you bring from the Azure AD SSO configuration (AzureADSSOSalesforce.cert)||AzureADSSOSalesforce.cert|
|Entity Id||Used by Salesforce, need to set it to https://test.salesforce.com||https://test.salesforce.com|
|Issuer||Paste here the Issuer URL got from Azure ADD SSO configuration wizard|
|Request Signing Certificate||Which Certificate to use to sign the request||Default Certificate|
|Request Signature Method||The method for the Request signing certificate||RSA-SHA1|
|Assertion Decryption Certificate||If your assertion is encrypted, choose a certificate to decrypt it with. Otherwise, choose Assertion not encrypted||Assertion not encrypted|
|SAML Identity Type||Which identity type will be used||Assertion contains User’s salesforce.com username|
|SAML Identity Location||Where the identity is located||Identity is in an Attribute element|
|Attribute Name||Which attribute will be used. In our configuration, the name will contain the name that will match the user name in Salesforce ‘sandbox’. In fact, we have to set this attribute in Azure AD to add the ‘.uisandbox’ suffix to the user name||http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name|
|Name ID Format||leave it blank|
|Service Provider Initiated Request Binding||HTTP POST|
|Identity Provider Login URL||Paste here the Identity Provider Login URL copied from the Azure AD SSO config wizard|
|Identity Provider Logout URL||Paste here the Identity Provider Logout URL copied from the Azure AD SSO config wizard|
|Custom Error URL||Leave it blank|
|User Provisioning Enabled||Check this box if you want to enable the User Provisioning feature on Azure AD|
C- Enable the SSO settings for the ‘salesforce’ domain
This is the last step in this configuration walkthrough. We have now to enable the configured SSO authentication for the ‘salesforce’ sandbox domain.
Go to Go to Setup –> Domain Management –> Domains
Select your ‘sandbox’ domain and click Edit
Affect the SSO configuration which was created during the previous steps to this domain then click Save
- You can affect more than one SSO configuration to your domain
- If you uncheck the ‘Login page’, users will not be able to use local ‘salesforce’ users to login to the domain
3.3- Test the configuration
Now, we can test our configuration.
First, you must assign users or groups to be be authorized to use this application (to use the Azure AD Authentication).
In Azure AD, go to the Application –> Users and Groups. Choose the ‘All Users’ or ‘Groups’ filter and assign the desired users.
Now connect to the ‘Salesforce’ sandbox URL (sign-on URL ie your Salesforce ‘sandbox’ domain name ). And choose your ‘AzureAD SSO’ that you already configured.
You have successfully logged using SSO to Salesforce ‘sandbox’ environment.