Implement the OAuth 2.0 Web Server Flow

Choose a Flow

Now that you’ve built a Customer Order Status external client app for Help Desk users, you need to implement a flow for the app. Since the external client app is integrating an external web service (the Customer Order Status website) with the Salesforce API, you want to use the OAuth 2.0 web server flow. This authorization flow uses the authorization code grant type.

Request an Authorization Code

To initiate the OAuth 2.0 web server flow, the Customer Order Status web service—via the external client app—posts an authorization code request (using the authorization code grant type) to the Salesforce authorization endpoint. An authorization code is like a visitor’s badge. With it, the external client app can prove that it’s been authorized as a safe visitor to the site, and it has permission to request an access token.

The call is made in the form of an HTTP redirect, such as the following.

https://mycompany.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=code

If you’re not familiar with these types of calls, don’t worry. Let’s break it down into its individual components.

Component 1

https://mycompany.my.salesforce.com/services/oauth2/authorize

This address is the Salesforce instance’s OAuth 2.0 authorization endpoint. It’s the endpoint where your external client apps send OAuth authorization requests.

Component 2

client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq

The client ID is the external client app’s consumer key. To access the consumer key, from the External Client App Manager, click Edit Settings in the dropdown menu beside the external client app. Expand the OAuth Settings section, click Consumer Key and Secret, and then verify your identity.

The Consumer Details page opens with the Consumer Key and Consumer Secret listed.

Component 3

redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback

The redirect URI is where users are redirected after a successful authorization. The redirect URI is the external client app’s callback URL, which you can find on the external client app’s Settings tab.

This image shows the callback URL that corresponds with the code samples. For your connected app, use the callback URL you used in the first unit: https://openidconnect.herokuapp.com/callback

Component 4

response_type=code

The response type tells Salesforce which OAuth 2.0 grant type the external client app is requesting. The response type of codeindicates that the connected app is requesting an authorization code.

Authenticate the User and Grant Access to the App

Before Salesforce provides an authorization code to the external client app, you need to authenticate yourself by logging in to your Salesforce org.

After successfully logging in, click Allow to authorize the external client app to access your Salesforce org’s data.

Receive a Callback

After you authorize the app, Salesforce sends a callback to the connected app with an authorization code.

https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==

Component 1

The first part of the callback is the external client app’s callback URL.

https://www.mycustomerorderstatus.com/oauth2/callback

Component 2

The second part is the authorization code, approving the app.

code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==

Request an Access Token

Now that the external client app has a valid authorization code, it passes it to the Salesforce token endpoint to request an access token.

POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback

Let’s look at the individual components of this call, too.

Component 1

POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded

The first two lines of this component are the POST request being made to the Salesforce instance’s OAuth 2.0 token endpoint. This endpoint is where your external client apps send access and refresh token requests.

The second two lines show the length and type of the request’s content.

Component 2

grant_type=authorization_code

The grant type defines the type of validation that the external client app can provide to prove it's a safe visitor. In this case, it’s providing an authorization code.

Component 3

code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA

The authorization code is a temporary value that you get from the authorization server (Salesforce in this case). The external client app uses this code in exchange for an access token. This type of OAuth 2.0 flow is a secure way to pass the access token back to the application.

Component 4

client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq

This component should look familiar to you, too. It’s the external client app’s consumer key from the Client ID and Secret page.

Component 5

client_secret=*******************

The client secret is the same as the external client app’s consumer secret. You access the consumer secret the same way you access the consumer key.

Component 6

redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback

Do you remember this component from the first 2 calls? It’s the external client app’s callback URL.

Receive an Access Token

When you built the external client app, you selected the Require Secret for Web Server Flow option. This requirement means that Salesforce can’t give an access token to the external client app unless the app sends a valid consumer secret. So in this step, Salesforce validates the external client app’s authorization code, consumer key, and consumer secret.

After Salesforce validates the external client app’s credentials, it sends back an access token in a JSON format. The access token also includes associated permissions in the form of scopes, and an ID token for the app.

{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://mydomain.my.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}

Your Turn

Now it’s your turn to test out the OAuth 2.0 web server flow. Because sensitive information is passed between the Salesforce instance and the callback URL during the flow, it’s critical that this information isn’t passed to arbitrary locations. To securely demonstrate the authorization flow, we’re using a secure OpenID Connect Playground built just for this purpose. The OpenID Connect Playground is hosted on a secure Heroku server that shows the authorization flow while protecting your data.

When you implement this flow in the real world, it’s imperative to use a secure host for the callback URL so that your data is kept safe.

Let’s get started. First, collect some information about the connected app that you created in the first step of this project.

• Consumer Key
  
• Consumer Secret
  
• Callback URL
  
• My Domain URL
  

To access the consumer key, from the External Client Apps Manager, click Edit Settings in the dropdown menu beside the external client app. Expand the OAuth Settings section, click Consumer Key and Secret, and then verify your identity. To find your My Domain URL in Setup, enter My Domain in the Quick Find box then click My Domain.

Give It a Try

1. Open the OpenID Connect Playground.
   

2. Copy your Trailhead playground’s My Domain URL, and paste it after https:// as the login host.
   
3. Paste your external client app’s consumer key.
   
4. Paste your external client app’s consumer secret. The OpenID Connect Playground uses POST to submit information, meaning your client secret is not logged.
   
5. Verify that your external client app’s callback URL matches the Redirect URI (Callback URL).
   
6. Click Next to send a request for an authorization code.
   

If you receive a prompt to allow the OpenID Connect playground to access your Trailhead playground, go ahead and click Allow.

With a successful request, you receive an authorization code. On the right side of the page, you can view your authorization request and the Heroku server’s response.

7. Click Next to request an access token. With a successful request, you receive both an access token and an ID token. On the right side of the page, you can view your access token request and the Heroku server’s response.
   

8. Click Next again to pass the access token back to the Heroku server. The Heroku server should respond with your external client app’s metadata.
   

Congratulations! You built an external client app and authorized it against an actual server.

Resources

• Salesforce Help: OAuth Authorization Flows
• Salesforce Help: OAuth 2.0 Web Server Flow for Web App Integration
• Trailhead: API Basics