Salesforce OAuth Flows Guidelines and Tips

In this post we will talk about different OAuth flows available in Salesforce and consideration while deciding which one to use. You’ve likely heard of OAuth but what exactly is it? How is it used in Salesforce and where does it fit in with other protocols like SAML? Let’s talk about what is OAuth 2.0 and Salesforce OAuth Flows Guidelines and Tips.

What is OAuth?

OAuth 2.0 is a framework that allows for secure way for systems to establish trust with one another. The end goal is to obtain an access token that can be used by to access protected resources without ever providing your username or password to the other system

Go With the Flow

Outbound:-  When you are going outbound from SFDC w/named credentials SFDC uses the Web Server Flow OOTB.

Inbound – you decide! Salesforce supports the following flows

1. Web Server Authentication
2. User-Agent
3. JWT Bearer Token
4. SAML Bearer Assertion
5. SAML Assertion
6. Username-Password
7. Device Authentication
8. Asset Token
9. Refresh Token

OAuth 2.0 for Authentication?

• OAuth 2.0 was designed for Authorization and Identity is out of its scope
• Access Token does not represent a user’s identity
• OpenId helps to implement single sign on
• OpenId Connect is OAuth Authorization + Authentication.

We’ll look at several core OAuth flows relevant to Salesforce.

User interaction	No user interaction
Authorisation Code + Secret (Web Server) Implicit Grant (User-Agent) Authorization Code + PKCE	JWT Bearer SAML Bearer Username-Password

Salesforce OAuth Flows Guidelines and Tips

Let’s look into all available Salesforce OAuth Flows with some tips and guidelines.

1. OAuth 2.0 Web Server Authentication Flow

Allows apps with a secure client server (one which can protect a secret or private key) to access protected resources. This flow is mainly used by applications hosted on web server. If external application is trusted one and hosted on secure server and can securely store client_secret, then flow can be used. This flow is used mainly to build web application

• First of all external application will request for access_token and user will be redirected to login page for authentication. After authentication, user will approve Salesforce access by external app.
• After successful approval to grant access, authentication code will be returned through callback. External app will utilize this temporary OAuth token( valid for 10 mins) and send POST request to get access_token by sending temporary OAuth code, client_id and client_secret.
• Salesforce will return access_token and refresh_token. Refresh token can be used to regenerate the access token by external app so that user is not required to authenticate every time.
• Instead of sending client credentials as parameters in the body of the access token POST, Salesforce supports the HTTP Basic authentication scheme. This scheme’s format requires the client_id and client_secret in the authentication header of the post as follows:         Authorization: Basic64Encode(client_id:secret)

Some Key Notes

• Used by web server applications which need to interact with Force.com API on behalf of a user
• there we apps run on server where the code is not available publicly
• Higher Degree of security because the client secret is protected
• use when you have a web application running on a server that can securely store the consumer secret.

This flow is not recommended for application (like ETL or middleware’s) which will access Salesforce using API’s and no UI is involved. Check this post to learn more about this flow.

2. OAuth 2.0 User Agent Flow

A simpler flow for clients which should not hold a global secret (e.g. distributed apps), but can be trusted with per-user access token. This flow is recommended when you build mobile or desktop application and your application can be distributed to anyone. So these kind of application are not considered as safe to store client secret because source code of application will be accessible to everyone and client secret can be exposed easily

• This flow is used when external system application wants to login into Salesforce using Salesforce login credentials. Once user logged in, then he/she to approve that external application can fetch Salesforce data(scope defined in connected app).
• In this flow, external application will pass only client id and user login page opens and user authenticate themselves to get access token, refresh tokens.
• External application can use use refresh token to get new access token if it get expired and can avoid logging user again in salesforce.
• With the user-agent authentication flow, the client app receives the access token as an HTTP redirection. The client app requests the authorization server to redirect the user-agent to another web server or to an accessible local resource. The server can extract the access token from the response and pass it to the client app. For security, the token response is provided as a hash (#) fragment on the URL. It prevents the token from being passed to the server or to any other servers in referral headers

Considerations for Choosing Implicit Grant Flow

• Salesforce implementation has been established for some time and avoids a custom alternative for Mobile SDK apps
• Multiple security vulnerabilities possible
• Complications for cross-domain use cases when 3rd party cookie support disabled / retired
• Current IETF recommendation is not to use this flow

some key-note

• It is used for mobile or desktop applications for example Data Loader, Salesforce 1 and Mobile SDK apps.
• Clients app that run on a device or in browser use this flow to obtain an access token.
• Token are returned to client app via a ‘hash fragment’ on a URL.

3. OAuth 2.0 JWT Bearer Token Flow

JSON Web Token (JWT) is an open standard ( RFC 7519 ) that defines a compact and self-contained way for securely transmitting information between parties as a JSON Object.

• Ideal for application which access sfdc only through API as there is no UI involved. For example ETL tools or middleware.
• A JSON Web Token (JWT) enables identity and security information to be shared across security domains. 
• JWT is basically a JSON file consisting of a header and claims object, where the header contains the signature algorithm and the claims object contains specific information such as the username and consumer key. At a high level, you will then sign the JSON object with the private key of your certificate and send the JWT to Salesforce to obtain an access token.
• When a client wants to use this flow, posts an access token request that includes a JWT to Salesforce’s OAuth token endpoint. Salesforce authenticates the authorized app through a digital signature that is applied to the JWT. 
• Digital certificates are required in this flow. Upload certificate (X509 ) to connected app which will be used to authenticate JSON web tokens.
• External application send request for access token by passing JWT token in body. SFDC server validate JWT and return access token to external app.
• No refresh token is returned in this flow. So if access token expires then send request to generate access token again.

4. OAuth 2.0 SAML Bearer Assertion Flow.

• A SAML assertion is an XML security token issued by an identity provider and consumed by a service provider.
• The external app or client isn’t required to store client_secret.
• If you use active directory or LDAP as identity provider, then you will use SAML assertion from your SSO flow to obtain an access token to Salesforce.
• This flow used SAML assertion (XML token generated by Identity provide) and applied digital signature to it using certificates.
• In connected app, you upload this certificate (X509 ) containing private key. This key should be used while signing SAML asseration(base 64 encoded).
• The SAML assertion is posted to the OAuth token endpoint, which in turn processes the assertion and issues an access_token based on prior approval of the app(users are pre- authorized in connected app). 
• This flow also return only access token not refresh token

Check this flow for more information.

5. SAML Assertion Flow

• The SAML assertion flow is an alternative for Orgs that are currently using SAML to access Salesforce and want to access the web services API the same way. 
• You can use the SAML assertion flow only inside a single org.  So it means it can be used to connect to single sfdc org
• You don’t have to create a connected app to use this assertion flow. Clients can use this assertion flow to federate with the API using a SAML assertion, the same way they federate with Salesforce for web single sign-on.
• If you have SSO configured specifically for the Salesforce org that your partner application is authenticating to, you can also use the SAML Assertion Flow. 
• Configure SAML for your org. SAML version 2.0 is required. Exchange a SAML assertion for an access token. Use a JSON parser to process the response from salesforce to extract the access_token.
• The benefit of this flow is that you can use a Base-64 encoded, then URL encoded, SAML assertion that is normally used for web single sign-on. This makes it significantly more simple from a development perspective because you don’t need to create a connected app but requires you to have SSO enabled for your Salesforce instance.
• No refresh token is issued in this flow.

6. OAuth 2.0 Username and Password Flow

• Use the username-password authentication flow to authenticate when the consumer already has the user’s credentials.
• Avoid using this flow because you have to send username and password un-encrypted to Salesforce.
• Use this flow only when there is no way to connect by using other available flows.
• Salesforce communities don’t support the OAuth 2.0 username-password authentication flow.
• In this flow, external app or client sends client_id,client_secret, username and password in POST request.
• The security token must be added to the end of the password to log in to Salesforce from an un-trusted network. Concatenate the password and token when passing the request for authentication.
• No refresh token is issued.

7. OAuth 2.0 Device Authentication Flow

• The OAuth 2.0 device authentication flow is typically used by applications on devices with limited input or display capabilities, such as TVs, appliances, or command-line applications. 
• This flow returns access_token and refresh_token.
• When device requests authorization by specifying client_id, Salesforce verifies the request and returns the following: human-readable user code, verification URL, device code, and minimum polling interval (in seconds).
• User navigate to verification URL and enters user code received.
• User prompted to login and approve access to salesforce data.
• In the meantime, the application running on the device should keep polling Salesforce (polling interval is also returned by Salesforce) and once the user has approved access, the application on the device will get an access token issued.
• After the access token is granted, the device can use it in API requests to access data on the user’s behalf. The device uses a refresh token to get a new access token if the access token becomes invalid.

Considerations for choosing authorisation code + PKCE

• Auth code request can be over relatively open channel
• Ideal for mobile, SPA, desktop apps etc where no secure client server involved
• Requires auth. server to support PKCE

Check more detail here.

8. OAuth 2.0 Asset Token Flow

• Client applications use the OAuth 2.0 asset token flow to request an asset token from Salesforce for connected devices. 
• In this flow, the device obtain an access token (in any of the above ways) and use this token alongside additional information to create an actor token. This token contains valuable information about the asset which is then send to Salesforce where it is exchanged for an asset token. Subsequent requests to protected resources at Salesforce can then be made with the asset token.
• In this flow, an OAuth access token and an actor token are exchanged for an asset token. This flow combines asset token issuance and asset registration for efficient token exchange and automatic linking of devices to Service Cloud Asset data.

9. OAuth 2.0 Refresh Token Flow

• The OAuth 2.0 refresh token flow renews tokens issued by the web server or user-agent flows

Revoking Tokens

• Revoke an OAuth token if you don’t want the client app to access Salesforce data or if you don’t trust the client app to discontinue access on its own.
• When users request their data from within an external app (the consumer’s page), they’re authenticated. You can revoke their access tokens, or the refresh token and all related access tokens, using revocation. Developers can revoke the token when configuring a log-out button in their app.
• You can use POST method to revoke token as mentioned below

Identity Flows : OAuth 2.0 Decision Guide

Please check this post to learn about when to use which flow.

Decision guide

Here are Salesforce OAuth Flows Guidelines and Tips with decision guide.

	Context	Authorisation Code + Secret (Web Server)	Implicit Grant (User-Agent)	Authorisation Code + PKCE
1	Enterprise app with secure server component authenticating to Salesforce	Good choice	Suboptimal	Suboptimal
2	Partner app with trusted server authenticating to Salesforce	Good choice	Suboptimal	Suboptimal
3	App built with Salesforce Mobile SDK	Bad choice	Good choice*	Suboptimal
4	Custom mobile app, Single Page Application (SPA) or desktop app authenticating to Salesforce (no client server)	Bad choice	Suboptimal	Good choice
5	Salesforce authenticating to an auth server	Good choice	Suboptimal	Suboptimal

*Assuming default Mobile SDK methods used

	Context	JWT Bearer	SAML Bearer	Username-Password
1	Salesforce -> Auth. Server integration	Good choice	Suboptimal	Suboptimal
2	Client Server -> Salesforce integration where client can easily construct a JSON web token	Good choice	Suboptimal	Suboptimal
3	Client Server -> Salesforce integration where client can easily construct and encode an XML format SAML assertion	Suboptimal	Good choice	Suboptimal

Learn more about all flow on our speaker blog.

Summary

I hope this Salesforce OAuth Flows Guidelines and Tips helped you to understand different OAuth Flows in Salesforce.