Access Data with API Integration

If you’re new to OAuth 2.0, we recommend familiarizing yourself with the protocol’s common terminology, which you can read about in the Salesforce Help article, Connected App and OAuth Terminology.

You can use a connected app to request access to Salesforce data on the behalf of an external application. For a connected app to request access, it needs to be integrated with the Salesforce API using the OAuth 2.0 protocol. OAuth 2.0 is an open protocol that enables authorization and secure data sharing between applications through the exchange of tokens. When developers want to integrate their app with Salesforce, they use OAuth APIs. These OAuth APIs enable a user to work in one app but see the data from another.

When you open the Salesforce mobile app to access your Salesforce data, you’re initiating an OAuth 2.0 authorization flow. In this flow, your Salesforce org is the resource server and the Salesforce mobile app is the client requesting access. You authorize the Salesforce mobile app to access and manage your Salesforce data over the web at any time.

The flow of events during OAuth authorization depends on the state of authentication on the device.

First Time Authorization Flow

1. You open the Salesforce mobile app.
2. An authentication prompt appears.
3. You enter your username and password.
4. The Salesforce mobile app sends your credentials to Salesforce and initiates the OAuth authorization flow.
5. You approve the request to grant access to the Salesforce mobile app, as shown in the image above.
6. Salesforce sends the mobile app access and refresh tokens as confirmation of successful authorization.
7. The Salesforce mobile app starts.

Ongoing Authorization

1. You open the Salesforce mobile app.
2. If the session is active, the Salesforce mobile app starts immediately. If the session is stale, the Salesforce mobile app uses the refresh token from its initial authorization to get an updated session.
3. The Salesforce mobile app starts.

To integrate an external web application with the Salesforce API, use the OAuth 2.0 web server flow. With this flow, the server hosting the web app must be able to protect the connected app’s identity, defined by the client ID and client secret.

For example, you’ve recently developed a website that allows secure access to customer order status. The order status data is securely stored in your Salesforce CRM platform. To authorize Help Desk users to view a customer’s order status, you develop an Order Status app and configure it as a connected app with the web server flow.

1. A Help Desk user clicks the Order Status web app.
2. The connected app directs the user to Salesforce to authenticate and authorize the app to access the order status data.
3. The user approves the Order Status app to access the data.
4. Salesforce sends a callback to the Order Status app with an authorization code.
5. The Order Status app passes the authorization code to the Salesforce token endpoint, requesting an access token.
6. Salesforce validates the authorization code, and sends back an access token that includes associated permissions in the form of scopes.
7. The Order Status app sends a request back to Salesforce to access the order status data. Its request includes the access token with the associated scopes.
8. Salesforce validates the access token and associated scopes.
9. The Order Status app can access the protected data, and the customer’s order status is displayed in the app.

A connected app is a primary means by which a mobile app connects to Salesforce. Although not required, you can use Salesforce Mobile SDK to build mobile applications as connected apps. These apps can access Salesforce OAuth services and call Salesforce REST APIs.

Let’s say you use Salesforce Mobile SDK to build a mobile app that looks up customer contact information from your Salesforce org. Mobile SDK implements the OAuth 2.0 user-agent flow for your connected app, integrating the mobile app with your Salesforce API and giving it authorized access to the defined data.

1. The end user opens the mobile app.
2. The connected app directs the user to Salesforce to authenticate and authorize the mobile app.
3. The user approves access for this authorization flow.
4. The app receives the callback from Salesforce to the redirect URL, which extracts the access and refresh tokens.
5. The connected app uses the access token to access data on the end user’s behalf.

For more information about Salesforce Mobile SDK, check out the Salesforce Mobile SDK Basics Trailhead Module.

In some cases, you need to authorize servers without interactively logging in each time the servers need to exchange information.

To provide authorization for server-to-server integration, you can use the OAuth 2.0 JSON Web Token (JWT) bearer flow. This flow requires prior approval of the client app.

1. The report service begins its nightly batch report.
2. The connected app sends the JWT, which enables identity and security information to be shared across security domains, to the Salesforce token endpoint.
3. Salesforce validates the JWT based on a signature using a previously configured certificate and additional parameters.
4. Assuming that the JWT is valid and that the connected app has prior approval, Salesforce issues an access token. Prior approval happens in one of these ways.
   • If your connected app policy is set to “Admin approved users are pre-authorized,” you can use profiles and permission sets.
   • If your connected app policy is set to “All users may self-authorize,” you can use end-user approval and issuance of a refresh token. However, the client doesn’t need a current or stored refresh token. The client also doesn’t need to pass a client secret to the token endpoint.
5. The connected app uses the access token to access the protected data on the Salesforce server.
6. The report service pulls the authorized data into its nightly report.

To integrate devices with limited input or display capabilities, such as Smart TVs, you can configure connected apps with the OAuth 2.0 device flow.

With the device flow, end users can authorize connected apps to access Salesforce data using a web-based browser.

For example, a customer uses your bluetooth device to control their house lights while they are away for the evening. You can create a connected app for the bluetooth device to enable this flow.

1. The user opens the bluetooth app on their mobile device and clicks Turn On Lights.
2. The connected app posts a request to the Salesforce authorization endpoint.
3. Salesforce verifies the request and returns a human-readable user code, verification URL, and device code.
4. The bluetooth app displays the device code, and instructs the user to enter it at the specified verification URL. The app also begins polling the Salesforce token endpoint for authorization.
5. The user clicks the link to the verification URL and enters the code.
6. The user then authorizes the app to access their protected data, in this case their home’s location.
7. Salesforce sends an access and refresh token to the connected app.
8. The bluetooth app can access the user’s home location and turn on the lights.

You can also use the asset token flow for IoT integration. This flow uses a JWT that ties the user and device together, authorizing the device. You can read more about this flow in this Salesforce Help article: OAuth 2.0 Asset Token Flow for Securing Connected Devices.

In addition to the examples above, you can also use the following OAuth 2.0 flows with connected apps.

Now that you’ve learned more about when to use connected apps for accessing data in your Salesforce org, let’s move on to using connected apps for single sign-on.