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

Create a Connected App in Your Org

Salesforce CLI requires a connected app in the org that you're authorizing. A connected app is a framework that enables an external application, in this case Salesforce CLI, to integrate with Salesforce using APIs and standard protocols, such as OAuth. We provide a default connected app when you use the OAuth 2.0 web server flow to authorize an org. For extra security, create your own connected app in your org and configure it with the settings of your choice. You're required to create a connected app when using the OAuth 2.0 JWT bearer authorization flow.

Create a connected app using Setup in your 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.

The web server authorization flow implements the OAuth 2.0 authorization code grant type. With this flow, the server hosting the web app must be able to protect the connected app’s identity, defined by the client ID and client secret. See OAuth 2.0 Web Server Flow for Web App Integration.

The steps marked JWT only are required only if you’re creating a connected app for the JWT bearer authorization flow. They're optional for the web server authorization flow.

Note

To learn more about connected apps, see Connected Apps.

  1. Log in to your org.
  2. From Setup, enter App Manager in the Quick Find box, then select App Manager.
  3. In the top-right corner, click New Connected App.
  4. Update the basic information as needed, such as the connected app name and your email address.
  5. Select Enable OAuth Settings.
  6. For the callback URL, enter http://localhost:1717/OauthRedirect.

    If port 1717 (the default) is already in use on your local machine, specify an available one instead. Make sure to also update your sfdx-project.json file by setting the oauthLocalPort property to the new port. For example, if you set the callback URL to http://localhost:1919/OauthRedirect:

    1"oauthLocalPort" : "1919"
  7. (JWT only) Select Use digital signatures.
  8. (JWT only) Click Choose File and upload the server.crt file that contains your digital certificate.
  9. Add these OAuth scopes:
    • Manage user data via APIs (api)
    • Manage user data via Web browsers (web)
    • Perform requests at any time (refresh_token, offline_access)
  10. Click Save.

    Make note of the consumer key because you need it later when you run a auth command.

    Important

  11. Click Manage.
  12. Click Edit Policies.
  13. In the OAuth Policies section, for the Refresh Token Policy field, click Expire refresh token after: and enter 90 days or less.
    Setting a maximum of 90 days for the refresh token expiration is a security best practice. To continue running CLI commands against an org whose refresh tokens have expired, reauthorize it with the auth:web:login or auth:jwt:grant command.
  14. In the Session Policies section, set Timeout Value to 15 minutes.
    Setting a timeout for access tokens is a security best practice. Salesforce CLI automatically handles an expired access token by referring to the refresh token.
  15. (JWT only) In the OAuth Policies section, select Admin approved users are pre-authorized for permitted users, and click OK.
  16. (JWT only) Click Save.
  17. (JWT only) Click Manage Profiles and then click Manage Permission Sets. Select the profiles and permission sets that are pre-authorized to use this connected app. Create permission sets if necessary.