This is an update to my previous Cool Solution: Integrating Salesforce.com and NetIQ Access Manager using SAML2. If you are new to SAML2 and federation, you may still find my first article useful as I endeavored to explain each concept as each configuration step is described. This article is not inclusive, but an update to that article. In the years since it was written, several new features related to SAML have been added to Salesforce.com. I describe some of those here and also add some extra tips along the way.
Since my first article, Salesforce.com has made some changes to their support of SAML:
Don't be surprised if your Salesforce.com admin UI does not exactly match my screen shots. I have found that your update level and the age of your account can influence what you see in your admin screens. Functionality is usually unaffected, but not always. Throughout this article I point out some of these idiosyncrasies. Unfortunately, I was not always able to determine the root causes and/or often found too many dependencies to cover every possibility.
As a general rule you should also be very careful with case sensitivity. I have run into mind-numbing issues due to case sensitivity so you should assume this whenever federating. For example Salesforce.com's "Federation ID" is case sensitive.
Service Provider (SP) Configuration Options
Your Salesforce.com SP configuration options now offer you more flexibility and control. This is most evident when you enable the SAML "Multiple Configs" option where you can simultaneously federate with more than one IDP. Enabling this feature opens up options that I cover in the "Flexible User Account Matching / Multiple SAML Configurations" section. Keep in mind that any change to the Salesforce.com SAML SSO settings could affect your metadata which may require you to update your IDP(s) configuration. Fortunately Salesforce.com has made updating you metadata a piece of cake via the Metadata Export / Download feature.
Metadata Export / Download Tool
As with any SAML federation you must configure both your NetIQ Access Manager (NAM) Identity Provider (IDP) and Salesforce.com Service Provider (SP) to establish a trust. In my first article, I described how to do this between your NAM IDP and Salesforce.com SP. At that time, you had to create your specific Salesforce.com metadata from scratch using the sample that I provided as a template so you could import it into your NAM IDP configuration. Now you simply click a button to download your metadata from Salesforce.com. Below are two slightly different views of this feature. Which one you will see is primarily dependent upon whether you have the SAML multiple configurations feature enabled (more on this in a later section). To download your specific metadata go to your Salesforce.com instance:
Login as administrator | Administration Setup | Security Controls | Single Sign-On Settings | Download Metadata:
The resulting metadata file will also include a certificate. For NAM to trust/use this certificate, the trusted root certificate chain that minted the certificate must exist in the NAM certificate trust store(s). While NAM 3.2 now includes many well-known CA trusted root certificates, it may not include the specific one you need for Salesforce.com. Your NAM Identity Server cluster will display health errors in the NAM admin console if you have certificate related problems. Below is a way to easily get importable CA trusted root certificates for NAM. While the example below is for salesforce.com, this approach can be used any time you need a trusted root certificate.
First export your Salesforce.com metadata file as described above. Open the resulting .xml file with a file editor. Look for the certificate in the X509Certificate element (between <ds:X509Certificate> and </ds:X509Certificate>). Copy that information into its own file and give it a .cer file extension. Windows will recognize this as a certificate. Open the file by double-clicking on it:
Next, click on the "Certification Path" tab to see the chain of authority for the certificate:
You will need the trusted root certificate for every CA in the chain that you see listed. In the example above, select the "VeriSign Class 3 International Server CA – G3". Then click the "View Certificate" button:
Next, click the "Details" tab:
From here you can export the CA trusted root certificate by clicking the "Copy to File…" button. This will launch the Windows Certificate Export Wizard. Select .DER encoded when prompted, give the file a name, and save the file.
Repeat this process for every CA in the certificate path chain. Finally, use the NAM Administration Console to import the resulting CA trusted root certificates into your NAM keystore(s) as usual.
Service Provider (SP) Initiated Login / My Domain
In my first article, I described how Salesforce.com did not support SP-initiated login but only IDP-initiated login. IDP-initiated login is dependent upon on a complex URL to access an SP which makes it hard for users to remember and also causes deep-linking and bookmarking problems for users. SP-initiated login solves these problems by letting the user use a simple and intuitive URL to access the target application. This also makes it possible to use deep links that take users directly to a function within the SP. This is often handy when an SP application or user sends deep-links within emails to assist in workflow processing.
To enable SP-initiated login in Salesforce.com, you must enable and configure the Salesforce.com "My Domain" option. Defining your own domain provides the basis for an SP-initiated capable URL. Before you establish your own domain for your Salesforce.com instance refer to the Salesforce.com documentation. When you are ready:
Login as administrator | Administration Setup | Domain Management | My Domain:
Once you establish your domain, your Salesforce.com URLs will change. If you have already configured your NAM SP for Salesforce.com, you will need to update your configuration (e.g. metadata) to reflect the new URLs. No other change is required in your NAM configuration; simply notify your users about the new URL to access Salesforce.com.
Federated / Just-In-Time Provisioning
Most SAML federated systems require each user to have an account within the SP system before a user can login. While not used for authentication, such an account is often used for fine-grained access control and reporting within the application. Sometimes called a "shadow account", a unique account is required for each user before they can use Salesforce.com.
In my first article, I mentioned that the Salesforce.com shadow account could be created manually or provisioned and de-provisioned in real-time using NetIQ Identity Manger. I also mentioned the concept of "federated provisioning" where the shadow account can be automatically created by the Salesforce.com SP dynamically during the first successful authentication. At that time, Salesforce.com did not support this idea but does so now through a feature they call "Just-in-Time Provisioning." Conceptually Just-in-Time Provisioning is where the user described within an IDP assertion can't be matched with an existing SP shadow account. Instead of simply failing, a new shadow account is automatically created within the SP system (e.g. Salesforce.com) on the fly.
Federated / Just-in-Time provisioning is handy and convenient but it is not always the best choice for account management since it often leaves behind "orphaned accounts" in the SP system. Completely de-provisioning accounts has benefits such as preventing unnecessary license costs, increasing security and/or eliminating compliance violations, and provides full control over the account provisioning process. If any of these are concerns for you, NetIQ Identity Manager is a much better choice to compliment NAM with Salesforce.com.
Whenever a user successfully authenticates to your IDP, a SAML assertion is presented to the Salesforce.com SP. Before access is granted, the unique user represented in the assertion must be matched to a Salesforce.com shadow account (more info on user/account matching follows in the next section). Normally, for a match to be made, the shadow account must first exist within the Salesforce.com system. With Just-in-Time provisioning, if a match is not found Salesforce.com uses the identity data contained in the SAML assertion to automatically provision the shadow account in its database during the first successful authentication of that user through your NAM IDP. Salesforce.com supports a long list of user attributes that can be used to create this user and keep the data in sync with your internal user store. You simply add the attributes you want/need to your NAM Attribute Set so they are included in assertions for Salesforce.com to consume.
Just-in-Time provisioning also requires you to use the shadow account "Federation ID" for user matching (covered in the next section). For a complete list and instructions for using this feature please refer to the Salesforce.com Single Sign-On documentation.
Flexible User Account Matching / Multiple SAML Configurations
While this is not a new feature, it is not one I covered in my first article and its configuration has changed since then.
When your NAM IDP authenticates a user, it creates a SAML assertion that includes identity information unique to the authenticated user sent to the requesting SP (e.g. Salesforce.com). Typically, the assertion is sent to and used by the trusted SP to match the authenticated user to a "shadow account" within the Salesforce.com system. Salesforce.com provides you some flexibility on how this match is performed. You can configure how it reads a SAML assertion and with which shadow account data it compares to find a match. NAM allows you to configure how and what information is sent in assertions to be in harmony with your Salesforce.com configuration.
This is one Salesforce.com feature where I encountered some inconsistency. I was not able to get this feature working with an old Salesforce.com instance, yet with a new instance it worked beautifully the first time. I suspect the reason was related to the SAML "Multiple Configurations" feature. This feature had to be manually enabled on my old instance, but was enabled by default with my new instance. Note that once this feature is enabled on your Salesforce.com instance, it can't be disabled (it does warn you). Below are screen shots of both for your comparison:
Login as administrator | Administration Setup | Security Controls | Single Sign-On Settings:
With SAML "Multi Configs" enabled:
Unfortunately subsequent Salesforce.com SAML Single Sign-On admin screens will differ between those enabled with or without SAML "Multiple Configs" enabled. Since this is an update to my original, the remainder of this section has "Multiple Configs" enabled. If you do not have this feature enabled, some of your screens will look different. The Salesforce.com user matching configuration is very flexible so there can be many variations. I provide you with three examples, but others are possible.
For this first example, as in my first Cool Solution, I keep things simple and use the Salesforce.com default settings wherever possible. As mentioned, the Salesforce.com configuration looks a little different from my first Cool Solution because the "Multiple Configs" feature is enabled. Fortunately, NAM configuration has always been very flexible so its screens are essentially identical. Otherwise the configuration is essentially unchanged but described more thoroughly here.
The SSO settings that govern how Salesforce.com performs user matching are "SAML User ID Type" and "SAML User ID Location" settings. To view/configure these settings:
Login as administrator | Administration Setup | Security Controls | Single Sign-On Settings:
Click either "New" or "Edit" as appropriate to see the user matching configuration options:
The radio button selections highlighted and depicted above are the defaults. They tell Salesforce.com how to match the authenticated user to a local shadow account by telling it what to use from the SAML assertion for its matching criteria.
The "SAML Identity Type" setting determines which local shadow account attribute is searched to find a match. This can be the Salesforce.com "username", "Federation ID", or "User ID" field. Salesforce.com shadow accounts require the "username" field be populated whereas the "Federation ID" is optional. I have not tried to use the "User ID" field. When manually creating a user account in Salesforce.com, it automatically copies the user's email address to the username field so it is very common to configure NAM to send the user's email address value so that is what I have done in this example.
The "SAML Identity Location" setting determines where Salesforce.com is going to look for the "username", "Federation ID", or "User ID" value in assertions. The location can be either the NameIdentifier value (always in the subject statement of an assertion) or among the list of attributes sent within the assertion attribute statement.
Both your Salesforce.com and NAM IDP settings must be harmonized so that NAM assertions can be successfully matched to Salesforce.com shadow accounts. In my first article, I used defaults whenever I could which meant that Salesforce.com users used their email address as their username and NAM was configured to send the user's email address as the value for the assertion's NameIdentifier attribute. Below is a screenshot of a typical user account in Salesforce.com, the default SSO settings and their relationship:
The "Username" field is mandatory for all Salesforce.com user accounts. The username field is automatically filled with the user's email address by the admin UI unless the admin purposefully changes it while creating an account. The "Federation ID" field is optional (more on this later). Salesforce.com requires and enforces that both the "Username" and the "Federation ID" fields be globally unique to ensure that only one SAML user can be matched to these fields.
The radio button selections depicted above are the defaults and require that your NAM IDP send the user's Salesforce.com username as the NameId value in the Subject portion of the assertion and ignore the Federation ID. You must configure NAM to do this for you.
First you must define an attribute mapping in your Attribute Set so it is available for configuration in the second step. In my example the Salesforce.com username value is set to the user's corporate email address. You can use any values you like within Salesforce.com. You do not have to use user email addresses for Salesforce.com usernames, but it must be globally unique within Salesforce.com so email addresses are often used. Below is an example using email address:
Identity Servers | TAB: Shared Settings | Attribute Sets | <your_AttrSet_name> Salesforce
Make sure to enable your Attribute Set with your Salesforce.com SP definition. That will make the user's email attribute selectable for the next step.
Now that the attribute is available, next configure NAM so the appropriate Salesforce.com username value is sent as the NameIdentifier value in your assertions. This is done on your SP definition for Salesforce.com as shown in the example below:
Identity Server Cluster | Edit | TAB: SAML 2.0 | Service Providers | <your_SP_definition_name>Salesforce
The above configuration maps the authenticated user's mail attribute value from your LDAP user store defined in NAM into your SAML assertion sent to Salesforce.com as the value for the "NameIdentifier element of the subject statement" in an E-mail format to match your Salesforce.com SSO configuration. This will satisfy the Salesforce.com SSO user matching settings.
Below is another view of both Salesforce.com and NAM configurations and their relationships that will allow the JBloggs-TST user to successfully access Salesforce.com via NAM. Starting with the Salesforce.com "SAML Identity Type" setting:
To find a matching Salesforce.com shadow account the assertion must contain a valid username ("SAML Identity Type" setting). The NAM "Attribute Set" configuration above determines which attributes are available and included in an assertion. The "mail" attribute above is being "sent with authentication" but it need only be listed as "Available" to succeed for this example.
To find a matching Salesforce.com shadow account the assertion must have a valid username as the NameIdentifier element of the Subject statement ("SAML Identity Location" setting). The NAM "Authentication Response" above sends the authenticating user's local LDAP "mail" attribute value as the NameIdentifier (a.k.a. NameID) value within assertions. Note that this is also where you set the format of the NameIdentifier that is defined in the assertion. Salesforce.com does not require this to be set to "E-mail" as in the example, it could also be "Unspecified". I have found both acceptable to Salesforce.com but other SP's may be more particular.
My second example matches the user without using the user's email address nor Salesforce.com username and instead uses the Salesforce.com "Federation ID". Just-in-Time provisioning requires that the "User Identity Type" use the "Federation ID" but has other advantages as well. Since user email addresses can often change and be reused, you may not want to use it for matching. Instead you could use the Salesforce.com "Federation ID" field and match its value to a more consistent unique identifier within your local LDAP user store. A common example of this would be the user's employee ID number. This value is often populated as the workforceID attribute in eDirectory LDAP user stores so I use it in this example but any sufficiently managed attribute can be used.
The following example uses the same JBloggs-TST shadow account above that has both his Salesforce.com Federation ID and LDAP user store workforceID attribute set to the same unique value. Important: The federation ID is case sensitive. I use "pfm-tst0001" in this example. First you must tell Salesforce.com to match users based on their "Federation ID" value instead of their username by changing the "SAML Identity Type" setting:
Next, modify your NAM configuration so that the workforceID attribute is present in assertions by adding a mapping to your Salesforce.com Attribute Set. Note: Like any new attribute, you may first have to add the workforceID to your NAM Identity Server Cluster's Shared Settings Attribute list. In my mapping, I used a "remote attribute" name of "federationId" but you can choose another or not provide a remote attribute name at all. The remote attribute name is unimportant for this example. It becomes important for my third example that follows.
The result will look like this:
Optionally, you may also remove the mail attribute mapping as it is no longer needed for user matching in this example.
Simply adding this attribute to the NAM Attribute Set will make it "Available". It need not be "sent with authentication", it simply must be available:
This Salesforce.com configuration expects the federation ID / workforceID value to be sent in the assertion as the value of the NameIdentifier element of the Subject statement. NAM must be configured to do this by selecting "workforceID" as shown below:
While my third example is rather interesting, I am not sure why one would care to use it. It is a variation of the previous example that also uses federation ID / workforceID data but differs where and how data is organized in the assertion. This time the workforceID MUST be in the "Send with authentication" column in the list of attributes to work:
In my previous example the "Remote Attribute" name in my Attribute Set mapping did not matter, but for this configuration it does. The "Remote Attribute" name can be any name you choose, but must match the Attribute Name defined in Salesforce.com configuration setting. I use "federationId":
This Salesforce.com configuration ignores the Name Identifier in your assertion so any NAM configuration of the Name Identifier should work.
As you can see from the three examples I provided, changing the Salesforce.com radio buttons that control the "SAML Identity Type" and "SAML Identity Location" settings have a significant impact on how you must also configure NAM. By changing the radio buttons you can experiment with additional combinations of settings. To fully understand the ramifications of each combination you can refer to the Salesforce.com documentation but I have found using log files and browser header traces more illuminating. Unfortunately Salesforce.com error messages are often misleading so you should not assume that they mean what they say as you are troubleshooting and instead rely on log files and traces.