Salesforce Single Sign On Flows

Single Sign On (SSO) flows enable users to authenticate using their identity from an external system. There are three mechanisms which can be used to achieve this in Salesforce:

  • SAML, where signed structured messages known as SAML requests and assertions are passed between the identity provider and service provider via the browser.
  • OpenID Connect, which leverages OAuth web server or user agent flows to establish trust.
  • Delegated Authentication, a mechanism based on capturing and submitting credentials for authentication via a SOAP message. Can be useful for authenticating to systems which don't offer other protocols.

This section outlines the sequence of messages in SSO mechanisms supported by Salesforce for the flows below:

Service Provider (SP) Initiated SSO

SP Initiated SSO Diagram

If Salesforce acts as the Service Provider:

  • Salesforce "Single-Sign On Settings" should be configured with values from the IDP
  • Certificate from the IDP should be uploaded as the identity provider certificate in Salesforce. This is used for signature validation on incoming SAML responses
  • Requests will be signed by Salesforce with the selected certificate, which can be validated by the IDP if necessary
  • IDP-encrypted assertions are also supported, and decryption certificate uploaded and selected as Assertion Decryption Certificate
  • SAML request bindings can be configured to be bound to HTTP Redirect or HTTP POST (determines whether initial SAML authentication request is GET or POST)
  • Just In Time (JIT) user provisioning can be configured to enable automatic creation/update of users based on contents of incoming SAML assertions. Salesforce will attempt to match a user and will either update this record or create a new user in real time. Standard provisioning allows assertion attributes corresponding to standard field names to be used for matching and values for field contents, or custom logic can be defined in a class implementing the Auth.SamlJitHandler interface
  • The IDP will need to be set up with the Authorisation Consumer Service (ACS) URL ("Salesforce Login URL") and Entity ID
  • MyDomain required for SP-Initiated SSO, which enables deep linking (landing on requested URL) and OAuth with SAML


For Salesforce to act as the Identity Provider:

  • Salesforce identity provider setup must be enabled, and a connected app set up for each service provider specifying the Authorisation Consumer Service (ACS) URL and service provider's Entity ID, as well as general SAML configuration, which can differ by service provider
  • User profiles or permission sets must be added to connected app for accounts to be used for SSO identity
  • Optionally, SAML request signatures for a service provider can be validated by uploading the SP's signing certificate
  • SAML responses can be encrypted for additional security
  • The connected app's Start URL is used as Relay State if the app's icon is clicked in the Salesforce app launcher

OpenID Connect (OIDC)

OpenID Connect SSO Diagram
  • OpenID Connect is the accepted standard and most popular mechanism for identity verification using the OAuth 2.0 framework. Salesforce allows OpenID Connect providers to be set up as authentication providers for Social Sign On with simple configuration
  • Many identity services offer an identity verification mechanism based on OAuth 2.0 and similar to but not completely consistent with OpenID Connect. It's possible to set up custom authentication providers for services like these by extending the Auth.AuthProviderPluginClass class with custom logic to initiate authentication and retrieve user information (details in Salesforce documentation)
  • OpenID Connect is offered by services such as Google and Microsoft, and is likely used in the pre-configured authentication providers available for these services
  • Some popular OAuth-based identity services which don't comply entirely with the OpenID Connect spec are also pre-configured in Salesforce. Examples include:
  • A Salesforce org can also act as the OpenID Connect Provider for other applications. In this instance, either the web server version (as shown) or another OAuth flow could be used for the authentication/authorisation
  • In addition to Social Sign On, authentication providers in Salesforce can be used to authenticate content providers for Salesforce Files Connect (e.g. Google or Office 365)
  • Client id and secret are managed by Salesforce for standard authentication providers (Facebook, Google etc), though these can be overridden in the org if required

General details around characteristics of OpenID Connect:

  • Nonce if provided is included as an attribute in the ID token - this binds the token to a specific authorisation request and help protect against replay attacks possible through CSRF
  • The UserInfo endpoint can be used to provide ID claims not included in the scope of the ID token, for example picture, email, website, locale, phone number etc
  • The draft OpenID Connect Session Management spec recommends the RP to regularly verify the session is still active at the OP, although these checks aren't made in the current Salesforce Auth. Provider implementation
  • The OpenID Connect Core spec includes details on implementation of this flow

Legacy & Special Scenarios

The flows below are supported by Salesforce, but are not recommended for most scenarios due to suboptimal security, use of a legacy protocol or lack of support in typical integrating applications.

Identity Provider (IDP) Initiated SSO

IDP Initiated SSO Diagram
  • This flow is inherently less secure than the SP-initiated version, and is highly susceptible to Man-in-the-Middle and CSRF attacks (see links below). Careful consideration should be made before choosing to use IDP-Initiated SSO
  • When Salesforce acts as an IDP, this flow can be started by launching the "IdP-Initiated Login URL" shown in the policies for the connected app set up for the SP. To launch a specific resource, also include a RelayState parameter with the intended URL from the SP. This URL can also be used as the connected app's Start URL to start this flow when the connected app's icon is clicked from the App Launcher. If Start URL is simply set to a resource from the SP, clicking the App Launcher will redirect to this resource without initiating SSO directly
  • IDP-Initiated SSO can be used as part of canvas app authentication by selecting "Identity Provider Initiated" as the canvas app's initiation method option. Unlike the "Service Provider Initiated" option, this has the advantage that the SAML response can be passed and the user authenticated without the need for the canvas app / service provider to first serve an un-authenticated login page, which may not permit embedding in an iframe (this applies to Salesforce's own standard login page, so this consideration is relevant to Salesforce -> Salesforce canvas apps)
  • If Salesforce acts as the Service Provider, general setup considerations and capabilities described in the Service Provider Initiated SSO flow apply except the requirement for My Domain, which isn't necessary here

Delegated Authentication from Salesforce Login

Delegated Authentication
  • Provides a method of using credentials for applications which don't offer SAML to login to Salesforce
  • My domain is not required
  • Delegated authentication SOAP endpoint must comply to specific WSDL (which can be downloaded from Salesforce)
  • Password is not validated in SF and instead passed to authentication service for validation, so Salesforce password policy doesn't apply
  • This flow requires delegated authentication endpoint to support processing passwords
  • Delegated authentication can be enabled / disabled by an admin from Single Sign On Settings
  • Permission "Is Single Sign-On Enabled" controls by user whether passwords are submitted to delegated authentication service

SAML migration trick: It can be useful to block certain users from logging in with username and password. By enabling delegated authentication and using the "Is Single Sign-On Enabled" permission, these users will be prevented from using their Salesforce password to login

Delegated Authentication (HTTP)

Delegated Authentication (HTTP) SSO Flow
  • Enables authentication to Salesforce without prompting for credentials
  • Application must manage or be able to acquire the token, assertion or password
  • A token or assertion is preferable to avoid sending corporate passwords to or from Salesforce
  • If a token or assertion is used, this should be set as the password in the POST to the Salesforce login page

Apex Hours SSO Videos

Videos created for Apex Hours are linked from the article pages - click "Read More" against a section above to check whether a video is available.

Some guidelines for choosing between SSO flows are outlined in the video below, and the full set of video content around SSO is available on this page.

Terminology

SAML
  • Security Assertion Markup Language (SAML) - Provides an open standard for XML-based confirmation of identity and transfer of identity attributes between an Identity Provider and Service Provider
  • Identity Provider (IDP) - An application with the capability to authenticate a user's identity (i.e. allow the user to login), and confirm authentication and identity attributes to a Service Provider
  • Service Provider (SP) - An application which defers to an Identity Provider for authentication of a user, and allows this user access to protected resources or capabilities based on this authentication
  • SAML Request - The structured XML message sent by the Service Provider to an Identity Provider, identifying itself and requesting authentication of the user
  • SAML Response - The XML message sent by the Identity Provider to the Service Provider identifying itself as the issuer, indicating the status of the authentication attempt, and including the SAML Assertion if this can be issued (typically signed with the Identity Provider's certificate)
  • SAML Assertion - The portion of the SAML Response which confirms identity attributes of the authenticated user

OpenID Connect

Note that terms below are specific to the OpenID Connect specific aspects of the identity exchange. For details on other elements of OAuth 2.0 relevant to OIDC, check the OAuth 2.0 terminology page.

  • OpenID Connect (OIDC) - An identity extension to the OAuth 2.0 framework which specifies a JSON Web Token structure for confirmation of identity and communication of identity attributes
  • OpenID Connect Provider (OP) - The application with the ability to authenticate a user and confirm identity attributes and authentication event information to a Relying Party. This application is playing the role of Authorisation Server in the terminology of OAuth 2.0
  • Relying Party (RP) - The application deferring to the OpenID Connect Provider for an end user's authentication and authorisation, and providing an authenticated service to the user once identity and authorisation is confirmed. This application is playing the role of Client in the terminology of OAuth 2.0
  • ID Token - The JSON Web Token (JWT) structure used to communicate identity attributes from the OpenID Connect Provider to the Relying Party
  • UserInfo Endpoint - Protected resource at the OpenID Connect Provider which will validate an access token and return authorised information about the user this token relates to