Salesforce DX Developer Guide

How Salesforce Developer Experience (DX) Tooling Changes the Way You Work
Provide Developers Access to Salesforce DX Tools
Project Setup
Authorization
Authorize an Org Using a Browser
Authorize an Org Using the JWT Flow
Authorize a Scratch Org Using the JWT Flow
Create a Private Key and Self-Signed Digital Certificate
Create an External Client App in Your Org
Create a Connected App in Your Org
Use the Default Connected App Securely
Use an Existing Access Token
Authorize an Org Using Its SFDX Authorization URL
Authorization Information for an Org
Log Out of an Org
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Work with Data
Salesforce DX MCP Server and Tools (Beta)
Development
Build and Release Your App
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 Flow

Use the JWT flow to authorize an org in continuous integration (CI) environments, which are fully automated and don’t support the human interactivity of logging into a browser.
The JWT flow requires a digital certificate, also called a digital signature, to sign the JWT request. You can use your own certificate or create a self-signed certificate using OpenSSL.

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

Important

  1. If you don’t have your own private key and digital certificate, you can use OpenSSL to create the key and a self-signed certificate.
    It’s assumed in this task that your private key file is named server.key and your digital certificate is named server.crt.
  2. Create an external client 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 finish configuring the external client app because you need it later.

    If you're authoring a Dev Hub org and plan to create scratch orgs or sandboxes with the org create scratch|sandbox commands, then you must create a connected app instead of an external client app.

    Important

  3. Open a terminal (macOS and Linux) or command prompt (Windows).
  4. Run the org login jwt CLI command. We recommend using the --alias flag to make it easy to refer to the org later.
    Specify the consumer key from your external client app or connected app with the --client-id flag, the path to the private JWT key file (server.key), and the username for your org. For example:
    1sf org login jwt --client-id 04580y4051234051 --jwt-key-file /Users/jdoe/JWT/server.key --username jdoe@myorg.com --alias my-hub-org
    Use the --set-default flag if you want the org to be the default for commands that accept the --target-org flag. If you’re authorizing a Dev Hub org, use the --set-default-dev-hub flag instead. See the org login jwt command for examples.
You can authorize a scratch org using the same consumer key and private key file that you used to authorize its associated Dev Hub org. See Authorize a Scratch Org Using the JWT Flow

If the URL that you use to log in to your org isn’t the default (login.salesforce.com), update your project configuration file (sfdx-project.json). Set the sfdcLoginUrl option to your enhanced My Domain login URL. For example:

1"sfdcLoginUrl" : "https://MyDomainName.my.salesforce.com"

This example is for a sandbox.

1"sfdcLoginUrl" : "https://MyDomainName--SandboxName.sandbox.my.salesforce.com"

Alternatively, you can use the --instance-url flag of the org login jwt command to specify the URL. This value overrides the login URL you specified in the sfdx-project.json file. For example:

1sf org login jwt --client-id 04580y4051234051 --jwt-key-file /Users/jdoe/JWT/server.key --username jdoe@myorg.com --alias my-hub-org --instance-url https://mydomain--mysandbox.sandbox.my.salesforce.com

We recommend that you use your My Domain login URL, because it isn’t affected by org migrations that change your org’s Salesforce instance. Be sure you 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.

Note

Authorize a Scratch Org Using the JWT Flow

If you authorized your Dev Hub org using the org login jwt command, 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.

Before you begin, we assume that:

  • You previously authorized your Dev Hub org with the org login jwt command.
  • The private key file you used when authorizing your Dev Hub org is accessible and 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.
  • You know the scratch org’s instance URL. If you don’t know it, you can query your Dev Hub org. For example:
    1sf data query --target-org my-dev-hub --query "SELECT SignupUsername,LoginUrl FROM ScratchOrgInfo WHERE SignupUsername='test-wvkpnfm5z113@example.com'"
  1. Copy the consumer key from the external client app (or 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 external client app (or connected app) in the apps list, then click the dropdown menu on the right side, and select View.
    4. In the API (Enable OAuth Settings) section, click Manage Consumer Details
      If prompted, verify your identity by entering the verification code that was automatically sent to your email address.
    5. 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. Open a terminal (macOS and Linux) or command prompt (Windows).
  3. Run the org login jwt CLI command. The --client-id and --jwt-key-file flag 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 --instance-url to the scratch org’s instance URL, such as https://energy-enterprise-2539-dev-ed.scratch.my.salesforce.com. For example: 
    1sf org login jwt --client-id 3MVG9szVa2Rx_sqBb444p50Yj \
2--jwt-key-file /Users/jdoe/JWT/server.key --username test-wvkpnfm5z113@example.com \
3--instance-url https://energy-enterprise-2539-dev-ed.scratch.my.salesforce.com
    If you get an error that the user isn’t approved, it means that the scratch org information hasn’t yet been replicated. Wait a short time and try again.

If your scratch org is running on Hyperforce and the --username value of org login jwt is a non-admin scratch org user, you can’t use your Dev Hub’s digital certificate and private key. To authorize the scratch org in this scenario, follow the standard JWT flow steps.

Note