Create an External Client App

Create an SFDX Project

Now that your environment is set up, it’s time to create your external client app. To do that, you need an SFDX project.

1. Create a folder called ECA Metadata on your computer where you want to create the app.
   
2. Open the folder in VS Code.
   
3. Open the Terminal in VS Code at the folder you created.
   
4. Run this command in the Terminal to create a Salesforce DX project called ecaViaMetadata with the standard template.
   

sf project generate --name ecaViaMetadata --template standard

Authorize Your Dev Hub Org

Connect the SFDX project on your computer to the Trailhead Playground Dev Hub using the connected app. You’ll need your domain for this step. To find your domain in Setup, enter My Domain in the Quick Find box then click My Domain.

1. Open the SFDX project ECA Metadata folder in VS Code.
   
2. In the Terminal in VS Code, run this command after replacing <my domain> with your org’s domain.
   

sf org login web --set-default-dev-hub --alias ecaViaMetadata --instance-url https://<my domain>

3. Log in with your Trailhead Playground credentials in the web page that opens.
   
4. Allow access to the org.
   

Configure the SFDX Project for an External Client App

1. Open the sfdx-project.json file in VS Code.
   
2. Update the sfdcLoginUrl parameter to your domain.
   

To find your domain in Setup, enter My Domain in the Quick Find box then click My Domain.

3. Expand the directory called config and open the scratch org definition file, which is called project-scratch-def.json. Add ExternalClientApps and ExtlClntAppSecretExposeCtl to the features setting.
   

	  "features": ["EnableSetPasswordInApi", "ExternalClientApps", "ExtlClntAppSecretExposeCtl"],

4. Create a package.xml manifest file in the project directory.
   
5. Add this content to your package.xml file.
   

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>ExternalClientApplication</name>
    </types>
    <version>61.0</version>
</Package>

6. In the force-app/main/default directory, create a folder called externalClientApps.
   
7. Add a file to the externalClientApps folder called ecaViaMetadata.eca-meta.xml. This will be the header file for your external client app.
   

8. Add this content to your header file.
   

<?xml version="1.0" encoding="UTF-8"?>
<ExternalClientApplication xmlns="http://soap.sforce.com/2006/04/metadata">
    <contactEmail>eca_metadata@example.com</contactEmail>
    <description>External client app Metadata API creation</description>
    <distributionState>Local</distributionState>
    <isProtected>false</isProtected>
    <label>ecaViaMetadata</label>
</ExternalClientApplication>

At this point your external client app is technically complete. You could deploy this configuration, and it would show up in the External Client App Manager on your playground as a basic external client app. However, to make a useful app, you need a plugin. Let’s configure an OAuth plugin similar to the one we made in the first module. An OAuth plugin that is configured for the OAuth 2.0 Web Server flow requires a couple of edits and a couple new files.

Enable and Configure the OAuth Plugin

Unlike connected apps, which combine all configurations in a single file, external client apps include two settings files and a policies file. The Global OAuth Settings file includes those sensitive fields like OAuth consumer key and consumer secret that should be protected. The OAuth Settings file includes all of the less-sensitive configurations for an external client app. There is no need to create a policies file while configuring an external client app for the web server flow, because policies are configured based on the settings files. The OAuth Policies file is generated when you deploy the external client app.

Create a Global OAuth Settings File

1. In the force-app/main/default directory, create a folder called extlClntAppGlobalOauthSets.
   
2. Add a file to the extlClntAppGlobalOauthSets folder called ecaViaMetadataGlblOAuth.ecaGlblOauth-meta.xml.
   

3. Open ecaViaMetadataGlblOAuth.ecaGlblOauth-meta.xml in VS Code and add this content to it.
   

<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <callbackUrl>https://openidconnect.herokuapp.com/callback</callbackUrl>
    <externalClientApplication>ecaViaMetadata</externalClientApplication>
    <isConsumerSecretOptional>false</isConsumerSecretOptional>
    <isIntrospectAllTokens>false</isIntrospectAllTokens>
    <isPkceRequired>false</isPkceRequired>
    <isSecretRequiredForRefreshToken>true</isSecretRequiredForRefreshToken>
    <label>ecaViaMetadataglobalset</label>
    <shouldRotateConsumerKey>false</shouldRotateConsumerKey>
    <shouldRotateConsumerSecret>false</shouldRotateConsumerSecret>
</ExtlClntAppGlobalOauthSettings>

4. Save the Global OAuth Settings file.
   

Create an OAuth Settings File

1. In the force-app/main/default directory, create a folder called extlClntAppOauthSettings.
   
2. Add a file to the extlClntAppOauthSettings folder called ecaViaMetadataSettings.ecaOauth-meta.xml.
   

3. Open ecaViaMetadataSettings.ecaOauth-meta.xml in VS Code and add this content to it.
   

<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <commaSeparatedOauthScopes>Api, Web, OpenID</commaSeparatedOauthScopes>
   <externalClientApplication>ecaViaMetadata</externalClientApplication>
    <label>ECA via Metadata Oauth Settings</label>
</ExtlClntAppOauthSettings>

4. Save the OAuth Settings file.
   

Reference Settings Files in the Header File

Now that you have created the two settings files, you need to incorporate them into the external client app. The Header file is a list of all the files that make up the external client app.

1. Open the package.xml manifest file.
   
2. Add an entry for each of the three OAuth files.
   

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>ExternalClientApplication</name>
    </types>
    <types>
        <members>*</members>
        <name>ExtlClntAppOauthSettings</name>
    </types>
    <types>
        <members>*</members>
        <name>ExtlClntAppGlobalOauthSettings</name>
    </types>
    <types>
        <members>*</members>
        <name>ExtlClntAppOauthConfigurablePolicies</name>
    </types>
    <version>61.0</version>
</Package>

3. Save the package.xml manifest file.
   

Deploy Your External Client App

Now that your external client app is properly configured, deploy the app. The policies file is created on deployment, so after you deploy, retrieve the external client app to pull the generated file to your SFDX project.

1. Run this command to deploy the external client app. Replace <username> with the username you used to log in when you authorized the Dev Hub.
   

sf project deploy start --manifest package.xml --target-org <Username>

2. Retrieve the external client app from your Trailhead Playground. Replace <username> with the username you used to log in when you authorized the Dev Hub.
   

sf project retrieve start --manifest package.xml --target-org <username>

Verify Your App

After successfully deploying and retrieving the external client app, you should see a policies file in your SFDX project where there wasn’t one before.

Also, you can open the External Client App Manager and see a new external client app called ecaViaMetadata. If you’re feeling adventurous, you could collect your My Domain and the OAuth consumer key and secret, and plug it all into the OpenID Connect Playground to walk through the OAuth Web Server flow.

Resources

• Salesforce Help: Create an External Client App with Metadata API
• Salesforce Help: Understanding Metadata API
• Salesforce Help: Deploying and Retrieving Metadata
• Salesforce Help: How Salesforce Developer Experience Changes the Way You Work
• Trailhead: API Basics