General OAuth 2.0 Flows

Salesforce can participate in a number of standard OAuth 2.0 flows acting as either the client, or as the authorisation and resource server. The flows in this section are the common general flows which are used for either user or server authorisation and authentication - flows to be applied in specific circumstances can be found in the "Specialised OAuth 2.0 Flows" section.

The diagrams are shown in general terms as Salesforce can play the role of client or server. Considerations specific to Salesforce are mentioned in the notes.

Authorisation Code with Secret (Web Server)

Web Server Flow Diagram
  • This flow provides the highest level of security possible through standard OAuth flows, but is suitable only if the client secret can be protected by the client application - generally this is the case when the application has a back end server component which is operating in a trusted environment (e.g. an internal enterprise server application)
  • The current IETF OAuth working group recommendation is for public and confidential clients participating in any auth. code flow to implement PKCE using code_challenge and code_verifier  (more info on how these are used in the Authorisation Code with PKCE flow below)
  • As an alternative to client secret, a JWT with issuer & subject = client_id signed with the client app's key can be provided in the access token request. For this variation, client_assertion and client_assertion_type should be set instead of client_secret
  • The Salesforce "Web Server" flow is an implementation of this flow where Salesforce is acting as the authorisation and resource server
  • Salesforce can also participate as the client in this flow

Implicit Grant (User-Agent)

User Agent Flow Diagram
  • The flow can be used in circumstances where a client secret can't be protected, for example in a mobile or desktop application, or client app running in a browser, such as a SPA
  • Identity is based on the same-origin policy (redirect_uri must match one of the Callback URL values in connected app)
  • The flow is sub-optimal from a security perspective in many scenarios, as tokens are transmitted in URL. This means they are accessible to the browser and stored in browser history, which is frequently synced across devices and susceptible to attack. It's advisable to ensure that access token validity is short and refresh tokens aren't used to reduce the risk of such attacks
  • Prior to 2017, this flow was recommended as best practice for mobile and native applications, however the current recommendation is to implement the more secure Authorisation Code with PKCE flow described below in contexts where an out of band POST can be made
  • The Salesforce "User-Agent" flow is an adaptation of the OAuth 2.0 Implicit Grant flow where Salesforce acts as the authorisation and resource servers. Some security counter-measures (e.g. tokens and sessions being returned in URL hash fragments rather than query string parameters) have been implemented to improve security. A connected app is needed to support this configuration
  • Salesforce Mobile SDK implements the User-Agent flow, so apps developed through this framework (including Mobile Publisher apps) will authenticate in this way

Authorisation Code with PKCE

Authorisation Code with PKCE diagram
  • Since 2017, Authorisation Code with PKCE (Proof Key for Code Exchange) has been recommended as the most secure flow for mobile and native apps by the Internet Engineering Task Force (IETF). Their white paper recommendation is linked below
  • The major advantage this has over implicit grant (User-Agent) is that although there's no need for the client to protect credentials or a secret, tokens are returned through a secure channel (an out of band HTTPS call) rather than via the browser URL, which carries risk of a token being leaked through browser history or URL referrals
  • PKCE refers to the use of "code verifier" and "code challenge", which provide an additional layer of security. Code verifier is a 128 byte base64url encoded random string generated by the app, and code challenge is the base64url encoded SHA256 hash of this string
  • Native apps may make use of a custom URL scheme (e.g. MyApp://) or localhost (e.g. http://localhost/) to capture redirects - exposing authorisation codes issued for this flow carries low risk
  • The authorisation server checks the application is making an authorised token request by comparing code challenge to the hash of code verifier. When these match, the authorisation server can be confident the entity making the token request is the same one which requested the authorisation code - the one-way nature of the hash function makes it difficult for an attacker to find a matching code verifier and so impersonate the authorised client even if code challenge and auth code are intercepted
  • To configure Salesforce as an authorisation server allowing this flow, a connected app is needed with the option "Require Secret for Web Server Flow" disabled

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

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

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"