TL;DR I just want to know which flow to use

If you're short on time or just want to know what flow is for you, just go here.

Introduction

Brief Overview

OAuth, which stands for Open Authorization, is an open-standard protocol that provides users with secure access to resources on an application, such as Salesforce, without needing to share their credentials.

Think of OAuth as the internet's version of a valet key. It's a system that allows you to use applications like Salesforce without having to hand over your password. Instead, you give them this 'valet key' (OAuth), which grants them limited access to your account, without letting them run wild with your personal information.

Importance of OAuth 2.0 in Salesforce

In the context of Salesforce, OAuth 2.0 plays a crucial role in enabling secure access for both users and applications. Salesforce uses OAuth 2.0 to authenticate users from various devices and applications, and to authorize these authenticated users to interact with Salesforce APIs.

It's like the bouncer of the Salesforce club, checking IDs (authenticating users) and making sure everyone sticks to the rules (authorizing user actions).

Post Objective

This post is designed to give beginners an understanding of Salesforce OAuth 2.0 flows. We'll break down what OAuth 2.0 is, why Salesforce uses it, and the different ways (or 'flows') it can work.

Just a quick heads up before we dive in - this post is going to focus solely on OAuth 2.0 and its flows within Salesforce. We won't be getting into the nitty-gritty of Open ID Connect (OIDC), even though it's based on OAuth 2.0. OIDC is a whole other ballgame and deserves its own dedicated discussion. So, for today, let's keep the spotlight on understanding Salesforce OAuth 2.0 flows. Ready? Let's jump right in!

Understading OAuth 2.0

Basic Terminology

Client App

This is the application that wants to access the user's account. It could be a web app, a mobile app, or any other software that needs to interact with protected resources on behalf of the user.

Resource Server

This is the server hosting the protected resources. It's the place the client wants to access - for instance, a Salesforce server where user data is stored.

Authorization Server

This is the server that authenticates the user's identity and issues access tokens to the client. In many cases, the authorization server and the resource server can be the same server (as for example Salesforce).

Resource Owner

This is the person who owns the account that the client wants to access. In the context of Salesforce, this would typically be a Salesforce user.

Client Id

This is a publicly exposed string that is used by the service (like Salesforce) to identify the application, similar to a username. It's unique to the client application and can be included in the code of a publicly accessible application without any security risks.

Client Secret

This is a secret known only to the application and the authorization server, similar to a password. It should be kept private. The client secret is used by the service to ensure that the application asking for a user's data is the one it claims to be. Therefore, it should never be included in publicly accessible areas such as client-side code or version control systems.

Access Token

This is the key that the client receives from the authorization server. It's what the client uses to access the resource server. Access tokens are limited in scope (they can only access certain resources) and duration (they expire after a certain time).

Refresh Token

This is a special kind of token that can be used to get a new access token when the old one expires. Not all OAuth 2.0 flows use refresh tokens, but they're handy for allowing long-lived access without needing the user to re-authenticate.

Scope

This refers to the specific resources that an access token can access. For instance, an access_token might have the scope to read user data but not modify it. There are multiple Salesforce Scopes that can be selected, including full access, API access, refresh_token access and others.
The full list is here.

Redirect URI

This is the location where the authorization server will send the user after they've authorized (or denied) the client's access request. It's usually a URL associated with the client application.

How OAuth 2.0 Works

OAuth 2.0 works by providing a process for end-users to authorize applications to access their data on other applications. Process of granting this access depends on the type of the used flow, but the result is always the same - access to the resource is allowed.

Connected Apps in Salesforce

Connected Apps in Salesforce are the hearth of Salesforce resource access management. One of the things they allow is OAuth 2.0. All the flows require Connected App, but this app will be configured differently based on different flows.

Please be aware that from some time we have access to External Client Apps in Salesforce, which will be overtaking the Connected App usage. It is not a must have but I recommend to familiarize with the concept.

Main OAuth 2.0 Flows in Salesforce

Web-Server Flow

The Web Server OAuth 2.0 flow is designed for applications that are capable of securely storing secrets and communicating directly with the authorization server. In this flow, the server application handles the heavy lifting of authentication on behalf of the client. Again, this method is only suitable if the client_secret can be protected and kept confidential by the client application.

The Web Server flow generally unfolds in two main stages:

1. User Login and granting the consent
2. Acquiring the Access Token by Client Application.

The first step provides the authorization_code which is then securely exchanged by Client Application for the access_token and refresh_token (if requested in scopes) in the second step. This way, the client application can access the user's data without needing to know the user's credentials.

Diagram

Example

Suppose you have a web application that displays a summary of users' Salesforce data. The Web Server OAuth 2.0 flow can be a great tool for this. When a user logs in, they grant your app access to their Salesforce data. Salesforce then provides an authorization code, which your app exchanges for an access_token and a refresh_token.

You can securely store this refresh_token. It allows your app to fetch the latest Salesforce data on the user's behalf, anytime, even when they're offline. So, users always see up-to-date data when they log in. This flow is ideal for server-side applications that can securely store the client_secret.

PKCE Flow

The Proof Key for Code Exchange (PKCE) flow is the User-Agent flow's more secure version, and follows similar process as Web-Server flow with two phases. It's designed for client-side authentication rather than server-side.

When an app wants to access secure data, it creates a random string (the code_verifier) and a scrambled version of that string (the code_challenge) using encryption. The app first sends the scrambled string to the server. Later, it sends the original string. The server scrambles it again and checks if it matches the first scrambled string. If they match, it means the request is coming from the right app. The server then sends back special keys (the access_token and refresh_token) that the app can use to access the data.

These features prevent the token from being exposed in the URL, as they allow for secure POST requests. This makes PKCE the go-to choice when you can't securely store the client_secret, such as with device applications.

PKCE also tackles security vulnerabilities like CSRF Attacks, Token Replay Attacks, and Access Token exposure in the browser, which are common issues with the User-Agent flow. So, if you're looking for a more secure OAuth 2.0 flow, PKCE is a strong contender.

Diagram

Example

Imagine you've developed a mobile application that allows users to track their Event Schedule across multiple Salesforce orgs. How can your app access data from these customer orgs?

Web Server flow isn't suitable here because mobile applications can't securely store the client_secret. So, we turn to the PKCE flow.

With PKCE, your mobile app can securely exchange the client_id, code_challenge, and code_verifier for an access_token and refresh_token. These tokens can then be used to fetch Event data from various Salesforce instances. The beauty of PKCE is that it provides a secure OAuth 2.0 flow even when client_secret can't be safely stored, making it a great fit for mobile applications.

JWT Bearer Token Flow

The JWT Bearer Token flow is a key player in server-to-server OAuth 2.0 interactions. It uses JSON Web Tokens (JWT), which are created and signed by one server using the private key of a certificate. JWT Tokens contains information like client_id, username, and expiration time, that are used by Salesforce to authorize the right user with the right access.

The beauty of this is that the recipient server (Salesforce in our case) can quickly verify the authenticity of the token (and thus the sender) by checking the signature using the public key assigned in Connected Application.

A standout feature of this flow is that there's no user interaction involved. Instead, access to resources is explicitly granted by Salesforce Administrators on the Connected App, using Profiles or Permission Sets.

So, if you're looking for a secure and efficient way to handle server-to-server integrations and your systems support it, the JWT Bearer Token flow is typically the go-to choice.

Diagram

Example

Imagine you're tasked with integrating an Enterprise Service Bus (ESB), like Mulesoft or Dell Boomi, with your Salesforce instance. This isn't a small task - both servers are securely running vital operations, and there's no client application involved to facilitate the integration. Plus, the data being transferred is critical, so top-notch security is a must.

In this scenario, the JWT Bearer Token flow shines as the perfect solution for secure server-to-server communication. These tokens are like special packages, signed and sealed by the ESB using a private key. Upon receiving the token, Salesforce can quickly confirm it's from a trusted source by verifying the signature.

Asset Token Flow

The Asset Token OAuth 2.0 flow is tailor-made for Internet of Things (IoT) devices. It's a bit like a relay race, where an access_token obtained from another OAuth 2.0 flow is passed along with an Actor Token (which is essentially device metadata in JSON format) to the Salesforce authorization server.

In exchange, Salesforce hands back an asset_token. This isn't just any token; it's a variation of a JWT token that carries valuable Asset information.

But here's where the Asset Token flow really shines: as part of this process, Salesforce automatically creates or updates the Asset record. This means your IoT device isn't just communicating with Salesforce; it's also helping to keep your Salesforce data up-to-date.

So, if you're working with IoT devices and want to keep your Salesforce Asset records in sync, the Asset Token flow is a great option to consider.

Diagram

Example

Picture this: your company sells smart fridges and you want to integrate these fridges with Salesforce to send necessary data. Here's where the Asset Token flow comes into play.

Each smart fridge can be authorized with Salesforce using the Asset Token flow. Once authorized, the fridge stores an asset_token, which it uses every time it sends data to Salesforce.

But here's the cool part: this asset_token is created from a combination of an access_token (which is linked to a specific user) and an Actor Token (which is tied to the specific fridge). This means that when the asset_token is created, Salesforce automatically creates an Asset record linked to the correct user or account.

So, with the Asset Token flow, your smart fridges aren't just sending data to Salesforce; they're also helping to keep your Salesforce Asset records accurate and up-to-date. It's a smart solution for your smart fridges!

Refresh Token Flow

The Refresh Token flow is like the marathon runner of OAuth flows. It uses a refresh_token, which can be obtained from any other flow that supports it, to keep the authentication going for the long haul.

The main goal of this flow is to let applications swap a long-lived refresh_token for a short-lived access_token. This means users don't have to go through the hassle of authorizing the app too often, which is a big plus in today's fast-paced world.

But don't worry, it's not an 'all-access pass'. These tokens can be revoked at any time, and they don't have any ties to your username or password. So, if there's a breach, attackers only get access to the resources within the access_token's scopes. It's a handy way to keep things secure, while making life easier for users.

Diagram

Example

Let's say you've developed an app that's already been authorized using another OAuth 2.0 flow. Now, you want to keep things running smoothly without bothering the user to re-authorize frequently. This is where the Refresh Token flow comes in handy.

With the refresh_token your app received during the initial authorization, you can use the Refresh Token flow to obtain a new access_token whenever needed.

In short, the Refresh Token flow keeps your app's connection to Salesforce fresh and active, ensuring a seamless experience for your users.

User-Agent Flow

The User-Agent flow is a bit like a last resort option - it's best to avoid it if you can implement the PKCE flow instead. Why? Well, because of its reliance on GET requests and redirects, this flow comes with a few security vulnerabilities that could potentially be exploited.

Like the PKCE flow, the User-Agent flow assumes that the user can't securely store the client_secret. However, its security mainly depends on the whitelisting of the Redirection URI. After the user logs in and grants access, they're redirected to a specified URL with the access_token and possibly a refresh_token included.

This might sound fine, but the issue is that these tokens could potentially be intercepted by a malicious party during the redirect. So, while the User-Agent flow can be useful in certain situations, it's generally safer to opt for the PKCE flow if possible.

Diagram

Example

Imagine you're developing a mobile application. Due to the nature of the app, you can't securely store the client_secret, but your chosen framework also doesn't support generating a code_challenge and code_verifier for the PKCE flow. You're in a bit of a bind.

This is where the User-Agent flow can come to the rescue. Even with its potential security vulnerabilities, it can be a viable option when other flows aren't feasible due to technical constraints. So, in this scenario, the User-Agent flow could be the right choice for enabling secure communication between your mobile app and Salesforce.

Client Credentials Flow

The Client Credentials flow is a server-to-server flow that operates a bit like a digital handshake. It allows the exchange of client_id and client_secret for an access_token. This flow requires a specified running user under the Connected App in Salesforce.

However, this flow comes with a significant security vulnerability: the risk of a man-in-the-middle attack. If a malicious party intercepts the client_id and client_secret, they could compromise the entire integration. This is in contrast to the JWT Bearer Token flow, which sends a signed signature with a salt. This makes the token a one-time pass, rendering it useless after a single use.

So, while the Client Credentials flow can be useful in certain scenarios, it's important to be aware of its potential security risks and to consider more secure options like the JWT Bearer Token flow where possible.

Diagram

Example

Let's say you're working with a server that, due to technical constraints, can't support the JWT Bearer Token flow. You might feel like you're stuck between a rock and a hard place, but there's another option you can consider: the Client Credentials flow.

Username-Password Flow

The Username-Password flow is a client flow that essentially swaps username/password credentials for an access_token. However, this flow comes with a big 'handle with care' label.

Due to significant security risks, it's generally not recommended for production use. Imagine user credentials zipping around the web just to get an access_token - it's not the most secure picture. If an attacker gets hold of these details, they could log into Salesforce and have free rein to do anything the user can do. And since they can login directly via Salesforce login page (not using the access_token), the defined scopes won't provide any restrictions.

So, while the Username-Password flow can be useful for quick testing or development, it's best to steer clear of it for production applications due to its security vulnerabilities.

Diagram

Example

Let's say you're just dipping your toes into the world of OAuth 2.0 flows, or you're a developer in need of a quick access_token for testing or development purposes. The Username-Password flow can be a useful tool in your arsenal.

Choosing the right OAuth 2.0 flow

Keep in mind, while it's technically possible to use almost any OAuth 2.0 flow for any situation and still have your integration function, doing so without considering the security implications can be like playing with fire. Choosing the wrong flow could expose your application to significant security risks.

It's like using a sledgehammer to crack a nut - it might work, but it's probably not the best tool for the job. So, always consider the specific needs and context of your application when choosing an OAuth 2.0 flow to ensure you're maintaining the highest level of security.

If you cannot securely store a secret

Your go-to should be the PKCE Flow. If your app can't support code_challenge and code_verifier, then consider the User-Agent Flow.

If a server (that can securely store a secret) is authenticating on behalf of a client

In this scenario, the Web-Server Flow is your best bet.

If you're integrating a device with Salesforce

For asset devices, opt for the Asset Token Flow. In other cases, the Device Flow (not covered in this post) is a good choice.

If you're integrating two servers

The JWT Bearer Token Flow should be your first choice. If this flow isn't supported, then try the Client Credentials Flow.

For quick development or proofs of concept

The Username-Password Flow can be handy.

How to implement it?

To implement any of these OAuth 2.0 flows, your first port of call should be the official Salesforce documentation. It's a treasure trove of detailed guides and instructions to help you navigate the process.

For practical examples of requests for all the authorization flows, check out the Postman Salesforce Platform API specification. It's like a cookbook for Salesforce API requests, providing you with all the 'recipes' you need.

And remember, you're not alone in this journey. If you hit a roadblock or just need a bit of guidance, don't hesitate to reach out to us. Our team at Beyond The Cloud is always here to lend a hand and help you navigate your way to successful Salesforce integration.

Resources

Salesforce OAuth 2.0 Flows Documentation
Postman Salesforce Platform API specification
Salesforce OAuth Flows