OAuth Authorization Flows

For example, when you open the Salesforce mobile app to access your Salesforce data, you initiate an OAuth 2.0 authorization flow. In this flow, your Salesforce org is the resource server that hosts the protected resource. The Salesforce mobile app is the client requesting access. You’re the resource owner, who allows the Salesforce mobile app to access and manage your Salesforce data over the web at any time. Your Salesforce org, acting as the authorization server, grants access to the Salesforce mobile app by issuing an access token. Let’s go over the flow step by step.

1. You open the Salesforce mobile app.
2. An authentication prompt displays, in which you enter your username and password.
3. The Salesforce mobile app sends your credentials to Salesforce and initiates the OAuth authorization flow.
4. Salesforce sends the mobile app access and refresh tokens as confirmation of a successful validation of the user and the mobile app.
5. You approve the request to grant access to the Salesforce mobile app.
6. The Salesforce mobile app starts.

After this initial flow, the Salesforce mobile app starts immediately when the session is active. If the session is stale, the Salesforce mobile app uses the refresh token from its initial authorization to get an updated session.

Contrast this approach with giving your username and password to a client app to access a resource server on your behalf. The client app effectively impersonates you, with precisely the same access to your data. If you no longer trust the client app, you must change your password at the resource server, which is an inconvenience and a security risk. For this reason, OAuth authorization is a better solution.

OAuth Authorization Flows and External Client Apps

All OAuth authorization flows, except for the SAML Assertion flow, require you to define an external client app. The external client app framework enables an third-party application to integrate with Salesforce using APIs and standard protocols, such as SAML, OAuth, and OpenID Connect. External client apps use these protocols to authenticate, authorize, and integrate external applications and service providers. The external applications that are integrated with Salesforce can run on the customer success platform, devices, SaaS subscriptions, or other platforms. In the example above, the Salesforce mobile app integrates with your org using an external client app.

Note Users can authorize an external client app to access protected data more than one time, for example, a laptop, a desktop computer, and a mobile device. The default is five authorizations per external client app per user. If a user tries to grant access to an external client app after reaching the org’s limit, the access token that has been unused for the longest period of time is revoked. Newer OAuth 2.0 external client apps using the web server flow are approved for more devices after the user has granted access. The user-agent flow requires user approval every time.

OAuth Authorization Flow Use Cases

As a Salesforce developer, you can choose from several OAuth authorization flows. When selecting the correct flow for your app, consider these use cases.

Important Some flows have important security considerations. For example, when using the web server flow, you must store the client secret securely. We recommend avoiding the user-agent and username-password flows because they transmit credentials. Instead, choose a flow that frees the app from having to manage, store, and protect credentials.

• Headless Identity Flows
  You can use Headless Identity APIs to configure login, registration, passwordless login, and more for an off-platform app. Headless Identity flows are available only for external users, also known as customers and partners.
• Create a Native Single Sign-On Experience in Your App
  With an optional parameter in the OAuth 2.0 web server flow and user-agent flow, you can build a single sign-on (SSO) experience that feels like your third-party app is integrated with an external identity provider. With this process, you link an OAuth flow to an SSO flow while maintaining control of the experience within your app. This parameter is supported for Experience Cloud sites, so you can use this capability to add SSO to a Headless Identity implementation. This parameter is also supported for My Domain.
• OAuth 2.0 Web Server Flow
  To integrate an external web app with the Salesforce API, use the OAuth 2.0 web server flow, which implements the OAuth 2.0 authorization code grant type. With this flow, the server hosting the web app must be able to protect the external client app’s identity, defined by the client ID and client secret.
• OAuth 2.0 User-Agent Flow
  With the OAuth 2.0 user-agent flow, users authorize a desktop or mobile app to access data by using an external or embedded browser. Client apps running in a browser using a scripting language such as JavaScript can also use this flow. This flow uses the OAuth 2.0 implicit grant type.
• OAuth 2.0 Refresh Token Flow
  The OAuth 2.0 refresh token flow renews access tokens issued by the OAuth 2.0 web server flow or the OAuth 2.0 user-agent flow.
• OAuth 2.0 Token Exchange Flow
  When Salesforce is just one component of an architecture that includes a central identity provider along with multiple apps and microservices, use the OAuth 2.0 token exchange flow to simplify your integration patterns. With this flow, exchange tokens from external identity providers for Salesforce tokens and grant access to Salesforce data.
• OAuth 2.0 for Hybrid Apps
  Managing web sessions for hybrid apps is complex with a typical user-agent or refresh token flow. In these flows, a hybrid app sets requested domain cookies and bridges an access token into a web session. But the access token and web session aren’t connected in these flows. Instead you must track when the access and refresh tokens expire and when the web session expires, and then manually rebridge the session to avoid interrupted service. To avoid this complex process, use the OAuth 2.0 hybrid app flows. These flows connect the access and refresh tokens with the web session to give hybrid apps direct web session management.
• OAuth 2.0 JWT Bearer Flow
  Sometimes you want to authorize servers to access data without interactively logging in each time the servers exchange information. For these cases, you can use the OAuth 2.0 JSON Web Token (JWT) bearer flow. This flow uses a certificate to sign the JWT request and doesn’t require explicit user interaction. However, this flow does require prior approval of the client app.
• OAuth 2.0 Client Credentials Flow
  Sometimes you want to directly share information between two applications without a user getting in the way. For these scenarios, you can use the OAuth 2.0 client credentials flow. In this flow, the client app exchanges its client credentials defined in the external client app—its consumer key and consumer secret—for an access token. This flow eliminates the need for explicit user interaction, though it does require you to specify an integration user to run the integration. You can use this flow as a more secure alternative to the OAuth 2.0 username-password flow.
• OpenID Connect Dynamic Client Registration
  Although not a typical authorization flow, you can use OpenID Connect dynamic client registration to enable your Salesforce instance as an independent OAuth authorization server to protect resources hosted on an external API gateway.
• Generate an Initial Access Token
  OpenID Connect dynamic client registration lets OAuth 2.0 clients—connected apps—directly register connected apps with Salesforce. To authenticate these client registration requests, Salesforce requires an initial access token.
• OpenID Connect Token Introspection
  As part of the authorization process, token introspection allows all OAuth connected apps to check the current state of an OAuth 2.0 access or refresh token. The resource server or connected apps send the client app’s client ID and secret to the authorization server, initiating an OAuth authorization flow. As part of this flow, the authorization server validates, or introspects, the client app’s access token. If the access token is current and valid, the client app is granted access.
• OAuth 2.0 Device Flow
  To integrate apps that run on devices with limited input or display capabilities, such as Smart TVs, appliances, and other IoT devices, use the OAuth 2.0 device flow. Command-line apps can also use this flow. Users can connect these apps to Salesforce by accessing a browser on a device with more advanced input capabilities, such as a desktop or mobile device.
• OAuth 2.0 Asset Token Flow
  To integrate IoT devices with the Salesforce API, use the OAuth 2.0 asset token flow. Asset tokens are an open-standards-based JWT authentication token for verifying and securing requests from connected devices. Asset tokens identify the device to a backend service that processes the stream of data and events from the device. These tokens allow registration of device data with the Salesforce platform and linking the device to Salesforce CRM data about the customer, account, or contact.
• Demo the Asset Token Flow
  For a quick demo of asset tokens, you can use the Asset Token Explorer demo app. The demo app simplifies your initial experience of getting an access token and exchanging it for the asset token.
• OAuth 2.0 Username-Password Flow
  You can use the username-password flow to authorize a client via a connected app that already has the user’s credentials. However, we recommend avoiding this flow because it passes credentials back and forth. Use it only if there’s a high degree of trust between the resource owner and the client, the client is a first-party app, Salesforce is hosting the data, and other grant types aren’t available. In these cases, set user permissions to minimize access and protect stored credentials from unauthorized access.
• Block Authorization Flows to Improve Security
  The OAuth 2.0 user-agent and username-password flows are considered insecure and aren’t recommended. For better security, we strongly recommend that you block these flows in Salesforce to prevent developers from using them to build new integrations. If your org is created in Summer ‘23 or later, the username-password flow is blocked by default. You can enable the username-password flow if needed. If you have existing integrations that use the user-agent or username-password flow, update them to a more secure OAuth 2.0 flow. You can also block the Authorization Code and Credentials Flow, which is used to securely configure a headless login process. And you can block certain flows that don’t use the PKCE extension.
• OAuth 2.0 SAML Bearer Assertion Flow
  With the OAuth 2.0 SAML bearer assertion flow, a client—via a connected app—can use previous authorization by supplying a signed SAML 2.0 assertion to request an OAuth access token. The digital signature applied to the SAML assertion authenticates the authorized app. A SAML assertion is an XML security token issued by an identity provider and consumed by a service provider. The service provider relies on its content to identify the assertion’s subject for security-related purposes.
• SAML Assertion Flow
  The SAML assertion flow is an alternative for orgs that use SAML to access Salesforce and want to access the API the same way. Clients can federate with the API using a SAML assertion, the same way they federate with Salesforce for Web Single Sign-On (Web SSO). You can use this assertion flow without a connected app.
• OAuth 2.0 Authorization Errors
  Errors can occur during OAuth authorization. For example, a user denies access to the connected app or request parameters are incorrect. When errors occur, the authorizing server sends an error to the callback URL with an error code.
• OAuth 1.0.A Flow
  If your org uses the OAuth 1.0.A protocol, use this authorization flow to integrate a client—via a connected app—with the Salesforce API.
• OAuth 1.0.A Authorization Error Codes
  Errors can occur during authorization. For example, the callback URL is invalid. When errors occur during the OAuth 1.0.A flow, Salesforce returns an error code.