Create a Salesforce client secret - AWS Secrets Manager
Step 1: Create an External Client App and enable OAuthStep 2: Create the managed external secret and enable rotationStep 3: Test the rotated credentialsStep 4: Clean up resourcesNext steps
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Create a Salesforce client secret

In this tutorial, you create a Salesforce client secret and store it in AWS Secrets Manager as a managed external secret, turn on managed rotation, and then test the rotated credentials by exchanging them for an access token. This tutorial takes approximately 20–30 minutes to complete.

This tutorial uses AWS services that might incur charges to your AWS account, including charges for the secret you store in Secrets Manager and, if you choose to use one, a customer managed key. For more information, see Pricing.

Note

This tutorial uses the SalesforceClientSecret secret type as an example. Other managed external secrets types follow a similar flow. You create the secret using the format the integration partner defines, turn on managed rotation, and then use the rotated credentials. For the list of onboarded partners and their required secret formats, see Integration Partners.

Before you begin this tutorial, make sure you have the following.

  • A Salesforce account (developer or otherwise) that allows you to create External Client Apps (ECAs).

  • Administrative permissions to your AWS account. In a production setting, it is a best practice to use different roles for different tasks. For example, a role that manages secrets in your organization would create the secret, and a separate role would use the secret at runtime. For the tutorial steps, we recommend you continue using the same identity. For information about how to set up permissions in a production environment, see Authentication and access control for AWS Secrets Manager.

Step 1: Create an External Client App and enable OAuth

The first step is to create an External Client App (ECA) in Salesforce and configure it for OAuth so that Secrets Manager can rotate the client secret. For the full Salesforce procedure, see Set up authorization with an External Client App in the Salesforce documentation.

As you set up the ECA, make sure you configure the following:

  • At the org level, enable Allow access to External Client App consumer secrets via REST API. This setting allows Secrets Manager to retrieve and rotate the consumer secret through the Salesforce REST API.

  • On the ECA, enable the OAuth scope Manage user data via APIs (api).

  • On the ECA, enable Enable Client Credentials Flow.

  • On the ECA, enable Enable Token Exchange Flow and Require secret for Token Exchange Flow.

After you create the ECA, gather the values you need to store in the secret in the next step:

  • The consumer key (client ID) and consumer secret (client secret) from the ECA Manager OAuth settings.

  • Your Salesforce My Domain base URL, for example https://MyDomainName.my.salesforce.com.

  • The app ID and consumer ID for the ECA. These correspond to the external_client_app_identifier and consumer_id fields in the Salesforce documentation. To learn how to retrieve these values, see Stage OAuth Credentials in the Salesforce documentation.

For a description of each field required in the secret, see Salesforce Client Secret.

Step 2: Create the managed external secret and enable rotation

Next, you store the Salesforce client secret in Secrets Manager as a managed external secret and turn on managed rotation. With managed rotation, you don't create or maintain a Lambda rotation function. Secrets Manager rotates the secret for you.

To create the secret and turn on rotation (console)

  1. Open the Secrets Manager console at https://eusc-de-east-1.console.amazonaws-eusc.eu/secretsmanager/.

  2. Choose Store a new secret.

  3. On the Choose secret type page, do the following:

    1. For Secret type, choose the Salesforce client secret managed external secret type (SalesforceClientSecret).

    2. Enter the secret value fields for the Salesforce client secret: the consumer key, consumer secret, base URI, app ID, and consumer ID. For a description of each field, see Salesforce Client Secret.

    3. For Encryption key, choose aws/secretsmanager to use the AWS managed key for Secrets Manager. There is no cost for using this key. You can also use your own customer managed key. For information about the costs of using a customer managed key, see Pricing.

    4. Choose Next.

  4. On the Configure secret page, enter a descriptive Secret name and Description, and then choose Next.

  5. On the Configure rotation page, do the following. For managed external secrets, rotation is enabled by default during secret creation.

    1. Confirm that Automatic rotation is turned on.

    2. Under Rotation metadata, for API version (apiVersion), enter your Salesforce organization's API version. This field is required. It must be in the format vXX.X, where X is a numeric character, and must be at least v65.0. If you want Secrets Manager to rotate the secret using a separate set of administrative credentials, also provide the admin secret ARN. For a description of each metadata field, see Salesforce Client Secret.

    3. In Service permissions for secret rotation, choose Create a new role to automatically create an IAM role with the permissions Secrets Manager needs to rotate the secret. By default, permissions are scoped to the integration partner in the AWS Region where the secret is created. For more information, see Security and permissions.

    4. Under Rotation schedule, enter your schedule in UTC time zone, for example rotate automatically every 30 days.

    5. Choose Next.

  6. On the Review page, review your secret details, and then choose Store.

For more ways to configure rotation for a managed external secret, including the AWS AWS CLI, see Rotate Secrets Manager managed external secrets.

Step 3: Test the rotated credentials

The last step is to confirm that the rotated credentials work by retrieving the secret value and exchanging the credentials for a Salesforce access token.

To retrieve the secret value (console)

  1. Open the Secrets Manager console at https://eusc-de-east-1.console.amazonaws-eusc.eu/secretsmanager/.

  2. On the Secrets page, choose your secret.

  3. On the Secret details page, scroll down and choose Retrieve secret value. Note the current consumerKey and consumerSecret values.

Note

Confirm that the consumerKey and consumerSecret values have actually changed from the values you originally stored. If they haven't changed, wait a couple of minutes and check again. If they still haven't changed, check AWS CloudTrail for any RotationFailed events for the secret, which include details about why rotation failed. For more information, see My managed external secret is not rotating.

Next, use the retrieved credentials to request an access token from Salesforce. Replace MyDomainName with your Salesforce My Domain name, and replace consumerKey and consumerSecret with the values you retrieved.

curl -X POST "https://MyDomainName.my.salesforce.com/services/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=consumerKey" \
  -d "client_secret=consumerSecret"

If the credentials are valid, Salesforce returns a JSON response that contains an access_token. Receiving an access token confirms that the rotated credentials work.

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. See Mitigate the risks of using the AWS CLI to store your AWS Secrets Manager secrets.

Step 4: Clean up resources

To avoid incurring ongoing charges, delete the resources you created in this tutorial when you no longer need them: the secret and the IAM rotation role that Secrets Manager created. Deleting the secret also stops automatic rotation.

To delete the secret (console)

  1. Open the Secrets Manager console at https://eusc-de-east-1.console.amazonaws-eusc.eu/secretsmanager/.

  2. On the Secrets page, choose your secret.

  3. In the Secret details section, choose Actions, and then choose Delete secret.

  4. In the Disable secret and schedule deletion dialog box, enter a waiting period, and then choose Schedule deletion. Secrets Manager makes the secret inaccessible immediately and schedules it for deletion after the recovery window. For more information, see Delete an AWS Secrets Manager secret.

To delete the rotation role (console)

  1. Open the IAM console at https://console.aws.amazon.com/iam/, and then choose Roles.

  2. Find the role that Secrets Manager created for rotation, select it, and then choose Delete. For more information, see Deleting roles or instance profiles in the IAM User Guide.

Next steps