Salesforce Platform: Migrate from OAuth Username-Password to Client Credentials Flow

Step One: Update the Developer-Side Settings on the Connected App

Log in to the org that hosts your connected app. From Setup, in the Quick Find box, enter App, and then select App Manager. On the dropdown menu next to your app, select Edit.You see a page that looks like this:

Select  Enable Client Credentials Flow, and accept the alert that you get:

You do this step only once.. As noted in the message that appears when you save, it can take a few minutes for the change to propagate before you can start Step Two.

Step Two: Update the Manage-Side Settings on the Connected App

Complete this step for every org where you’re using the OAuth username-password flow. For every set of username-password credentials that your client has, you must change the manage-side policies in the corresponding org.

Log in to that org as an adminFrom Setup, in the Quick Find box, enter App, and then select App Manager. On the dropdown menu next to your app, select Manage, and then click Edit Policies. You see a page that looks like this:

In the Client Credentials Flow section, use the lookup field for Run As to look up the user in the org whose username you were using with the OAuth username-password flow.

For example, if your client was previously using the OAuth username-password flow with the username test@example1.com, locate the user in the org with the username test@example1.com.

Select the user and click Save.

Repeat these steps for every org where the client has a set of username and password credentials

Step Three: Update the Client Code

To update the client’s callout in the current OAuth username-password flow to instead use the OAuth client credentials flow, update the request body. If applicable, change the host domain too.

For example, where your client is currently making a POST request similar to this one:

POST /services/oauth2/token HTTP/1.1

Host: foo.my.salesforce.com

  

grant_type=password&

client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&

client_secret=1955279925675241571&

username=testuser@salesforce.com&

password=mypassword

Instead make a POST request like this one:

POST /services/oauth2/token HTTP/1.1

Host: foo.my.salesforce.com

  

grant_type=client_credentials&

client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&

client_secret=1955279925675241571

The response format is directly comparable between the flows.

The client credentials flow doesn’t support calls to login.salesforce.com or test.salesforce.com. If you’re using either of these host domains, for every set of username-password credentials that your client has, update your code to use the correct domain for the corresponding org. Instead of login.salesforce.com, switch to the org’s My Domain login URL, such as  https://MyCompany.my.salesforce.com. Instead of test.salesforce.com, use the sandbox’s My Domain login URL, such as https://MyDomainName--SandboxName.sandbox.my.salesforce.com. 

Note: We recommend that you pass all data in the POST body. In particular, do not pass the client secret in the query string of the POST request. Secrets must always be passed as part of the POST body. Passing sensitive information in the query string can leak that information to network intermediaries and other services.

Further documentation on these flows are available here (for username-password) and here (for client credentials).

Note: The resulting access tokens differ slightly between the flows. The token returned from the client credentials flow should be more compliant with OAuth standards.