Server Access OAuth 2.0 Flows

The flows in this section are those usually used to allow a server application to acquire an OAuth access token without a user needing to authenticate or authorise in real time.

As user authorisation is not a part of these flows, this needs to have been provided in another way for the authorisation server to allow access. When Salesforce acts as the authorisation and resource servers, users could either be pre-authorised in connected app configuration, or could provide prior authorisation through a browser-based flow.

Flows covered are summarised below:

JWT Bearer Flow

JWT Bearer Flow Diagram
  • JSON Web Token (JWT) is created and signed with private key of an X509 certificate by client app
  • Authorisation server checks signature against public key of certificate to verify authenticity of request
  • Allowed scopes are based on approval previously provided by the user through another OAuth flow
  • Additional claims can be included in the JWT to communicate extra user or context info to the auth. server
  • For Salesforce to act as the authorisation & resource server, a connected app is needed. This flow is used in Salesforce DX CLI authorisation
  • Salesforce can also act as the client, and an option is offered in Named Credentials to make callouts from Salesforce to an external server application using this flow

SAML Bearer Flow

SAML Bearer Flow Diagram
  • SAML assertion is created and signed with private key of an X509 certificate by client app
  • Authorisation server checks signature against public key of certificate to verify authenticity of request
  • Allowed scopes are based on approval previously provided by the user through another OAuth flow
  • Additional claims can be included in the assertion to communicate extra user or context info to the auth. server
  • For Salesforce to act as the authorisation & resource server, a connected app is needed

Client Credentials Grant Flow

Client Credentials Grant Flow Diagram
  • The client credentials grant flow is used for server-to-server interaction, and allows clients to obtain an access token outside of the context of a user
  • Since client authentication is used as the authorisation grant, no additional authorisation request is needed
  • As with other server-server flows, a refresh token will not be supplied
  • Salesforce can act as the client, and as of Winter '23, Salesforce also supports this flow while acting as the server. When Salesforce participates as the server, an execution user must be selected in the connected app which determines the running user and permissions for any integration activity

Refresh Token Flow

Refresh Token Flow Diagram
  • Used to exchange a refresh token for an access token when required
  • An app will need to invoke this flow each time an access token expires. Access token expiry can be identified by a status code 401 ("Unauthorized") or sometimes 403 ("Forbidden") error response from a resource server endpoint. If Salesforce is the resource server, this response will be 401 with error code "INVALID_SESSION_ID"

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.

Username-Password Flow

Username-Password Flow Diagram
  • Current recommendation from IETF is not to use this flow. A more secure alternative should be used in almost all scenarios (e.g. web server for user authentication or JWT bearer for server authentication)
  • The only circumstances this should be considered is where there is complete trust between all systems and networks. An example use case would be a user entering a password in real time on an internally managed client application which doesn't support a browser-based identity flow

SAML Assertion Flow

SAML Assertion Flow Diagram
  • This flow makes use of a Single Sign On (SSO) configuration in Salesforce for authentication rather than a connected app, which isn't required.
  • In general, as part of an SSO configuration Salesforce will accept SAML assertions which:
    • Are signed by the Identity Provider (IDP)
    • Have the Recipient attribute in the SubjectConfirmationData element set to an org-specific Login URL or OAuth 2.0 Token Endpoint indicated on the SSO settings page
    • Have an AudienceRestriction element with an Audience element indicating the correct Salesforce Entity ID
  • The restrictions above make this flow impractical for most circumstances, and either a JWT or SAML bearer flow would almost always be preferable for server-server integrations.
  • Historically, the SAML Assertion flow has been used in the context that a client app authenticated by an IDP needs to then authenticate as the logged in user to Salesforce. In some circumstances the SAML assertion could be reused by the client app to directly authenticate to the Salesforce org in this way. For this to be possible, the assertion can be created by the IDP with multiple AudienceRestriction elements, however Salesforce appears to only support the presence of a single SubjectConfirmationData element, which must have a Salesforce login URL as Recipient, so suitability would depend on the implementation of SAML in the client application.