Share via

Azure Active Directory integration with Salesforce 'Sandbox'

  • Article

The main goal of this article 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.

*Important notice
*

  • In this article, i used the ‘.uisandbox’ as a suffix. You should replace it by the suffix attributed to your sandbox platform
  • This article is only applicable if you use only one Sandbox environment. If you use more than one, and use the same Azure Active Directly for SSO, you will need extra steps that i will publish in two future articles.

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.com@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 article’s purpose.

NB

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-11-37-03_thumb.png?w=702&h=401

Choose Add an application form the gallery

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-11-37-44_thumb.png?w=602&h=453

On the Search bar, type salesforce. Choose the Salesforce Sandbox. Type a Display Name for this application (Example : MySalesforceSandbox) and click Okay

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-11-39-41_thumb.png?w=602&h=422

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-11-42-29_thumb.png?w=602&h=340

Select ‘Microsoft Azure AD single sign-On’

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-17-04-57_thumb.png?w=602&h=441

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-17-14-08_thumb.png?w=602&h=435

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-17-16-11_thumb.png?w=602&h=441

Click Next

Type an Email address to receive information about SSO events with this application.

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-17-16-47_thumb.png?w=602&h=428

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)

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-17-24-23_thumb.png?w=602&h=294

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-17-28-43_thumb.png?w=602&h=210

Change it like the following:

Attribute Value : Join()

STRING1 : User.userPrincipalName

String2 : uisandbox

Separator : .

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-17-29-51_thumb.png?w=526&h=453

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-11-46-11_thumb.png?w=602&h=306

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-12-01-02_thumb.png?w=602&h=202

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-12-52-42_thumb.png?w=602&h=275

Once connected, you will be switched to the custom domain

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-12-52-58_thumb.png?w=602&h=88

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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-12-54-12_thumb.png?w=730&h=234

You will have to provide the following information:

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-08-at-16-58-03_thumb.png?w=602&h=282

Setting

Description

Example
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

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-04-at-12-18-06_thumb.png?w=602&h=441

Affect the SSO configuration which was created during the previous steps to this domain then click Save

NB

  • 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.

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-18-08-43_thumb.png?w=714&h=451

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.

https://buildwindows.files.wordpress.com/2015/09/snap-2015-09-07-at-18-10-52_thumb.png?w=704&h=372

You have successfully logged using SSO to Salesforce ‘sandbox’ environment.