Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Enable Dev Hub Features in Your Org
Project Setup
Authorization
Authorize an Org Using the Web Server Flow
Authorize an Org Using the JWT Bearer Flow
Authorize a Scratch Org
Create a Private Key and Self-Signed Digital Certificate
Create a Connected App in Your Org
Use the Default Connected App Securely
Use an Existing Access Token instead of Authorizing
Authorization Information for an Org
Log Out of an Org
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Development
Build and Release Your App
First-Generation Managed Packages
Second-Generation Managed Packages
Partner Licensing Platform (Developer Preview)
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 Bearer Flow

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

The JWT bearer authorization 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. With this flow, explicit user interaction isn’t required. However, this flow does require prior approval of the client app. See OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration.

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 bearer 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 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 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 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 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.

Authorize a Scratch Org

If you configured your Dev Hub to support the OAuth 2.0 JWT bearer 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 bearer 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, click Manage Consumer Details, then verify your identity.
    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. Run the 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 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.