Create and Configure an External Client App

Learning Objectives

In this project, you’ll:

Build an external client app for API integration.
Implement the OAuth 2.0 Web Server flow.

What to Expect

In this project, you build external client apps and configure them for the OAuth 2.0 Web Server flow. You may know this flow as an authorization code grant type. After building an external client app, you’ll learn how to implement the authorization flow.

If you’ve completed the Build a Connected App for API Integration trail, you might experience a little deja vu. External client apps are the next generation of connected apps, so this project is modeled on the Create a Connected App Trailhead project. We call out places where external client apps are different from connected apps. If you haven’t completed the Connected Apps module, that’s no problem. This project requires no prior knowledge of connected apps.

But What If I’m Not a Developer?

In the External Client App Basics module, you learned about the different responsibilities of developers and admins. To remind you, an external client app developer is a Salesforce developer or independent software vendor (ISV) who builds API integrations or third-party applications that can access Salesforce data through an external client app. External client app developers configure settings to define the characteristics of an external client app, such as defining the type of data it can access. The majority of this project involves actions that developers take.

An external client app admin configures policies for the apps. Admins explicitly define who can use an external client app and where they can access the app from.

Whatever role you play with an external client app—developer, admin, or even both—you’ll benefit from completing all the steps of this project. By configuring an external client app from start to finish, you gain a better idea of how your org can benefit from them.

Let’s Not Forget Owners and Subscribers

Whether you’re a developer or an admin, you also need to know if your org is the external client app’s owner or a subscriber.

As an external client app owner, your org built the app. You can edit the app’s settings and policies. For example, you decide the type of information (such as a client secret) that the external client app must provide to gain access to data in your org.

As an external client app subscriber, your org installed the app as a second-generation (2GP) managed package from another org or a third-party vendor’s website. You can edit only the app’s policies, such as whether the app can access data from a remote location.

External client apps, unlike connected apps, have a Distribution State setting that defines the app as either Local or Packaged. A local external client app can’t be distributed, so your org owns any local apps you see on it. You’ll need to do a little investigation to find out if your org owns a Packaged app.

So how can you easily tell whether your org owns a Packaged external client app? The best way is to locate the app in the External Client App Manager, click the dropdown arrow next to it, and see which options are provided.

In this example, your org owns the My OAuth External Client App because you can edit both the external client app’s settings and policies. If your org were the subscriber, only the Edit Policies option would be available.

The External Client App Manager shows the app list with a packaged external client app. The dropdown menu is expanded and shows Edit Policies, Edit Settings, and Disable.

Launch Your Trailhead Playground

You complete this hands-on project in your own personal Salesforce environment. Get your Trailhead Playground now by first logging in to Trailhead, and then clicking the Launch button at the bottom of this page. After you complete the project steps in your playground, click Verify step at the bottom of the page.

An External Client App to Securely Access Customer Order Status Data

Your company recently developed a website that allows secure access to customer order status. The order status data is securely stored in your company’s Salesforce CRM platform.

Your company’s customer service manager wants his Help Desk users to be able to access customer order status data when assisting customers. He asks you to build a service that authorizes Help Desk users to securely access the order status data.

You know that Salesforce external client apps can be used to integrate third-party applications with the Salesforce API. So you decide to build an external client app that authorizes Help Desk users to securely access order status data.

Start with the Basics

The first step in creating an external client app is to give it a name and a description. These external client app basics help users quickly find the app they need.

From Setup, enter External Client App in the Quick Find box, then select External Client App Manager.
Click New External Client App.
In the Basic Information area of the page, specify the following information to describe the external client app.
- For the external client app’s name, enter Customer Order Status.
- For the external client app’s API name, press Tab to keep the default name: Customer_Order_Status. The API name is a unique identifier used when referring to the app programmatically. The API name defaults to the external client app’s name, replacing spaces with underscores.
- For the contact email, enter your email address. Salesforce uses this contact information if they need to contact you about the external client app. Later, we’ll access some consumer details that require an email verification code. Don’t worry, Salesforce won’t share this contact information.
- For distribution state, leave the field set to Local.
- For the logo image URL, click Choose one of our sample logos and select the Case Transcript logo from the Salesforce samples. After selecting the Case Transcript logo, copy and paste both the logo URL and the icon URL into the respective fields. This logo displays on both the App Launcher tile and the consent page that users see when authorizing the app.
- For the external client app’s description, enter External client app to securely access customer order status. This description displays on both the App Launcher tile and the consent page that users see when authorizing the app.

The External Client App Manager creation page is open and the basic information is entered in each of the fields.

Enable OAuth Settings for API Integration

Next, configure the external client app’s OAuth settings. These settings define how the external client app integrates with the Salesforce API.

Expand the Enable OAuth area of the page, and select Enable OAuth.
Enter the following callback URL—which is where your user is redirected after successful authorization—for the external client app: https://openidconnect.herokuapp.com/callback This URL is where the Help Desk user is taken when the Customer Order Status app is successfully approved. Because sensitive information is transmitted in an authorization flow, it’s imperative to use a secure host for the callback URL. The callback URL we are using for your external client app is hosted on a secure Heroku server using OpenID Connect. So your data is safe! For more information about OpenID Connect, see OpenID Connect.
Select the OAuth scopes to apply to the external client app. OAuth scopes define permissions for the connected app, such as whether the connected app can interact with the user’s data while the user is offline. Because you want the Customer Order Status app to access order status data that is stored in the Salesforce REST API via the web, apply these scopes that support the web server flow.
- Access unique user identifiers (OpenId): This scope allows the app to access the logged in user’s unique identifier for OpenID external client apps. You use the OpenID scope in the web server flow to receive a signed ID token conforming to the OpenID Connect specifications in addition to the access token.
- Manage user data via APIs (api): This scope allows access to the current, logged-in user’s account using APIs, such as REST API and Bulk API. This value also includes access to Chatter REST API resources.
- Manage user data via web browsers (web): This scope allows the app to use the access token on the web, and allows access to customer-created Visualforce pages.

The OAuth Settings section of the External Client App Manager creation page is open and the relevant information is entered in each of the fields.

Deselect Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows.
Select Require Secret for the Web Server Flow to require the app's client secret in exchange for an access token.
Select Require Secret for Refresh Token Flow to require the app’s client secret in the authorization request of a refresh token and hybrid refresh token flow. If you don’t select this option and an app sends the client secret in the authorization request, Salesforce still validates it. You can select this option for web-server based apps that can protect client secrets. But for apps that can’t protect client secrets, such as mobile apps or apps installed on a user’s computer, we recommend against selecting this option.

The Security section of the External Client App Manager creation page is open and the appropriate settings are selected.

Save these settings.

Save and Verify

Although there are additional settings that you can configure, such as defining what information is included in the ID token, you don’t need to define these characteristics for the Customer Order Status external client app. If you want to find out more about additional settings, hop on over to External Client Apps in Salesforce Help.

Let’s Flow

Now that we’ve demonstrated how to build a connected app, it’s your turn to give it a try. In the next step, you learn how to implement the OAuth 2.0 web server flow.

¿Necesita ayuda?