Create a Connected App

Learning Objectives

In this project, you’ll:

• Build a connected app for API integration.
  
• Implement the OAuth 2.0 web server flow.
  
• Manage access to the connected app for your org.
  

What to Expect

In this project, you build a connected app for API integration, using the OAuth 2.0 web server flow. You may also know this flow as the authorization code grant type. After building your connected app, we show you how to implement the authorization flow. You then define which users can access the connected app and where they can access it from using OAuth policies.

But What If I’m Not a Developer?

In the Connected App Basics module, we talked about the different responsibilities of connected app developers and connected app admins. To remind you, a connected app developer is a Salesforce developer or independent software vendor (ISV) who builds API integrations or external apps that can access Salesforce data as a connected app. Connected app developers define the characteristics of a connected app, such as defining the type of data it can access. In the real world, they typically perform steps 1 and 2 covered in this Trailhead project.

On the other hand, a connected app admin configures permissions and policies for the apps. Admins explicitly define who can use a connected app and where they can access the app from. Admins also install, uninstall, and—when necessary—block connected apps from your Salesforce org. In the real world, they typically perform the third step covered in this Trailhead project.

Whatever role you play with a connected app—developer or admin—we believe that you can benefit from completing all three steps of this project. By configuring a connected app from start to finish, you gain a better idea of how your org can benefit from them.

Let’s Not Forget Owners and Consumers

In addition to whether you’re a developer or admin, you also need to know whether your org is the connected app’s owner or consumer.

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

As a connected app consumer, your org installed the app from the AppExchange, as a managed package from another org or a third-party vendor’s website, or as metadata without packaging. You can edit only the app’s access policies, such as who can use the app and whether the app can access data from a remote location.

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

In this example, your org owns the My OAuth Connected App because you can both Edit the connected app’s characteristics and Manage its access policies.

However, your org is a consumer of the Trailhead connected app. You can only Manage the app’s access policies because your org installed this connected app as a managed package from Trailhead.

Now that we’ve reviewed the roles you and your org play with a connected app, let’s get to building. In this step, you’re the developer—and owner—of the connected app.

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.

A Connected 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 connected apps can be used to integrate external applications with the Salesforce API. So you decide to build a connected app that authorizes Help Desk users to securely access order status data.

Start with the Basics

The first step to take in creating a connected app is to give it a name, an easily identifiable logo, and a description. These connected app basics help users quickly find the app they need.

1. From Setup, enter App in the Quick Find box, then select App Manager.
   
2. Click New Connected App.
   
3. In the Basic Information area of the page, specify the following information to describe the connected app:
   

• For the connected app’s name, enter Customer Order Status.
  
• For the connected app’s API name, which is a unique identifier used when referring to the app programmatically, just press Tab. The API name defaults to the connected app’s name, replacing spaces with underscores.
  
• For the contact email, enter help.desk@mycompany.com. Salesforce uses this contact information if they need to contact you about the connected app. Don’t worry, Salesforce won’t share this contact information.
  
• For the logo image URL, select the Case Transcript logo from the Salesforce samples by clicking Choose one of our sample logos. 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 connected app’s description, enter Connected 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.
  

Enable OAuth Settings for API Integration

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

1. In the API (Enable OAuth Settings) area of the page, select Enable OAuth Settings.
   
2. Enter the following callback URL—which is where your user is redirected after successful authorization—for the connected 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 connected 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.
   
3. Select the OAuth scopes to apply to the connected 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 Connect 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.
  

4. Deselect Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows.
   
5. Select Require Secret for the Web Server Flow to require the app's client secret in exchange for an access token. 
   

6. 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.
   

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 connected app. If you want to find out more about additional settings, hop on over to Create a Connected App in Salesforce Help.

Now all you have left to do is save your new connected app, verify the settings, and make sure it shows up on the App Menu page so Help Desk users can access it from the App Launcher.

1. Click Save.
   
2. Click Continue. You’re taken to the Manage Connected Apps page where you can view the settings for your new connected app.
   
3. Verify that you defined the correct settings for the connected app. It should look like the following.
   

4. Copy the callback URL and paste it into a text editor. You need it for the next step.
   
5. You also need the consumer key and consumer secret. To access them, click Manage Consumer Details, and then verify your identity. Copy the consumer key and consumer secret and paste them into a text editor.
   
6. Return to Setup, enter App in the Quick Find box, and select App Menu.
   
7. Scroll to the end of the App Menu page to see your Customer Order Status connected app. You can also see that it’s visible in the App Launcher so that Help Desk users can quickly access it.
   

You just built a connected app. Way to go!

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, we show you how to implement the OAuth 2.0 web server flow.

Resources

• Trailhead: Connected App Basics
  
• Salesforce Help: Create a Connected App
  
• Salesforce Help: OAuth Tokens and Scopes
  
• Website: Welcome to OpenID Connect