📢 Attention Salesforce Certified Trailblazers! Maintain your credentials and link your Trailhead and Webassessor accounts by April 19th. Learn more.
close

Create Your Connected App

Learning Objectives

After completing this unit, you’ll be able to:
  • Describe the purpose of a connected app.
  • Identify the commands used to generate an X.509 certificate and key.

How the Salesforce CLI Facilitates CI

The Salesforce CLI makes it easy for you to manage the entire application development life cycle from the command line, including creating scripts that facilitate automation. However, you’ll need a way to manage the authorization process, because you’re not there to personally log in when your CI or build automation job runs. So, you’ll use the OAuth JSON Web Token (JWT) bearer flow that’s supported in the Salesforce CLI.

For a CI solution to work, you'll generate a private key for signing the JWT bearer token payload, and you'll create a connected app in the Dev Hub org that contains a certificate generated from that private key.

The JWT bearer flow supports the RSA SHA256 algorithm, which uses an uploaded certificate as the signing secret. This OAuth flow gives you the ability to authenticate using the CLI without having to interactively log in. This headless flow is perfect for automated builds and scripting. (A headless process is a process that runs without a user interface. While your head is resting comfortably on its pillow, your CI system uses the Salesforce CLI to do the work for you.) We’ll show you this handy CLI command after you generate the necessary X.509 certificate and key.

Got OpenSSL?

You’ll use the OpenSSL library to generate your own certificate. The files created during this step contain sensitive information that others can use to compromise your system. So it’s important to keep track of them in a safe place to use later. To make it easier to locate these files, create a folder in your file system that is outside of the project folder.

  1. Create a certificates folder outside of the project folder:
    cd ..
    mkdir certificates
  2. Run the following command in your local environment to see whether you already have OpenSSL installed:
    which openssl

    Did this command return a path that looked something like this?

    /usr/bin/openssl

  3. If the which openssl command doesn’t return a path, install OpenSSL.
    If you have... Install with...
    macOS Homebrew: brew install openssl
    Windows Windows complete package.exe installer
    Ubuntu Linux apt-get install openssl

Create a Self-Signed SSL Certificate and Private Key

Creating an SSL certificate requires a private key and a certificate signing request. You can generate these files with a few simple commands.

Important

Important

For security reasons, run these commands outside of the Git repo directory. That’s why we had you create a certificates folder. We don’t want you to inadvertently commit these files into the repo.

  1. Change directories to the certificates folder:
    cd certificates
  2. From within the certificates folder, generate an RSA private key:
    openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
  3. Create a key file from the server.pass.key file:
    openssl rsa -passin pass:x -in server.pass.key -out server.key
  4. Delete the server.pass.key:
    rm server.pass.key
  5. Request and generate the certificate:
    openssl req -new -key server.key -out server.csr
  6. Enter all requested information.
    1. Press Enter when prompted for the challenge password.

      The Certificate Authorities use this password to authenticate the certificate owner when they want to revoke their certificate. Because it’s a self-signed certificate, there’s no way to revoke it via CRL (Certificate Revocation List).

    2. Enter a period (.) to skip entering an optional company name.
  7. Generate the SSL certificate:
    openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt

    The self-signed SSL certificate is generated from the server.key private key and server.csr files.

    Look at the contents of your certificates folder:
    -rw-r--r-- 1 1322 May 3 14:03 server.crt
    -rw-r--r-- 1 1066 May 3 14:03 server.csr
    -rw-r--r-- 1 1675 May 3 14:02 server.key

    The server.crt file is your site certificate, suitable for use with the connected app along with the server.key private key. We’ll use these files soon. For now, keep them safe because they are secrets you want to ensure are kept private.

Create the Connected App

The next step is to create a connected app that includes the certificate we just created. A connected app integrates an application with Salesforce using APIs. Basically, for our purposes, it enables your headless process to connect to the Dev Hub and execute Salesforce CLI commands.

Log In to the Dev Hub

  1. Go back to the sfdx-travisci folder.
    cd ..
  2. Open your Dev Hub org.
    • If you already authorized the Dev Hub, open it:
      sfdx force:org:open -u DevHub
    • If you haven’t yet logged in to your Dev Hub org:
      sfdx force:auth:web:login -d -a DevHub

      Adding the -d flag sets this org as the default Dev Hub. To set an alias for the org, use the -a flag with an argument (something catchy like DevHub). Aliases are much easier to remember than the unique and unituitive usernames assigned to orgs.

  3. List your orgs:
    sfdx force:org:list
    The output of the list command looks something like this. Notice how this command verifies that you are connected to your Dev Hub, and that this Dev Hub org is the default.
    === Orgs
    
        ALIAS   USERNAME          ORG ID              CONNECTED STATUS
    ─── ─────── ────────────────  ──────────────────  ──────────────────
    (D) DevHub  user@dh0425.org   00DB0000000Ifd5MAC  Connected

Create the Connected App

  1. From Setup, enter App Manager in the Quick Find box, then select App Manager.
  2. Click New Connected App.
  3. Enter the connected app name and your email address:
    1. Connected App Name: sfdx travis ci
    2. Contact Email: <your email address>
  4. Select Enable OAuth Settings.
  5. Enter the callback URL:
    http://localhost:1717/OauthRedirect
  6. Select Use digital signatures.
  7. To upload your server.crt file, click Choose File.
  8. For OAuth scopes, add:
    • Access and manage your data (api)
    • Perform requests on your behalf at any time (refresh_token, offline_access)
    • Provide access to your data via the Web (web)

    New Connected App Setup page

  9. Click Save.
    Important

    Important

    Be sure to copy down the consumer key—you’ll use it later.

Edit Policies

After you’ve saved your connected app, edit the policies to enable the connected app to circumvent the manual login process.

  1. Click Manage.
  2. Click Edit Policies.
  3. In the OAuth policies section, for Permitted Users select Admin approved users are pre-authorized, then click OK.
  4. Click Save.

Create a Permission Set

Lastly, create a permission set and assign pre-authorized users for this connected app.

  1. From Setup, enter Permission in the Quick Find box, then select Permission Sets.
  2. Click New.
  3. For the Label, enter: sfdx travis ci
  4. Click Save.
  5. Click sfdx travis ci | Manage Assignments | Add Assignments.
  6. Select the checkbox next to your Dev Hub username, then click Assign | Done.
  7. Go back to your connected app.
    1. From Setup, enter App Manager in the Quick Find box, then select App Manager.
    2. Next to sfdx travis ci, click the list item drop-down arrow (list item dropdown), then select Manage.
    3. In the Permission Sets section, click Manage Permission Sets.
    4. Select the checkbox next to sfdx travis ci, then click Save.

Test the JWT Auth Flow

To test the JWT auth flow you’ll use some of the information that we asked you to save previously. We’ll use the consumer key that was generated when you created the connected app (CONSUMER_KEY), the absolute path to the location where you generated your OpenSSL server.key file (JWT_KEY_FILE) and the username for the Dev Hub (HUB_USERNAME).

  1. On the command line, create these three session-based environment variables:
    export CONSUMER_KEY=<connected app consumer key>
    export JWT_KEY_FILE=<example: /users/yourname/certificates/server.key>
    export HUB_USERNAME=<your Dev Hub username>

    The file path to the JWT key file

    These environment variables facilitate running the JWT auth command.

  2. Enter this command as-is on a single line:
    sfdx force:auth:jwt:grant --clientid ${CONSUMER_KEY} --username ${HUB_USERNAME} \
    --jwtkeyfile ${JWT_KEY_FILE} --setdefaultdevhubusername

This command logs in to the Dev Hub using only the consumer key (client ID), the username, and the JWT key file. And best of all, it doesn’t require you to interactively log in, which is important when you want your scripts to run automatically.

Congratulations, you’ve created your connected app!

retargeting