Introduction

Using Novell Access Manager (NAM) with salesforce.com allows your users to use their existing LDAP credentials for single sign-on access to salesforce.com as well as any web applications protected by NAM.

This cool solution will show you how to add salesforce.com to your NAM implementation using a federated authentication via SAML 2.0. By using SAML 2.0, your users authenticate to NAM as they typically do using their existing LDAP credentials provided by your corporate directory. salesforce.com then authenticates users via SAML without the need to synchronize passwords with salesforce.com. Once configured, your users will have SSO access to all your web resources protected by NAM through either the Access Gateway or using federation protocols. Unfortunately, salesforce.com does not support federated provisioning, so you will still need create users in salesforce.com. If you would like to automatically provision, deprovision, and manage the salesforce.com identities, you can use Novell Identity Manager, but that is out of scope for this article.

Unfortunately not all federated applications are configured the same. Configuration of NAM varies little, but there is little commonality among federated applications. Some other Cool Solution articles include:

• • Integrating Google Apps and Novell Access Manager using SAML2 by Neil Cashell

• • SAML NAM Concur Integration by Neil Cashell

• • Configuring and Troubleshooting SAML 1.1 with Novell Access Manager by Bart Andries

• • Configuring Access Manager for UserApp and SAML by CoolGuys

• • Integrating Novell's Access Manager with Shibboleth's IDP Server by Neil Cashell

• • Microsoft and Novell Interoperability (NAM and Microsoft SharePoint integration via WS-Federation & Active Directory Federation Services white paper)

Regardless of the configuration differences, federation terminology and concepts are the same. So if this is your first time using SAML, this article should make it easier for your next application! At first glance this article may appear to be a bit long, but it really isn't. It is long because because I include a lot of screen shots to make the configuration process easy. You will be pleasantly surprised how easy it is.

Overview

The NAM Access Gateway (AG) is used to protect web resources that are not federation aware in conjunction with the NAM Identity Server which provides authentication services. Federation requires only the NAM Identity Server. This works by establishing a trust between your Identity Provider (IdP) and your Service Provider (SP). In our case The IdP is your NAM Identity Server and your SP is salesforce.com; making up the two sides of the federation trust. To establish the trust, configuration will be required on both your NAM Identity Server and salesforce.com. NOTE: The NAM "Identity Server" is acting as your federation "IdP" so these terms are can be used interchangeably.

When using SAML there are two ways for users to login: Service Provider (SP) initiated and Identity Provider (IdP) initiated login. If you are familiar with NAM, you are familiar with SP initiated login; users enter a URL that represents the service on an AG and are redirected to the IdP for login and then sent back to the originally requested URL upon successful login. In an IdP initiated login, the user enters a URL that takes them to the IdP first and then upon successful authentication are redirected by the IdP to the service desired. This article will use an IdP initiated login for salesforce.com.

Network Considerations

When using federation it is very common that direct communication between your SP and IdP is required. Since salesforce.com is an cloud based offering, you can't download and install into your internal network lab, so you will need to create a "sandbox" instance of salesforce.com for testing. This will require proper communication between your users and salesforce.com through the internet.

In many federation trusts, direct communication between your SP and IdP is required. Usually this means that your NAM IdP is placed in your DMZ with appropriate firewall rules in place that allows communication between the SP (salesforce.com) and IdP (NAM Identity Server) as well as between users and your IdP. Because salesforce.com uses the browser post profile and does not exchange metadata directly with your IdP, direct communication between your salesforce.com (SP) and your NAM IdP is not required. Instead assertions are sent to salesforce.com by the user's browser. So as long as your users have access to your NAM IdP and salesforce.com, federated SSO will work. Still I do not recommend that you rely solely on this type of network configuration. I suspect that if your organization is looking to the cloud for salesforce.com, other cloud based services are likely to follow and they may require direct communication between your SP and IdP. Networking considerations for federation can be complex, and will not be covered in any further depth in this article. I recommend that you consult an experienced Novell partner for assistance.

Salesforce.com Configuration

Salesforce.com supports two single sign-on mechanisms: "Delegated authentication" and "Federated single sign-on using SAML". Federated SSO is what we will be using. Salesforce.com can use either SAML 1.1 or 2.0. NAM supports both; we will be using SAML 2.0 in this article.

Pfmxxx: Before you can configure SSO for salesforce.com, it must be enabled. Contact salesforce.com to do this. Enabling SSO will not actually "turn on" SSO. Instead it will expose the SSO feature in the salesforce.com administration tool where you can configure and enable SSO.

Salesforce.com CFG: Federated Single Sign-On

Enable federated single sign-on on your salesforce.com instance using the following instructions and example screen shots:

Login as an administrator and click Setup near the top of the page

In the left pane navigate to Administration Setup | Security Controls | Single Sign-On Settings

If you do not find "Single Sign-On Settings" listed, contact salesforce.com to enable this capability.

Configure the Single Sign-On Settings as follows according to this table and the following screen shot:

Click to view.

After hitting the "Save" button you should see something similar to the following screen shot. Take note of the "Salesforce.com Login URL" value displayed in your configuration (highlighted by the red box below). This value can vary and you will need this later during the NAM configuration to customize the sample metadata provided in this article before you import it into NAM. If you do not use the correct "Salesforce.com Login URL" in your metadata, users will not be able to perform a federated login. This specific scenario is described in detail later in the troubleshooting section of this article.

Click to view.

SFDC Test User:

We will need a salesforce.com test user so while in the salesforce.com admin console it is a good idea to create one now. Although you will set a password for your test user, it will not be used for authentication and can be ignored since salesforce.com will trust the SAML assertion sent by NAM once the test user has successfully authenticated to NAM.

Sample Test User (e.g. tuser@mycorp.com) Screen Shot:

Click to view.

NAM Configuration

NAM CFG: Basic Identity Server & SAML 2.0 Activation

Basic installation of NAM is not covered in this article. Please refer to your NAM documentation for installation instructions. A typical NAM installation will include an Administration Console, Identity Server, Access Gateway, and SSL VPN Server. For salesforce.com SSO purposes, only the Administration Console and Identity Server are involved. Below is a screen shot of a healthy Identity Server shown in the NAM Administration Console that is used as our example throughout this article and this is where we will start our NAM configuration:

Click to view.

Be sure that the SAML 2.0 protocol has been enabled on your Identity Server. To verify this or enable SAML 2.0, click the "Edit" link on your Identity Server as shown above. After clicking you should be at a screen similar to the following:

Click to view.

Scroll down to the "Enabled Protocols" section at the bottom of the page and select "SAML 2.0" (highlighted by a red box in the screen shot below) and click the "OK" button to save.

Click to view.

To affect your changes, you will need to "Update" your Identity Server so that the change is published to your Identity Server. Before you do that, you may want to configure your logging so you can troubleshoot if things do not work the first time. Later in this document is a troubleshooting section where you will need debug level logging enabled. To enable this: Click "Logging" on the blue bar in the previous screen shot.

Click to view.

Highlighted In the above screen shot:

Enable "File Logging"

Enable "Echo To Console"

Set the SAML2 Component File Logger level to "debug"

To affect your changes, you will need to "Update" your Identity Server so that the change is published to your Identity Server.

NAM CFG: Attribute Set

We will need to create an NAM Attribute Set (or use and existing one) so that we can send additional identity attributes to salesforce.com as part of the Attribute Statement portion of the SAML assertion. To create a new attribute set:

Navigate to your Identity Server | select the "Shared Settings" tab. You should see any previously created attribute sets. Below is a screen shot showing my attribute set called "salesforce.com" already created and associated (Trusted Providers = 1) with my NAM Identity Server / Provider configuration:

Click to view.

To create the "salesforce" attribute set like the one above, perform the following steps:

Select New

Provide a name (e.g. salesforce)

Click the "Next" button

These steps are exemplified by the following screen shot:

Click to view.

Next you will create your attribute mappings.

Do so by clicking New and entering your information.

In this example I am creating the mappings listed in the following table and screen shots:

Consult with salesforce.com regarding other attributes that may be valuable in your environment when sent in the attribute statement of your assertion.

The following screen shot depicts the configuration for adding the logouturl attribute mapping listed in the table above:

Click to view.

Click OK to complete the mapping.
Click New to create the next attribute mapping:

The following screen shot depicts the configuration for adding the mail attribute mapping listed in the table above:

Click to view.

You may add additional attribute mappings using the same processes above but the two above are sufficient to get NAM working with salesforce.com.

Click the "Finish" button.

The following screen shot shows the two mappings we just created:

Click to view.

Click Close and be sure to "Update" your Identity Server.

Your attribute set is not yet associated to your salesforce.com SP configuration in NAM. We will do that later after configuring the NAM side of the trust with salesforce.com which we will do next.

NAM CFG: Define the Salesforce.com SP Configuration (trust)

As mentioned previously, we need to establish a trust between the salesforce.com SP and the NAM IdP. We already configured salesforce.com so that it is aware of our IdP (except perhaps your signing certificate). Now we need to configure NAM IdP to be aware of the salesforce.com SP to complete the trust. NAM supports and requires the use of standard SAML metadata to establish this trust. Unfortunately salesforce.com does not provide a metadata URL or XML so we must create our own. Use the sample metadata below for this purpose:

NAM Sample SP Metadata:

<EntityDescriptor entityID="https://saml.salesforce.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" >
<SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" >
     <NameIDFormat > urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress</NameIDFormat >
<AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.salesforce.com" />
</SPSSODescriptor >
</EntityDescriptor >

You may need to change the above metadata example for your salesforce.com environment. Specifically you will need to change the "Location" value to reflect your salesforce.com login URL. This URL was shown and noted previously during the salesforce.com configuration. In this example the value used is "https://login.salesforce.com". Your value may be different (this URL is not easy to predict). Later in the troubleshooting section of this article, I detail a case where this value is wrong. NOTE: If you make any changes to the salesforce.com "Single Sign-On Settings" your Salesforce.com Login URL value may change. So be sure to watch for any changes to this URL if you make any changes to your salesforce.com SSO settings.

With your customized metadata in hand, you are now ready to complete your SAML 2.0 trust between salesforce.com and NAM using the following instructions and screen shots as a guide:

In the NAM Administration Console:

On your Identity Server click the "Edit" link (highlighted by the red box in the screen shot below):

Click to view.

You will be taken to the "General" tab. Click the "SAML 2.0" tab. You will see the following:

Click to view.

Here is where we will define the salesforce.com SP as a trusted provider using the following instructions:

Click New | Service Provider, as highlighted below:

Click to view.

The SP setup wizard will start with step 1 of 2. The following screen will appear prompting you for your SP information:

Click to view.

As you can see above, the default is to import your SP metadata directly from a URL published by your SP. Earlier in this doc I mentioned that salesforce.com does not provide any metadata via neither a URL nor Text/XML file. Here is where you will need the your customized metadata based on the sample provided at the beginning of this section. To use your metadata:

Change the "Source:" from "Metadata URL" to "Metadata Text" using the drop-down menu.

Your screen will change so that you can paste your metadata into the "Text:" window as shown below:

Click to view.

Now you are ready to specify your name and metadata (Step 1 of 2):

Enter a name into the "" field. This is an arbitrary value that you can set (e.g.).

Copy and paste your metadata into the "Text:" field as exemplified by the following screen shot:

Click to view.

Click Next to continue to Step 2 of 2:

Click to view.

Since the metadata did not contain a signing certificate (nor is one required) the above screen has no values. To complete the configuration:

Click the "Finish" button. You should be returned to the "SAML 2.0" tab in the "Trusted Providers" sub-section as exemplified by the following screen shot:

Click to view.

NAM CFG: Salesforce.com SP Federation Trust Configuration

Now that we have defined our salesforce.com SP for NAM, we need to make some other configuration changes.

Click on your Service Provider link (e.g. Salesforce.com in the screen shot above). You should be taken to the "Configuration" Tab in the "Trust" sub-section as exemplified by the following screen shot:

Click to view.

You do not need to make any changes to the "Trust" configuration elements but other changes are needed. Before we make these changes it is a good idea to confirm your metadata. To do that you can click on the "Metadata" tab in the screen shown above. The result will be a different view of your metadata import as exemplified by the following screen shot:

Click to view.

If you notice any problems with your metadata you can simply re-import it without losing any other SP configuration information.

To complete your SP configuration changes start by modifying the "Attributes" sub-section as follows:

Click the "Configuration" tab.

Click "Attributes" sub-section on the blue menu bar under the "Configuration" tab. You should see the following:

Click to view.

In one of the early NAM configuration steps in this article we created an "Attribute Set" for salesforce.com. Now we will associate that attribute set with our salesforce.com SP definition in NAM and configure it so that the attributes are available and sent to salesforce.com via our SAML assertions. To do this:

Click the "Attribute set" drop down menu and select your attribute set defined earlier (e.g. Salesforce)" from the list as exemplified by the following screen shot:

Click to view.

After selecting your Attribute Set, the attributes previously defined in the set will be listed in the "Available" field.

Select both attributes and use the left-hand blue arrow to move them to the "Send with authentication" field as highlighted in by the red boxes exemplified by the following screen shot:

Click to view.

After moving the attributes to the "Send with authentication" column:

Click the "Apply" button:

Click to view.

Next we need to make changes to the "Authentication Response" configuration:

Click "Authentication Response" sub-section on the blue menu bar under the "Configuration" tab. You should see something like the following screen shot:

Click to view.

We need to make changes to the above configuration:

Make sure the "Binding" is set to "Post" by selecting "Post" instead of "Artifact" from the drop-down menu.

Click the radio button that controls the "Default" name identifier so that the E-mail is selected.

Click the drop down menu to the right of the "E-mail" line and select "Ldap Attribute:mail [LDAP Attribute Profile]".

After these changes are made your configuration should look like the following screen shot:

Click to view.

After making the above changes to the "Authentication Response" settings:

Click the Apply button.

Next we need to make changes to the "Intersite Transfer Service" configuration:

NAM CFG: Intersite Transfer Service

As noted in the overview of this article, we will be using an IdP Initiated login. The "Intersite Transfer Service" configuration will determine the URL (based on the "ID" defined here) used by users to log into salesforce.com and also configures where the user's browser will be redirected ("Target") after successful login to salesforce.com.

Normally, the final URL that your users will use includes elements defining your IDP and SP target URL. But this makes for a lengthy and ugly URL. NAM offers a nice feature for you to simplify and centrally control the SP "target" element of the final user URL. This way if the target URL ever needs to change you can simply change your NAM IDP configuration instead of finding and fixing a bunch of links and bookmarks. In our case, the "TARGET=https://na7.salesforce.com/home/home.jsp" portion of the URL will be reduced down to "id=SalesForce". The "id" value is arbitrary, so you can choose a friendly name like I did, or if you like choose one that is more cryptic. We do this by defining the "Intersite Transfer Service" in NAM with an ID and target value. So lets do that.

Click the "Intersite Transfer Service" sub-section on the blue menu bar under the "Configuration" tab. You should see an empty configuration as exemplified by the following screen shot:

Click to view.

Configure the "Intersite Transfer Service" as follows:

Enter an "ID" value. The "ID" value you use here is arbitrary (e.g. SalesForce).

Enter the "Target" value. This must be a legitimate salesforce.com URL (e.g. https://na7.salesforce.com/home/home.jsp ).

To determine your specific URL, use your salesforce.com test user to login directly to salesforce.com via your browser using the salesforce.com ID and Password (federation is not complete yet). Once successfully authenticated, note the resulting salesforce.com URL in your browser. This is the URL you will use for your "Target" value. It should be something similar to the example used in the following screen shot (e.g. https://na7.salesforce.com/home/home.jsp ).

The sample configuration above is exemplified by the following screen shot:

Click to view.

Click the "Apply" button to save your salesforce.com SP configuration "Intersite Transfer Service" changes. To publish all of your SP configuration changes you made, you will need to:

Click the "OK" button and "Update" your Identity Server.

Your users will be able to perform an IdP Initiated login to salesforce.com using a specific URL that is based on your specific NAM configuration. This URL will take the form:

https://<your_NAM_IdP>:<your_port>/nidp/saml2/idpsend?id=<your_Intersite_Transfer_Service_ID>

Using the example configuration in this article our URL is:

https://dvlnam01.mycorp.com:8443/nidp/saml2/idpsend?id=SalesForce

Take note of your URL for later use. Your users will use this URL to login and access salesforce.com.

NAM CFG: Signing Certificate Configuration

Novell Access Manager includes its own PKI Certificate Authority(CA) for minting certificates to secure communication between NAM components, client browsers (https), and 3rd parties. When integrating with third parties using federation trusts, certificates are used to secure their communication to establish a secure trust. When integrating with salesforce.com, the secure trust is established when NAM signs assertions using a certificate.

The certificate used for signing must be trusted by salesforce.com. The PKI CA included with NAM is a "private" CA. Salesforce.com does not allow you to import your private CA trusted root so you can't use a cert signed by your NAM CA for assertion signing. The only certificates that salesforce.com will trust are those minted by a "public" CA for which they already have the certificate's trusted root in their certificate keystore. Salesforce.com does not support all public CA's. Before purchasing a certificate from a public CA vendor, I recommend that you confirm that salesforce.com includes the trusted root of the public certificate vendor you plan to use.

The following instructions show you how to create, import, and use a public CA certificate in NAM used for assertion signing to secure your trust with salesforce.com. You may need/want to use public certificates for other purposes. A common use is to secure browser to NAM traffic (HTTPS) communication to avoid the burdensome and user confusing untrusted certificate messages from their browser. Using public CA certificates for this purpose is similar to the instructions provided for assertion signing but are not explicitly covered in this article.

Before you can get a certificate from a public certificate authority you need to generate a Certificate Signing Request (CSR). The CSR and other certificate management tasks are performed from within the the NAM Administration Console. To do this we start in the main window of the NAM Administration Console:

Mouse-over the "Security" tab from the main and navigate down to the "Certificates" sub-selection and click it as highlighted by the red box in the screen shot below:

Click to view.

You will be taken to the main certificate management screen similar to the following screen shot:

Click to view.

In the screen shot above, the "test-signing" certificate is being used to sign SAML assertions. The "test-signing" certificate is the default certificate used for signing by NAM which was automatically created during your initial installation of NAM. This is the certificate that we need to replace with a public CA signed certificate. As mentioned, in order to purchase the new certificate we need to generate a CSR as follows:

Click "New..." from within the "Certificates" tab.

The following screen will appear prompting you through the remainder of the process:

Click to view.

Many of the details required for you to build a proper CSR request are dependent on your environment. Some elements of the example used here will vary significantly from your particular implementation. In the above screen shot:

Click the radio button to "Use external certificate authority".

Enter a "Certificate Name" (e.g. public_signing). This is an arbitrary name (FYI: it is also used as the alias name in certificate keystore(s)).

Click the pencil icon to the right of the "Subject" field. This will open a new window for you to build the "Subject" name of your certificate. The "Subject" must be correct to work properly and is based on your publicly resolvable DNS host name of your Identity Server. Your certificate provider will also require other organizational information. Be sure to enter values for at least the "Commonly used attributes" as exemplified in the following screen shot:

Click to view.

Click the "OK" button to return to the main certificate creation window.

You should see something similar to the following screen shot:

Click to view.

Before continuing you can make additional changes to your CSR but using the defaults are typically acceptable. Possible changes include:

Valid from: Default is the current date/time but can be back or future dated

Months valid: Default is 24 or 2 years but can be longer

Key Size: Default is 1024 but can be higher

Advanced options: A plethora of other options

When you are done with your changes, click the "OK" button to create the CSR. You will be returned to the list of "Certificates" including your CSR:

Click to view.

Now that your CSR has been created, you need to send it to your public certificate vendor. You can export your CSR data to a file for this purpose:

Click on the CSR that you just created ("public_signing") in the screen shot above.

You will see something similar to the following screen shot:

Click to view.

From the above screen you can export your CSR to a file by clicking "Export CSR" or you can highlight the CSR data and copy it to your clipboard. You will then submit this data to your certificate vendor. Your certificate vendor will then provide you with your signed certificate.

Your signed certificate with be provided as a file or as text. You will also need the trusted root certificate and any intermediaries from your vendor. With these available you are ready to import your certificate. In this example we will use simple text data for the certificate import.

Navigate back to the CSR you created as you did in the above screen shots.

In the last screen shot above, click "Import Signed Certificate...". This will open the following screen:

Click to view.

To import your certificate as text:

Copy your certificate data from your vendor into your clipboard. Be sure to include "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" lines along with the data in between.

Click the "Certificate data text (PEM/Base64)" radio button.

Paste your certificate data:

Click to view.

Click "Add trusted root" to provide your trusted root certificate in file or text form. Repeat this process for any intermediate certificates:

Click to view.

Click OK.

You will return to the following screen:

Click to view.

Now that your new certificate has been imported, we need to configure NAM so it will use it to sign your assertions by adding your new "public-signing" certificate to the keystore used for signing:

Starting from the above screen shot, click "Add Certificate to Keystores". The following will appear:

Click to view.

Click the pencil icon to select your keystore(s) and select the keystore you would like to which you are adding. For our purposes you need to use this certificate to sign assertions which is a function of the NAM Identity Server. To do this, you need to add the certificate to the keystore used by your NAM IdP for signing. In this article and screen shot below, the keystore name is "NIDP-signing", but your keystore name may be different:

Click to view.

Click OK.

Recall that the NAM default install creates a default signing certificate called "test-signing". It also adds it to the NIDP-signing keystore with the alias name of "signing". If you simply hit Ok when prompted below, the test-signing certificate will be replaced in the NIDP-signing keystore, but it will not be deleted from your NAM certificate server.

Click to view.

Click OK

Your certificate will now be added to your NIDP-signing keystore as highlighted below:

Click to view.

Great! We are almost done. Your NAM configuration is complete but you still need to export the signing certificate to a file so you can import it into your salesforce.com SP configuration. To export your certificate:

Click "Export Public Certificate" from the screen above.

Select your file format from the list above.

Click to view.

Save your file.

Next return to the salesforce.com administration console as instructed at the start of this article and import your certificate in the "Single Sign-On Settings" section.

LDAP User Store Test User:

You will of course, need to have a test user created in your LDAP user store that matches a user in salesforce.com. During our salesforce.com configuration early in this article I created a test account in salesforce.com called "tuser@mycorp.com". You will need to also create a test user in our LDAP user store called to match (e.g. tuser).

Ready to test...

Recall that users will perform an IdP Initiated login using a specific URL based on your specific NAM configuration. For example: https://dvlnam01.mycorp.com:8443/nidp/saml2/idpsend?id=SalesForce
From your browser use this URL to test your configuration.



NOTE: You can use HTTP or HTTPS for the IdP initiated login URL, but you must choose carefully. Typically your NAM IdP and default authentication contract will be configured to use HTTPS so you should also use HTTPS for the IdP initiated URL for salesforce.com. This way if your users access other web resources protected by the NAM AG before accessing Salesforce.com, they will not be prompted to login a second time. This assumes that this is your desired result and that your NAM AG protected resource is using the same "secure" authentication contract as your IdP's default contract or your configure your contracts to allow them to be "Satisfiable by a contract of equal or higher value".

Troubleshooting

Below are a few tips for troubleshooting authentication issues. If you have trouble with your first login, be aware that the error messages from salesforce.com presented to the user are often mis-leading. One such example is provided later in this section.

Login History

If you run into troubles, a good place to start is with the user login history in salesforce.com. Login history is available in the salesforce.com administration console:

Administration Setup | Security Controls | Single Sign-On Settings

You can access the login history for all users or filtered for your specific test user as highlighted in the screen shot below:

Click to view.

Choosing the "Login History" link in the left had pane will show you all users. You can only see the last few entries, so to filter the list by User:

Click Users | Select your User

Near the top of the page you will see another Login History link (see above screen shot). Clicking this link for our test user will display the last few logins:

Click to view.

When the user successfully authenticates using SAML you will see entries with a Login Type of "SAML Idp Initiated SSO" and a status of "Success". Additional login history can be downloaded into a CSV file by clicking the link at the bottom of the screen shot above. Below are a examples:

DATE,IP ADDRESS,LOGIN TYPE,STATUS,BROWSER,OS
"2/2/2010 10:36 AM",x.x.x.x,SAML Idp Initiated SSO,Success,IE 6,WinXP,,
"2/2/2010 10:31 AM",x.x.x.x,SAML Idp Initiated SSO,Failed: Signature Invalid/Configured Certificate Mismatch,IE 6,WinXP,,

Note that the second entry above shows a failed "SAML IdP Initated SSO" login due to a certificate problem.

SAML Assertion Validator

A more valuable and important troubleshooting tool, is the "SAML Assertion Validator" tool from salesforce.com. It allows you to run a series of tests using your specific SAML assertion as an input. Below are instructions on how to use this tool and also some examples with configuration errors.

First you will need to get your assertion from NAM so you can paste it into the validator tool. You can get an assertion from the NAM IdP catalina.out log file. If you did not enable logging during your initial NAM configuration refer to that section earlier in this article. To retrieve your log file:

Click "General Logging" from the NAM Administration Console:

Click to view.

By clicking "General Logging" above you will be taken to the following screen where you can download your catalina.out log file from your Identity Server:

Click to view.

With your log file in hand, locate your SAML assertion. Your assertion will be the XML data between the following:

************************* SAML2 POST message ********************************

Type: sent 
Sent to: https://login.salesforce.com RelayState: https://na7.salesforce.com/home/home.jsp
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Destination=
...
</samlp:Response > 
************************* End SAML2 message ****************************

You do not want all the data between the lines above, just the assertion XML data:

Start your selection at: <samlp:Response

End by including: </samlp:Response >

Copy your assertion to your clipboard so you can paste it into the validator.

To access the validator tool, log into as a salesforce.com administrator and navigate to the "Single Sign-On Settings" section:

Setup | Administration Setup | Security Controls | Single Sign-On Settings

The tool is available from the "Single Sign-On Settings" section as highlighted below by the red boxes:

Click to view.

Paste your assertion into the validator as exemplified by the following screen shot:

Click to view.

In the above screen shot click the "Validate" button. The validator will perform several tests on the assertion and display the results. The screen shots below provide an example where there is a problem. In this case the certificate used to sign the assertions has expired:

Click to view.

Click to view.

Here is another example of a configuration problem. When our test user tried to authenticate they were given the following message in their browser:

Click to view.

This is an example where the error message can lead you down the wrong troubleshooting path; there is nothing wrong with the certificate as the user error message suggests. This time the problem is a simple configuration error in the salesforce.com SAML 2 metadata that was imported into NAM. When the assertion is run through the validator you will get much more valuable information:

Click to view.

In the above validator results, notice that tests "11. Checking the Recipient" and "12. Validating the Signature" failed. The test 12 signature validation failure is what caused the user error message indicated a certificate problem. However the signature validation failed because the recipient in the assertion was wrong, not because of a certificate problem. To fix this problem refer back to the metadata configuration section of this article. Here the administrator failed to change the sample metadata in this article to match their environment. Specifically, the "Location" value was not changed to match their salesforce.com configuration. The Location value used was "https://login.salesforce.com" when it should have been "https://cs2.salesforce.com" for this specific salesforce.com environment. This value is determined by salesforce.com and is available as the "Salesforce.com Login URL" found in the salesforce.com administration console under the "Single Sign-On Settings" section described early in this article.

Summary

Using federated login with salesforce.com gives your users the convenience of SSO without the security risk of synchronizing your internal LDAP/network passwords with salesforce.com or any other cloud service provider that supports federated SSO. If that vendor also supports federated provisioning you have a complete identity and access management solution. If your cloud vendor does not support federated provisioning, Novell Identity Manager completes your solution in a secure and convenient manner that reflects your business processes and security policies while establishing a platform to meet your compliance needs.

Special thanks to contributors to this Cool Solution including a financial institution in the midwest United States, and Jim Wilbur of Concensus Consulting who provided several screen shots that contributed to the troubleshooting section of this article.