Salesforce Single Sign On
Salesforce Single Sign On
Table of Contents
About Single Sign-On..........................................................................................................................................................................2
Enabling Delegated Authentication Single Sign-On............................................................................................................................4
Configuring SAML Settings for Single Sign-On.................................................................................................................................7
Viewing Single Sign-on Settings........................................................................................................................................................13
Validating SAML Settings for Single Sign-On..................................................................................................................................14
Best Practices for Implementing Single Sign-On...............................................................................................................................16
Sample Delegated Authentication Implementations...........................................................................................................................18
Frequently Asked Questions...............................................................................................................................................................19
i
About Single Sign-On
Single sign-on is a process that allows network users to access all authorized network resources without having to log in
separately to each resource. Single sign-on allows you to validate usernames and passwords against your corporate user database
or other client application rather than having separate user passwords managed by Salesforce.
Salesforce offers the following ways to use single sign-on:
• Federated authentication using Security Assertion Markup Language (SAML): When federated authentication is
enabled, salesforce.com does not validate a user's password. Instead, salesforce.com verifies an assertion in the HTTP
POST request, and allows single sign-on if the assertion is true. This is the default form of single sign-on. Federated
authentication is available in all Editions.
• Delegated authentication: When delegated authentication is enabled, salesforce.com does not validate a user's password.
Instead, salesforce.com makes a Web services call to your organization to establish authentication credentials for the user.
You must request that this feature be enabled by salesforce.com. Contact salesforce.com to enable delegated authentication
single sign-on for your organization..
The Single Sign-On Settings page displays which version of single sign-on is available for your organization. To learn more
about the single sign-on settings, see Configuring SAML Settings for Single Sign-On on page 7. For more information
about SAML and Salesforce security, see the Security Implementation Guide.
2
About Single Sign-On
• Increased User Adoption: Due to the convenience of not having to log in, users are more likely to use Salesforce on a
regular basis. For example, users can send email messages that contain links to information in Salesforce such as records
and reports. When the recipients of the email message click the links, the corresponding Salesforce page opens automatically.
• Increased Security: Any password policies that you have established for your corporate network will also be in effect for
Salesforce. In addition, sending an authentication credential that is only valid for a single use can increase security for users
who have access to sensitive data.
3
Enabling Delegated Authentication Single Sign-On
3. The Web services call passes the username, password, and sourceIp to your Web service. (sourceIp is the IP address
that originated the login request. You must create and deploy an implementation of the Web service that can be accessed
by salesforce.com servers.)
4. Your implementation of the Web service validates the passed information and returns either true or false.
5. If the response is true, then the login process continues, a new session is generated, and the user proceeds to the application.
If false is returned, then the user is informed that his or her username and password combination is invalid.
4
Enabling Delegated Authentication Single Sign-On
b. Add a link to your corporate intranet or other internally-accessible site that takes the authenticated user’s credentials
and passes them through an HTTP POST to the Salesforce login page.
Because Salesforce does not use the password field other than to pass it back to you, you do not need to send a
password in this field. Instead, you could pass another authentication token, such as a Kerberos Ticket so that your
actual corporate passwords are not passed to or from Salesforce.
You can configure the Salesforce delegated authentication authority to allow only tokens or to accept either tokens or
passwords. If the authority only accepts tokens, a Salesforce user cannot log in to Salesforce directly, because they cannot
create a valid token. However, many companies choose to allow both tokens and passwords. In this environment, a
user could still log in to Salesforce through the login page.
When the salesforce.com server passes these credentials back to you in the Authenticate message, verify them, and
the user will gain access to the application.
3. In Salesforce, specify your organization’s single sign-on gateway URL by clicking Setup ➤ Security Controls ➤ Single
Sign-On Settings ➤ Edit. Enter the URL in the Delegated Gateway URL text box.
For security reasons, Salesforce restricts the outbound ports you may specify to one of the following:
• 80: This port only accepts HTTP connections.
• 443: This port only accepts HTTPS connections.
• 7000-10000 (inclusive): These ports accept HTTP or HTTPS connections.
4. Modify your user profiles to enable the Is Single Sign-On Enabled user permission. In Salesforce, click Setup ➤
Manage Users ➤ Profiles to add or edit profiles.
Important: If single sign-on is enabled for your organization, API and desktop client users cannot log in to Salesforce
unless their IP address is included on your organization's list of trusted IP addresses or on their profile, if their profile
has IP address restrictions set. Futhermore, the single sign-on authority usually handles login lockout policies for
users with the "Is Single Sign-On Enabled " permission. However, if the security token is enabled for your organization,
then your organization's login lockout settings determine the number of times a user can attempt to log in with an
invalid security token before being locked out of Salesforce. For more information, see "Setting Login Restrictions"
in the Salesforce online help. For information on how to view login errors, see "Viewing Single Sign-On Login
Errors" in the Salesforce online help.
5
Enabling Delegated Authentication Single Sign-On
6
Configuring SAML Settings for Single Sign-On
Your organization must have SAML enabled in order to view the SAML Settings on the Single Sign-On settings page.
7
Configuring SAML Settings for Single Sign-On
• ssoStartPage is the page to which the user should be redirected when trying to log in with SAML. The user is directed
to this page when requesting a protected resource in Salesforce, without an active session. The ssoStartPage should be
the SAML identity provider's login page.
• startURL is the URL where you want the user to be directed when sign-on completes successfully. This URL can be
absolute, such as https://na1.salesforce.com/001/o or it can be relative, such as /001/o. This parameter is only
used in SAML 1.1. In SAML 2.0, the start URL is the page the user attempted to access before they were authenticated.
• logoutURL is the URL where you want the user to be directed when they click the Logout link in Salesforce. The default
is http://www.salesforce.com.
The following sample TARGET field is for SAML 1.1, and includes properly-encoded parameters. It passes a customized start
page, as well as start and logout URLs embedded as parameter values in the query string.
https://saml.salesforce.com/?ssoStartPage=https%3A%2F
%2Fwww.customer.org%2Flogin%2F&startURL=%2F001%2Fo&logoutURL=https%3A%2F%2F1.800.gay%3A443%2Fhttp%2Fwww.salesforce.com
The following is an example of an <AttributeStatement> for SAML 2.0 that contains both ssoStartPage and
logoutURL:
<saml:AttributeStatement>
<saml:Attribute Name="ssoStartPage"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">
http://www.customer.org
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="logoutURL"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
https://www.salesforce.com
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
Field Description
SAML Enabled Select this checkbox to enable SAML for your organization. Deselect it to disable SAML.
SAML Version Specify the version of SAML your identity provider uses. Salesforce currently supports
version 1.1 and 2.0. The SAML specifications for the various versions are linked below:
• SAML 1.1
8
Configuring SAML Settings for Single Sign-On
Field Description
• SAML 2.0
Issuer A URL that uniquely identifies your SAML identity provider. This value is usually the
URL of the identity provider service, or the entity ID of the identity provider. SAML
assertions sent to Salesforce must match this value exactly in the Issuer attribute of SAML
assertions.
Identity Provider Use the Browse button to locate and upload a new identity provider certificate issued by
Certificate your identity provider.
SAML User ID Type Specify which element in a SAML assertion contains the string that identifies a Salesforce
user:
Assertion contains User's Salesforce username
Select this option if the assertion identifies a Salesforce user with his or her Salesforce
username. Use this option if your identity provider passes the Salesforce username in
SAML assertions.
Assertion contains the Federation ID from the User object
Select this option if the assertion identifies a Salesforce user with an external user
identifier stored in the FederationIdentifier field on his or her User record.
Use this option if your identity provider passes an external user identifier, for example
an employee ID, in the SAML assertion to identify the user.
SAML User ID Location Specify where in the assertion a user should be identified:
User ID is in the NameIdentifier element of the Subject
statement
The Salesforce Username or FederationIdentifier is located in the <Subject>
statement of the assertion.
User ID is in an Attribute element
The Salesforce Username or FederationIdentifier is specified in an
<AttributeValue>, located in the <Attribute> of the assertion.
Attribute Name If "User ID is in an Attribute element" is selected, enter the value of the
AttributeName that is specified in <Attribute> that contains the User ID.
Attribute URI If SAML 1.0 is the specified SAML version and "User ID is in an Attribute
element" is selected, enter the value of the AttributeNamespace that is specified in
<Attribute>.
Name ID Format If SAML 2.0 is the specified SAML version and "User ID is in an Attribute
element" is selected, specify the value for the nameid-format. Possible values include
unspecified, emailAddress or persistent. All legal values can be found in the
"Name Identifier Format Identifiers" section of the Assertions and Protocols SAML 2.0
specification.
4. Click Save.
5. To request single sign-on, your identity provider directs the user's browser to POST a form containing SAML assertions
to the Salesforce login page. Each assertion is verified, and if successful, single sign-on is allowed.
9
Configuring SAML Settings for Single Sign-On
6. If you are having difficulty signing on using single sign-on after you have configured and saved your SAML settings, click
SAML Assertion Validator.
Login History
When a user logs in to Salesforce from another application using single sign-on, SAML assertions are sent to the Salesforce
login page. The assertions are checked against assertions in the identity provider certificate specified in Setup ➤ Security
Controls ➤ Single Sign-On Settings. If a user fails to log in, a message is written to the login history log that indicates why
the login failed:
Issuer Mismatched
The issuer specified in an assertion does not match the issuer specified in your Salesforce configuration.
Recipient Mismatched
The recipient specified in an assertion does not match the recipient specified in your Salesforce configuration.
Signature Invalid
The signature in an assertion cannot be validated by the certificate in your Salesforce configuration.
Assertion Expired
An assertion's timestamp is more than five minutes old.
Note: Salesforce does make an allowance of three minutes for clock skew. This means, in practice, that an
assertion can be as much as eight minutes passed its validity period or three minutes before it.
Assertion Invalid
An assertion is not valid. For example, the <Subject> element of an assertion might be missing.
Replay Detected
The same assertion ID was used more than once. Assertion IDs must be unique within an organization.
Audience Invalid
The value specified in <Audience> must be https://saml.salesforce.com
Sample Assertions
Sample assertions are included below for SAML 1.1 and SAML 2.0.
SAML User ID type is the Salesforce username, and SAML User ID location is the <NameIdentifier> element
in the <Subject> element
SAML 1.1:
<Subject>
<NameIdentifier>[email protected]</NameIdentifier>
</Subject>
10
Configuring SAML Settings for Single Sign-On
SAML 2.0:
<saml:Subject>
<saml:NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">[email protected]</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2008-06-26T02:44:24.173Z"
Recipient="http://localhost:9000"/>
</saml:SubjectConfirmation>
</saml:Subject>
SAML User ID type isSalesforce username, and SAML User ID location is the <Attribute> element
SAML 1.1:
<AttributeStatement>
<Subject>
<NameIdentifier>this value doesn't matter</NameIdentifier>
<SubjectConfirmation>
<ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</ConfirmationMethod>
</SubjectConfirmation>
</Subject>
<Attribute AttributeName="MySfdcName" AttributeNamespace="MySfdcURI">
<AttributeValue>[email protected]</AttributeValue>
</Attribute>
</AttributeStatement>
SAML 2.0:
<saml:AttributeStatement>
<saml:Attribute FriendlyName="fooAttrib" Name="SFDC_USERNAME"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
[email protected]
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
SAML User ID type is the Salesforce User object's FederationIdentifier field, and SAML User ID location is
the <NameIdentifier> element in the <Subject> element
SAML 1.1:
<AttributeStatement>
<saml:Subject>
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.0:assertion"
NameQualifier="www.saml_assertions.com">
MyName
</saml:NameIdentifier>
11
Configuring SAML Settings for Single Sign-On
</saml:Subject>
</AttributeStatement>
SAML 2.0:
<saml:Subject>
<saml:NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">MyName</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2008-06-26T02:48:25.730Z"
Recipient="http://localhost:9000/"/>
</saml:SubjectConfirmation>
</saml:Subject>
Note: The name identifier can be any arbitrary string, including email addresses or numeric ID strings.
SAML User ID type is theSalesforce User object's FederationIdentifier field, and SAML User ID location is
the <Attribute> element
SAML 1.1:
<AttributeStatement>
<Subject>
<NameIdentifier>who cares</NameIdentifier>
<SubjectConfirmation>
<ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</ConfirmationMethod>
</SubjectConfirmation>
</Subject>
<Attribute AttributeName="MyName" AttributeNamespace="MyURI">
<AttributeValue>user101</AttributeValue>
</Attribute>
</AttributeStatement>
SAML 2.0:
<saml:AttributeStatement>
<saml:Attribute FriendlyName="fooAttrib" Name="SFDC_ATTR"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
user101
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
12
Viewing Single Sign-on Settings
After you have configured your Salesforce organization to use SAML, you can view the single sign-on settings. Click Setup
➤ Security Controls ➤ Single Sign-on Settings.
This page lists the details of your SAML configuration. Most of these fields are the same as the fields on the page where you
configured SAML. The following fields contain information automatically generated by completing the configuration. The
available fields depend on your configuration.
Field Description
Identity Provider For SAML 2.0 only: specifies the URL to which you post assertions.
Login URL
Identity Provider For SAML 2.0 only. specifies the URL that the user is directed to after he or she logs off.
Logout URL
Salesforce Login URL If you select "Assertion contains User's Salesforce username" for SAML User ID Type and
"User ID is in the NameIdentifier element of the Subject statement" for SAML User ID
Location, this URL is of the form https://login.salesforce.com or for sandbox,
https://test.salesforce.com. For all other selections, a similar URL is displayed; it
is appended with additional encrypted material.
Salesforce Logout URL Displays the Salesforce logout URL that the user is directed to after he or she logs off. This
URL is only used if no value is specified for Identity Provider Logout URL.
13
Validating SAML Settings for Single Sign-On
After you have configured the SAML settings for single-sign on, you can validate the settings as follows:
1. Click Setup ➤ Security Controls ➤ Single Sign-On Settings, configure Salesforce for SAML, then click SAML
Assertion Validator.
2. Enter your SAML response into the text box, and click Validate. You can use either a text or a base64 encoded response.
Conditions Statement
If the assertion contains a <Conditions> statement, it must contain a valid timestamp.
Timestamps
The validity period specified in an assertion is honored. In addition, an assertion's timestamp must be less than five
minutes old, plus or minus three minutes, regardless of the assertion's validity period setting. This allows for differences
between machines. The NotBefore and NotOnOrAfter constraints must also be defined and valid.
Attribute
If your configuration is set to User ID is in an Attribute element, your assertion must contain an
<AttributeStatement>.
If you are using SAML 1.1, both <AttributeName> and <AttributeNamespace> are required as part of the
<AttributeStatement>.
Format
The Format attribute of an <Issuer> statement must be set to
"urn:oasis:names:tc:SAML:2.0:nameid-format:entity" or not set at all.
14
Validating SAML Settings for Single Sign-On
For example:
<saml:Issuer
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://www.salesforce.com
<saml:Issuer >https://www.salesforce.com
Issuer
The issuer specified in an assertion must match the issuer specified in Salesforce.
Subject
The subject of the assertion must be resolved to be either the Salesforce username or the Federation ID of the user.
Audience
The <Audience> value must be https://saml.salesforce.com.
Recipient
The recipient specified in an assertion must match the recipient specified in the Salesforce configuration.
Signature
A valid signature must be included in the assertion.
15
Best Practices for Implementing Single Sign-On
• Federated authentication using Security Assertion Markup Language (SAML): When federated authentication is
enabled, salesforce.com does not validate a user's password. Instead, salesforce.com verifies an assertion in the HTTP
POST request, and allows single sign-on if the assertion is true. This is the default form of single sign-on. Federated
authentication is available in all Editions.
• Delegated authentication: When delegated authentication is enabled, salesforce.com does not validate a user's password.
Instead, salesforce.com makes a Web services call to your organization to establish authentication credentials for the user.
You must request that this feature be enabled by salesforce.com. Contact salesforce.com to enable delegated authentication
single sign-on for your organization..
16
Best Practices for Implementing Single Sign-On
• We recommend that you do not enable single sign-on for the system administrator’s profile. If your system administrators
are single sign-on users and your single sign-on server has an outage, they have no way to log in to Salesforce. System
administrators should always be able to log in to Salesforce so they can disable single sign-on in the event of a problem.
• We recommend that you use a Developer Edition account or a sandbox when developing a single sign-on solution before
implementing it in your organization. To sign up for a free Developer Edition account, go to developer.force.com.
• Make sure to test your implementation with Salesforce clients such as Connect for Outlook, Connect for Office, and
Connect Offline. For more information, see the Single Sign-On for Salesforce clients.
17
Sample Delegated Authentication Implementations
Sample 1
This is implemented in simple.asmx.cs. This file declares a new class, SimpleAdAuth, that is a Web service with one
method: Authenticate. There are a number of attributes declared on the method. These control the formatting of the
expected request and the generated response, and set up the service to match the message definition in the WSDL. The
implementation uses the passed credentials to try to connect to Active Directory via the LDAP provider. If it connects
successfully, the credentials are good; otherwise the credentials are not valid.
Sample 2
This is a more complex example that generates and verifies an authentication token rather than a password. The bulk of the
implementation is in the sso.asmx.cs file, which defines a class SingleSignOn that can generate an authentication token
and implements the authentication service to later verify that token. The generated token consists of a token number, expiry
timestamp, and username. All the data is then encrypted and signed.
The verification process verifies the signature, decrypts the token, checks that it has not expired, and checks that the token
number has not been previously used. (The token number and expiration timestamp are used to prevent replay attacks.) The
file gotosfdc.aspx is an ASPX page designed to be deployed and/or linked to from an intranet site. This forces the user’s
authentication, generates a new authentication token for the user, and finally POSTs that token to the Salesforce login page
along with a username that is mapped from the local NT username. The Salesforce login process sends the authentication
token back to the service, which verifies the token and lets the user into Salesforce. intranet.aspx is a simple page that
links to gotosfdc.aspx so you can see this in action.
18
Frequently Asked Questions
• Federated authentication using Security Assertion Markup Language (SAML): When federated authentication
is enabled, salesforce.com does not validate a user's password. Instead, salesforce.com verifies an assertion in the
HTTP POST request, and allows single sign-on if the assertion is true. This is the default form of single sign-on.
Federated authentication is available in all Editions.
• Delegated authentication: When delegated authentication is enabled, salesforce.com does not validate a user's
password. Instead, salesforce.com makes a Web services call to your organization to establish authentication credentials
for the user. You must request that this feature be enabled by salesforce.com. Contact salesforce.com to enable
delegated authentication single sign-on for your organization..
• The WSDL is available by clicking Setup ➤ Develop ➤ API ➤ Download Delegated Authentication WSDL.
• You can specify your organization’s single sign-on gateway URL by clicking Setup ➤ Security Controls ➤ Single
Sign-On Settings ➤ Edit.
• Click Setup ➤ Manage Users ➤ Profiles to enable the Is Single Sign-On Enabled user permission for the
profiles of your single sign-on users.
How are passwords reset when single sign-on has been implemented?
Password reset is disabled for single sign-on users because Salesforce no longer manages their passwords. Users who try
to reset their passwords in Salesforce will be directed to their Salesforce administrator.
Why can I not find any entries in the login history for a failed SAML login attempt?
When Salesforce cannot find the user in your assertion or cannot associate the provided user ID with a user in Salesforce,
there is no entry inserted in the login history at Setup ➤ Manage Users ➤ Login History.
19
Frequently Asked Questions
Can I configure a start page and logout page that are specific to my company?
Yes. For delegated authentication, the ssoStartPage and logoutURL fields can be submitted in a GET or POST
request. The configuration is different for federated authentication (SAML) where you add a TARGET field in the HTTP
POST request that sends a SAML assertion. The value of the TARGET field has a URL format described below:
https://saml.salesforce.com/?ssoStartPage=/001/o&logoutURL=http://www.salesforcecustomer.com
The portion of the URL before the query string (question mark) must be set to https://saml.salesforce.com/,
and the customized start and logout pages are embedded as parameter values in the query string.
The parameters are explained below:
• ssoStartPage is the URL where you want the user to be directed when sign-on completes successfully. This URL
can be absolute, such as https://na1.salesforce.com/001/o or it can be relative, such as /001/o.
• logoutURL is the URL where you want the user to be directed when they click the Logout link in Salesforce. The
default is http://www.salesforce.com.
20