Configure SAML for Salesforce Community SSO

Last Updated -

Prerequisites

  • License required: Customer Community, Customer Community Plus, or Partner Community for external users. Employee Apps Starter and Employee Apps Plus for Employee Communities.
  • Federated Authentication is available in: All Editions
  • Delegated Authentication is available in: Professional, Enterprise, Performance, Unlimited, Developer, and Database.com editions
  • Authentication Providers are available in: Professional, Enterprise, Performance, Unlimited, and Developer editions
  • Permissions: View Setup and Configuration, Customize Application AND Modify All Data

Guide

  1. Gather information from your identity provider.
  2. Provide information to your identity provider.
  3. Set up Single Sign-On.
  4. Set up an identity provider to encrypt SAML assertions. (optional)
  5. Enable Just-in-Time user provisioning. (optional)
  6. Edit the SAML JIT handler if you selected Custom SAML JIT with Apex Handler for Just-in-Time provisioning.
  7. Test the Single Sign-On connection.
Gather information from your identity provider
  1. Gather the following information from your identity provider before configuring Salesforce for SAML.
    • The version of SAML the identity provider uses (1.1 or 2.0)
    • The entity ID of the identity provider
    • An authentication certificate.
    • The following SAML assertion parameters
      • The SAML user ID type
      • The SAML user ID location
      • Attribute Name
      • Attribute URI
      • Name ID format
  2. Work with your identity provider to setup the start, login, and logout pages.
  3. Share the example SAML assertions with your identity provider so they can determine the format Salesforce requires for successful single sign-on.
Provide information to your identity provider
Gather your needed identity provider values and input them on the Single Sign-On page. The following fields might be useful for your identity provider.
 

Field

Description

 

SAML Version

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:

 

 

Issuer

The Entity ID — a URL that uniquely identifies your SAML identity provider. SAML assertions sent to Salesforce must match this value exactly in the attribute of SAML assertions.

Entity ID

The issuer in SAML requests generated by Salesforce, and is also the expected audience of any inbound SAML Responses. If you don’t have domains deployed, this value is always https://saml.salesforce.com. If you have domains deployed, Salesforce recommends that you use your custom domain name. You can find the value on the Single Sign-On Settings page. From Setup, enter Single Sign-On Settings in the Quick Find box, then select Single Sign-On Settings.

Identity Provider Certificate

The authentication certificate issued by your identity provider.

Request Signing Certificate

The certificate (saved in the Certificate and Key Management page in Setup) used to generate the signature on a SAML request to the identity provider when Salesforce is the service provider for a service provider-initiated SAML login. If a certificate has not been saved in the Certificate and Key Management page in Setup, Salesforce uses the global proxy certificate by default. Using a saved signing certificate provides more control over events, such as certificate expiration, than using the global proxy certificate.

Request Signature Method

The hashing algorithm for encrypted requests, either RSA-SHA1 or RSA-SHA256.

SAML Identity Type

The element in a SAML assertion that contains the string that identifies a Salesforce user. Values are: Assertion contains User’s 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 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. Assertion contains the User ID from the User object Use this option if your identity provider passes an internal user identifier, for example a user ID from your Salesforce organization, in the SAML assertion to identify the user.

SAML Identity Location

The location in the assertion where a user should be identified. Values are: Identity is in the Name Identifier element of the Subject statement The Salesforce Username or FederationIdentifier is located in the <Subject> statement of the assertion. Identity 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 Identity is in an Attribute element is selected, this contains the value of the AttributeName that is specified in <Attribute> that contains the User ID.

Attribute URI

If SAML 1.1 is the specified SAML version and Identity is in an Attribute element is selected, this contains the value of the AttributeNamespace that is specified in Attribute.

Name ID Format

If SAML 2.0 is the specified SAML version and Identity is in an Attribute element is selected, this contains 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.

Service Provider Initiated Request Binding

If you’re using My Domain, chose the binding mechanism your identity provider requests for your SAML messages. Values are: HTTP POST HTTP POST binding sends SAML messages using base64-encoded HTML forms. HTTP Redirect HTTP Redirect binding sends base64-encoded and URL-encoded SAML messages within URL parameters. No matter what request binding is selected, the SAML Response will always use HTTP POST binding.

Identity Provider Login URL

For SAML 2.0 only: The URL where Salesforce sends a SAML request to start the login sequence. If you have domains deployed and a value specified for this field, login requests are usually sent to the address specified by this field. However, if you need to bypass this value (for example, your identity provider is down) add the login parameter to the query string for the login page. For example: http://mydomain.my.salesforce.com?login.

Identity Provider Logout URL

For SAML 2.0 only: The URL to direct the user to when they click the Logout link in Salesforce. The default is http://www.salesforce.com.

Salesforce Login URL

The URL associated with logging in for the Web browser single sign-on flow.

OAuth 2.0 Token Endpoint

For SAML 2.0 only: The ACS URL used with the API when enabling Salesforce as an identity provider in the Web single sign-on OAuth assertion flow.

Custom Error URL

The URL of the page users should be directed to if there’s an error during SAML login. It must be a publicly accessible page, such as a public site Visualforce page. The URL can be absolute or relative. The following information might be useful to your identity provider if they are setting these pages.


Start, Login, and Logout URL Values
 

Your identity provider can also set the start, login, and logout pages or you can specify these pages yourself when configuring the SSO.

The following information might be useful to your identity provider when configuring these pages:

  • The SAML specification supports an HTML form that is used to pass the SAML assertion via HTTPS POST.
  • For SAML 1.1, the SAML identity provider can embed name-value pairs in the TARGET field to pass this additional information to Salesforce prepended with a specially formatted URL that contains URL-encoded parameters.
  • The URL for SAML 1.1 to include in the TARGET field is as follows: https://saml.salesforce.com/?
  • For SAML 2.0, instead of using the TARGET field, the identity providers uses the <AttributeStatement> in the SAML assertion to specify the additional information.
  • Salesforce supports the following parameters:
    • 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://yourInstance.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.
    • For SAML 1.1 these parameters must be URL-encoded. This allows the URLs, passed as values that include their own parameters, to be handled correctly. For SAML 2.0, these parameters are part of the <AttributeStatement>.

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=http%3A%2F%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>

 

Set up Single Sign-On
  1. In Salesforce, from Setup, enter Single Sign-On Settings in the Quick Find box, then select Single Sign-On Settings, and click Edit.
  2. Select SAML Enabled
  3. Specify the SAML version used by your identity provider.
  4. Click Save.
  5. In SAML Single Sign-On Settings, click the appropriate button to create a configuration:
    • New - Specify all settings manually.
    • New from Metadata File - Import SAML 2.0 settings from an XML file from your identity provider. This option reads the XML file and uses it to complete as many of the settings as possible.
      • If your XML file contains information for more than one configuration, the first configuration that occurs in the XML file is used.
    • New from Metadata URL - Import SAML 2.0 settings from a public URL. This option reads the XML file at a public URL and uses it to complete as many of the settings as possible. The URL must be added to Remote Site Settings to access it from your Salesforce org.
  6. Give this setting a Name for reference within your org. Salesforce inserts the corresponding API Name value, which you can customize if necessary.
  7. Enter the Issuer. Often referred to as the entity ID for the identity provider.
  8. If your Salesforce org has domains deployed, specify whether you want to use the base domain (https://saml.salesforce.com) or the custom domain for the Entity ID. You must share this information with your identity provider.
    • Generally, use the custom domain as the entity ID. If you already have single sign-on configured before deploying a domain, the base domain is the entity ID. If you are providing Salesforce to Salesforce services, you must specify the custom domain.
  9. For the Identity Provider Certificate, use the Browse button to locate and upload the authentication certificate issued by your identity provider. The certificate size can’t exceed 4 KB. If it does, try using a DER encoded file to reduce the size.
  10. For the Request Signing Certificate, select the certificate you want from the ones saved in your Certificate and Key Management settings.
  11. For the Request Signature Method, select the hashing algorithm for encrypted requests, either RSA-SHA1 or RSA-SHA256.
  12. Optionally, if the identity provider encrypts SAML assertions, select the Assertion Decryption Certificate they’re using from the ones saved in your Certificate and Key Management settings. This field is available only if your org supports multiple single sign-on configurations. For more information, see Set up an identity provider to encrypt SAML assertions.
  13. For the SAML Identity Type, SAML Identity Location, and other fields described in Identity Provider Values, specify the values provided by your identity provider as appropriate.
  14. For the Service Provider Initiated Request Binding, select the appropriate value based on the information provided by your identity provider.
  15. For SAML 2.0, if your identity provider has specific login or logout pages, specify them in Identity Provider Login URL and Identity Provider Logout URL, respectively.
    • These fields appear in Developer Edition and sandbox organizations by default and in production organizations only if My Domain is enabled. The fields do not appear in trial organizations or sandboxes linked to trial organizations.
  16. For the Custom Error URL, specify the URL of the page that the users are directed to if there's an error during SAML login. It must be a publicly accessible page, such as a public site Visualforce page. The URL can be absolute or relative.
  17. Optionally, set up Just-in-Time user provisioning. For more information, see Enable Just-in-Time user provisioning and About Just-in-Time Provisioning for SAML.
  18. Click Save.
  19. Click Download Metadata to download an XML file of your SAML configuration settings to send to your identity provider. The identity provider can then upload these configuration settings to connect to your Salesforce orgcommunity.

Set up an identity provider to encrypt SAML assertions (optional)
When Salesforce is the service provider for inbound SAML assertions, you can pick a saved certificate to decrypt inbound assertions from third party identity providers. You need to provide a copy of this certificate to the identity provider.
  1. In the Single Sign-On Settings page in Setup, add a new SAML configuration.
  2. In the Assertion Decryption Certificate field, specify the certificate for encryption from the ones saved in your Certificate and Key Management settings.
    • If you don’t see the Assertion Decryption Certificate field you need to enable multiple single sign-on for your organization.(Applies to orgs created before the Summer ’13 release that aren’t using SAML 1.1).To enable multiple single sign-on configurations, select Enable Multiple Configs on the Single Sign-On Settings page. If this setting has already been enabled, the field appears, and you won’t see the Enable Multiple Configs button.
  3. Set the SAML Identity Location to the element where your identifier is located.
  4. When you save the new SAML configuration, your org’s SAML settings value for the Salesforce Login URL (also known as the “Salesforce ACS URL”) changes. Get the new value (from the Single Sign-On Settings page in Setup), and click the name of the new SAML configuration. The value is in the Salesforce Login URL field.
  5. The identity provider must use the Salesforce Login URL value.
  6. You also need to provide the identity provider with a copy of the certificate selected in the Assertion Decryption Certificate field to use for encrypting assertions.
Enable Just-in-Time user provisioning (optional)
  1. In SAML Single Sign-On Settings, select User Provisioning Enabled.
    • Standard - This option allows you to provision users automatically using attributes in the assertion.
    • Custom SAML JIT with Apex handler - This option provisions users based on logic in an Apex class.
  2. If you selected Standard, click Save and test the single sign-on connection. If you selected Custom SAML JIT with Apex handler, proceed to the next step.
  3. In the SAML JIT Handler field, select an existing Apex class as the SAML JIT handler class. This class must implement the SamlJitHandler interface. If you do not have an Apex class, you can generate one by clicking Automatically create a SAML JIT handler template. You must edit this class and modify the default content before using it. For more information, see Edit the SAML JIT handler.
  4. In the Execute Handler As field, select the user that runs the Apex class. The user must have Manage Users permission.
  5. Just-in-time provisioning requires a Federation ID in the user type. In SAML Identity Type, select Assertion contains the Federation ID from the User object. If your identity provider previously used the Salesforce username, communicate to them that they must use the Federation ID.
  6. Click Save.
Edit the SAML JIT handler if you selected Custom SAML JIT with Apex Handler for Just-in-Time provisioning
  1. From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
  2. Edit the generated Apex SAML JIT handler to map fields between SAML and Salesforce. In addition, you can modify the generated code to support the following:
    • Custom fields
    • Fuzzy profile matching
    • Fuzzy role matching
    • Contact lookup by email
    • Account lookup by account number
    • Standard user provisioning into a community
    • Standard user login into a community
    • Default profile ID usage for portal Just-in-Time provisioning
    • Default portal role usage for portal Just-in-Time provisioning
    • Username generation for portal Just-in-Time provisioning
  3. For example, to support custom fields in the generated handler code, find the Handle custom fields here comment in the generated code. After that code comment, insert your custom field code. For more information and examples, see the SamlJitHandler Interface documentation.
  4. If your identity provider sends JIT attributes for the Contact or Account object with the User object in the same assertion, the generated handler might not be able to make updates. For a list of User fields that cannot be updated at the same time as the Contact or Account fields, see sObjects That Cannot Be Used Together in DML Operations.
Test the Single Sign-On connection
  1. After you have configured and saved your SAML settings, test them by trying to access the identity provider's application. 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.
  2. If you have difficulty signing on using single sign-on after you have configured and saved your SAML settings, use the SAML Assertion Validator. You might have to obtain a SAML assertion from your identity provider first.
  3. If your users are having problems using SAML to log in, you can review the SAML login history to determine why they were not able to log in and share that information with your identity provider.
  4. If you are using SAML version 2.0, after you've finished configuring SAML, the OAuth 2.0 Token Endpoint field is populated. Use the token with the web single sign-on authentication flow for OAuth 2.0.

Additional Resources