Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Salesforce CLI Configuration and Tips
Project Setup
Authorization
Authorize an Org Using the Web-Based Flow
Authorize an Org Using the JWT-Based Flow
Authorize a Scratch Org
Create a Private Key and Self-Signed Digital Certificate
Create a Connected App
Use an Existing Access Token Instead of Authorizing
Authorization Information for an Org
Log Out of an Org
Metadata Coverage
Scratch Orgs
Sandboxes
Development
Build and Release Your App
First-Generation Managed Packages
Second-Generation Managed Packages
Unlocked Packages
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Authorize an Org Using the JWT-Based Flow

Continuous integration (CI) environments are fully automated and don’t support the human interactivity of a web-based flow. In these environments, you must use the JSON web tokens (JWT) to authorize an org.

The JWT-based authorization flow requires first generating a digital certificate and creating a connected app. You execute these tasks only once. After that, you can authorize the org in a script that runs in your CI environment.

For information about using JWT-based authorization with Travis CI, see the Continuous Integration Using Salesforce DX Trailhead module.

If your Dev Hub org is configured with high assurance (stepped up) authentication, Salesforce prompts the user to verify identity. This verification process means that you can’t use the JWT flow and Salesforce CLI for headless authentication.

Important

  1. If you do not have your own private key and digital certificate, use OpenSSL to create the key and a self-signed certificate.
    It is assumed in this task that your private key file is named server.key and your digital certificate is named server.crt.
  2. Create a connected app, and configure it for Salesforce DX.
    This task includes uploading the server.crt digital certificate file. Make note of the consumer key when you save the connected app because you need it later.
  3. If the org you are authorizing is not hosted on https://login.salesforce.com, update your project configuration file (sfdx-project.json).
    Set the sfdcLoginUrl parameter to the login URL. Examples of other login URLs are your custom subdomain or https://test.salesforce.com for sandboxes. For example:
    1"sfdcLoginUrl": "https://test.salesforce.com"

    If you specify a My Domain subdomain for the login URL, use the version that ends in my.salesforce.com instead of the URL you see in Lightning Experience (.lightning.force.com). To verify the valid My Domain URL, from Setup, enter My Domain in the Quick Find box, then select My Domain.

    Important

    Alternatively, you can use the --instanceurl parameter of the force:auth:jwt:grant command to specify the URL. This value overrides the login URL you specified in the sfdx-project.json file. See the next step for an example.

  4. Run the force:auth:jwt:grant CLI command.
    Specify the client identifier from your connected app (also called the consumer key), the path to the private key file (server.key), and the JWT authentication username. When you authorize a Dev Hub org, set it as the default with the --setdefaultdevhubusername parameter. For example:
    1sfdx force:auth:jwt:grant --clientid 04580y4051234051 \
2--jwtkeyfile /Users/jdoe/JWT/server.key --username jdoe@acdxgs0hub.org \
3--setdefaultdevhubusername --setalias my-hub-org
    This example shows how to use the --instanceurl parameter to specify an org hosted on https://test.salesforce.com rather than the default https://login.salesforce.com:
    1sfdx force:auth:jwt:grant --clientid 04580y4051234051 \
2--jwtkeyfile /Users/jdoe/JWT/server.key --username jdoe@acdxgs0hub.org \
3--instanceurl https://test.salesforce.com

    You can authorize a scratch org using the same client identifier (consumer key) and private key file that you used to authorize its associated Dev Hub org. Set the --instanceurl parameter to https://test.salesforce.com and the --username parameter to the administrator user displayed after you create the scratch org with

Authorize a Scratch Org

If you configured your Dev Hub to support the JWT-based authorization flow, you can use the same digital certificate and private key to authorize an associated scratch org. This method is useful for continuous integration (CI) systems that must authorize scratch orgs after creating them, but don’t have access to the scratch org’s access token.
It is assumed in this task that:
  • You previously authorized your Dev Hub org using the JWT-based flow.
  • The private key file you used when authorizing your Dev Hub org is accessible and located in /Users/jdoe/JWT/server.key.
  • You’ve created a scratch org and have its administration user’s username, such as test-wvkpnfm5z113@example.com.
  1. Copy the consumer key from the connected app that you created in your Dev Hub org.
    1. Log in to your Dev Hub org.
    2. From Setup, enter App Manager in the Quick Find box to get to the Lightning Experience App Manager.
    3. Locate the connected app in the apps list, then click Action dropdown, and select View.
    4. In the API (Enable OAuth Settings) section, copy the Consumer Key to your clipboard. The consumer key is a long string of numbers, letters, and characters, such as 3MVG9szVa2Rx_sqBb444p50Yj (example shortened for clarity.)
  2. Run the force:auth:jwt:grant CLI command. The --clientid and --jwtkeyfile parameter values are the same as when you ran the command to authorize a Dev Hub org. Set --username to the scratch org’s admin username and set --instanceurl to https://test.salesforce.com. For example: 
    1sfdx force:auth:jwt:grant --clientid 3MVG9szVa2Rx_sqBb444p50Yj \
2--jwtkeyfile /Users/jdoe/JWT/server.key --username test-wvkpnfm5z113@example.com \
3--instanceurl https://test.salesforce.com
    If you get an error that the user is not approved, it means that the scratch org information has not yet been replicated to https://test.salesforce.com. Wait a short time and try again.