IAM Roles Anywhere integration guide for installing AWS Partner CRM Connector

Since the launch of AWS Partner Customer Relationship Management (CRM) Connector (referred to as the connector in this article), AWS Partner Network (APN) Partners have used it to share opportunities with and receive referrals from Amazon Web Services (AWS) in their Salesforce CRM platform. These partners have provided feedback that they want a more secure user onboarding experience that adheres to their organization security protocols. Specifically, they are concerned about hardcoding AWS Identity and Access Management (IAM) credentials into Salesforce when configuring their AWS Partner CRM Integration using the connector.

In this article, we present a solution that lets AWS Partner CRM Connector users authenticate with Salesforce via their AWS Partner CRM integration environment using AWS IAM Roles Anywhere. Using IAM Roles Anywhere, servers, applications and other workloads outside of AWS can use X.509 digital certificates to obtain temporary AWS credentials to access AWS resources, eliminating the need to hardcode credentials into Salesforce.

Overview

This article provides the following major steps for configuring IAM Roles Anywhere in your AWS account and then integrating it into Salesforce.

• Step 1: Configure IAM Roles Anywhere via the AWS Management Console, including setting up resources in your AWS account and downloading the private certificate used to request temporary credentials.
• Step 2: Create and submit an ACE CRM onboarding request and then add permissions to the IAM role that provides access to the Amazon S3 bucket used for the ACE CRM integration.
• Step 3: Configure IAM Roles Anywhere for Salesforce, including enabling the identity provider, creating a Java KeyStore (JKS) file for storing certificate information, creating a named credential, and then testing the connector integration.

The following image shows how your environment will look after completing these steps and configuring integration settings for the connector in Salesforce.

Prequisites

Solution walkthrough

Step 1: Configure IAM Roles Anywhere via the AWS Management Console

In this step, you download and launch a CloudFormation template that automatically adds the following resources to an AWS account in the us-west-2 Region.

• AWS Private Certificate Authority and private certificate that includes a custom passphrase and fully qualified domain name.
• An IAM Roles Anywhere trust anchor, used to establish trust between your CA and AWS IAM Roles Anywhere.
• An IAM role, required by the IAM Roles Anywhere service principal. The provided CloudFormation template creates the role with default sts:GetCallerIdentity, sts:AssumeRole, and sts:GetSessionToken permissions, but you will append additional ones in step 2.
• IAM Roles Anywhere profile that specifies the roles that IAM Roles Anywhere assumes and what your workloads can do with the temporary credentials.

Note: If you want to use your own CA-signed certificate, do these steps instead:

1. Create an IAM Roles Anywhere trust anchor by uploading the certificate body from the external CA.
2. Configure an IAM role and IAM Roles Anywhere profile. For instructions, see Configure roles.
3. Import an external CA-signed certificate into Salesforce. For instructions, see Generate a salesforce compatible JKS from PFX or P12.
4. Create an external credential, and then create a principal for it. For instructions, see Create or Edit an AWS Signature v4 External Credential.
5. Create a named credential in Salesforce. To learn more, see Authentication Protocols for Named Credentials.

For best practices, see Set up AWS Private Certificate Authority to issue certificates for use with IAM Roles Anywhere.

Step 1-A: Configure resources in your AWS account

1. Download the CloudFormation template (IAMAnywhere_Setup.yaml) to your local environment.
2. Log in to the AWS CloudFormation console in the us-west-2 Region (required). You may need to authenticate with the AWS Management Console first.
   Note: The us-west-2 Region is where AWS provisions the CRM integration bucket.
3. Choose Create Stack on the Stacks page.
4. Choose Upload a template file, and specify the location where you downloaded the CloudFormation template. Choose Next.
5. On the Specify stack details page, provide a stack name and other required details. Choose Next.

   

6. Configure tag keys and values, retention, rollback policy, and other stack options for all resources. Choose Next.
7. Select I acknowledge that AWS CloudFormation might create IAM resources with custom names, and then choose Submit to create the stack.

   

8. After the stack creation process reaches the COMPLETE state, navigate to the Outputs tab of the stack and make note of the Amazon Resource Names (ARNs) of the role, profile, and trust anchor resources.

   

You can see a list of your new resources in the Resources tab.

Step 1-B: Download the private certificate

1. Still logged in to the AWS Management Console, navigate to the AWS Certificate Manager.
2. Choose Certificate ID to open the certificate created by CloudFormation template.

   

3. Choose Export to download the certificate.
4. Provide a passphrase. and make note of it. The passphrase is required in later steps when validating access from your local environment and also when converting the certificate to a Java KeyStore (JKS) file that you will upload to Salesforce.
5. Choose I understand that ACM will charge my account for exporting this certificate if it has not been previously exported. This charge will reset the period for certificate renewal (13 months).  A one-time fee is required for each private certificate issued by AWS Private CA. This fee is charged to the AWS account from which the certificate was incurred. For more information, see AWS Private CA Pricing.

   

6. Choose Generate PEM Encoding to generate the certificate body and certificate private key. Download the certificate body to a file named certifcate.txt and the certificate private key to a file named private_key.txt.
7. In your local directory, rename certifcate.txt to certificate.pem and private_key.txt to private_key.pem. Move the files to the folder of your choice.
8. In the same folder as the new files, download the AWS credential helper tool provided by AWS IAM Roles Anywhere. Use the download option that’s appropriate for your local machine platform.

Step 1-C: Use certificate to request temporary credentials

1. Retrieve the ARNs of the IAM role, profile, and trust anchor resources that you created earlier in your AWS account. If needed, you can access the ARNs by logging in to the AWS CloudFormation console, launching the CloudFormation template in the us-west-2 Region, selecting the stack, and navigating to the Outputs tab.
2. Run the following commands from your local machine terminal to request temporary credentials and test your IAM Roles Anywhere configuration. For information, see Environment variables to configure the AWS CLI. Follow security best practices and root user best practices on your local machine to safeguard AWS account and other sensitive personal information.

   //Decrypt the Private key using the password you had set
   openssl rsa -in private_key.pem -out decrypted_private_key.pem
   
   //Change permissions of the tool
   chmod +x aws_signing_helper
   
   //Command to fetch temporary credentials. Modify the ARN of trust-anchor, profile and role and certificate path with decrypted private key in the below command
   ./aws_signing_helper credential-process \
         --certificate /path/to/certificate \
         --private-key /path/to/decrypted-private-key \
         --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \
         --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \
         --role-arn arn:aws:iam::account:role/role-name-with-path
         
   // Example for the above command
   ./aws_signing_helper credential-process --certificate certificate.pem --private-key decrypted_private_key.pem --trust-anchor-arn arn:aws:rolesanywhere:us-east-1:1234678910:trust-anchor/527c3297-e0b3-4cea-bb17-275f2dcf8af9 --profile-arn arn:aws:rolesanywhere:us-east-1:1234678910:profile/00978968-c5b6-4446-86d7-c6ecf6640e2a --role-arn arn:aws:iam::1234678910:role/marketplacecarole
   
   //Test your credentials, copy and configure your aws credentials using aws configure command 
   aws sts get-caller-identity

Now you can use a combination of the AccessKeyId, SecretAccessKey, and SessionToken data types to make AWS API calls. Note that temporary credentials must be changed at various intervals.

You have now successfully configured AWS IAM Roles Anywhere in your AWS account and validated it from your local environment.

Step 2: Create an ACE CRM onboarding request and update the IAM role

In this step, you create and submit an ACE CRM onboarding request using the IAM role that you created in the previous step. You also add permissions to the IAM role that provide access to the Amazon S3 bucket used for the ACE CRM integration, and finally, you amend or add the policy from the request back to the IAM role.

Step 2-A: Create and submit an ACE CRM onboarding request

1. Retrieve the ARNs of the resources that you created in your AWS account (see Step 1). You can access ARNs by logging in to the AWS CloudFormation console, launching the CloudFormation template in the us-west-2 Region, selecting the stack, and navigating to the Outputs tab.
2. Submit the onboarding request on Partner Central using the ARN of the IAM role.
3. Wait for the provisioning request to move to the sandbox.
4. From the request, download the IAM policy to the sandbox and save it to your local machine.

   

Step 2-B: Add permissions to the IAM role

1. Log in to the AWS IAM console.
2. Choose the IAM role that you created using the CloudFormation template in Step 1. Note: You can also access the IAM role by logging in to the CloudFormation console, launching the CloudFormation template in the us-west-2 Region, selecting the stack, and navigating to the Resources tab.
3. In the Permissions tab of the role, choose Add Permissions > Create Inline policy.
4. Switch to the JSON view and swap the policy with the new policy that you saved to your local machine earlier. Choose Next.
5. Provide a name for the IAM policy, for example ACE-CRM-INT-Sandbox-Policy.
6. Choose Create Policy.

For best practices about adding an IAM policy to a role, see Validating IAM policies.

Step 3: Configure IAM Roles Anywhere for Salesforce

In this step, you configure IAM Roles Anywhere in your Salesforce account so that the AWS Partner CRM Connector application can access your AWS account and request temporary credentials.

Prerequisites

• You must have an installation of Salesforce Spring 2023 release or later (available with instance 242 and higher).
• Completion of steps 1 and 2 earlier in this article.

(Optional) Step 3-A: Create a self-signed certificate in Salesforce

If your Salesforce instance is new, you must enable an identity provider on the instance. Otherwise, you can skip this step. For more information, see Identity Providers and Service Providers in the Salesforce documentation.

1. From the Setup tab in Salesforce, enter Certificate & Key Management in the search field.
2. Choose Create Self-Signed Certificate.

   

3. Provide a label and unique name for the certificate, and choose Save.

   

Your certificate is now successfully created.

(Optional) Step 3-B: Enable the identity provider in Salesforce

1. From the Setup tab in Salesforce, enter Identity Provider in the search field.
2. Choose Enable Identity Provider, and assign the self-signed certificate to the new identity provider.

   

3. Select SampleCertificate in the field, and choose Save.

   

Note: For details about a known issue with importing the Java keystore (JKS) when the identity provider has not yet been enabled, see Issue with importing keystore into Salesforce.

Step 3-C: Convert and upload the private key and certificate files as a .jfk file

In this step, you create a Java KeyStore (JKS) file from the certificate.pem and private_key.pem files that you downloaded from your private certificate in your AWS account.

1. 1. To generate the PKCS#12 certificate:
      1. Open the terminal on your local machine, and navigate to the folder where you stored the certificate.pem and private_key.pem files.
      2. Run the following command:

         openssl pkcs12 -export -in {private certificate pem file} -inkey {private key pem file} -certfile {private certificate pem file} -out {output .p12 file name}
         
         Eg:
         openssl pkcs12 -export -in certificate.pem -inkey private_key.pem -certfile certificate.pem -out keystore.p12
         

         Note: After entering your private key decryption passphrase, you will set a new passphrase for the PKCS#12 file. Make note of the new passphrase.

         

   2. To convert the PKCS#12 certificate file to a JKS file, run the following command:

      keytool -importkeystore -srckeystore {.p12 file} -srcstoretype pkcs12 -destkeystore {output .jks file name}-deststoretype JKS
      
      Eg:
      keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12 -destkeystore outputfile.jks -deststoretype JKS

      Note: After entering your key decryption passphrase, set a new passphrase for the .jks file.

      

   3. To update the alias of the certificates within the .jks file, run the following commands. According to Salesforce guidelines, the name must begin with a letter and use only alphanumeric characters and underscores. The name cannot end with an underscore or have two consecutive underscores.

      //Check the alias assigned to .jks file
      
      keytool -list -v -keystore outputfile.jks
      
      //In order to successfully use "Import from Keystore" feature available at "Certificate and Key Management", the 'alias' of the certificates within .JKS file must meet following criteria:
      "*The name must begin with a letter and use only alphanumeric characters and underscores. The name cannot end with an underscore or have two consecutive underscores.*"
      
      //Update the alias
      
      keytool -keystore outputfile.jks -changealias -alias 1 -destalias IAMRA
      
      //Verify alias update
      
      keytool -list -v -keystore outputfile.jks

      

   4. To upload the JKS to Salesforce:
      1. On the Certificate and Key Management page, choose Import from Key store.

         

      2. Add the outputfile.jks file, and input the key-store password that you created earlier.

         

Step 3-D: Create the external named credentials

In this step, you configure a named credential in Salesforce to use the IAM role that you created in Step 1.

The named credential is used for authenticating and managing API callouts to external services within Salesforce, to a specific endpoint URL. Initially, you point it to AWS Security Token Service (AWS STS), a web service used to request temporary credentials. Then, you point it to the Amazon S3 service URL. Salesforce named credentials support two variants of the AWS Signature Version 4 authentication protocol—IAM User (identified by access key) and Roles Anywhere.

As a prerequisite for creating the named credential that uses your IAM Roles Anywhere role, you must first configure an external credential to provide the required authentication configuration via IAM Roles Anywhere. For more information, see Create or Edit an AWS Signature v4 External Credential. You also configure a principal that uses the permissions of the IAM role that you configured in Step 1.

For more information about Salesforce named credentials, see Authentication Protocols for Named Credentials and Use AWS Roles Anywhere with Named Credentials.

Create the external credential and a principal

1. 1. From the Setup menu in the search field, enter Named Credentials, then choose Named Credentials.
   2. Change to the External Credentials tab.

      

   3. To create a new external credential, choose New. To edit an existing external credential, choose the external credential in the list, and then choose Edit.
   4. Complete the following fields, and save the external credential.
      • Label: Name of the external credential, for example AWS IAM Anywhere Credential.
      • Name: Unique identifier used in callout definitions and via the API, for example AWS_IAM_Anywhere_Credential.
      • Authentication Protocol: Choose AWS Signature V4.
      • Service: Name of an AWS service (for example, STS). After the validation step later in this article, you will change this value to S3.
      • Region: This value must be us-west-2. Configuration will fail for other regions.
      • AWS Account ID: (Optional) 12-digit number that identifies your AWS account.
      • Check the Obtain Temporary IAM Credentials via STS: Choose Roles Anywhere (Assume an IAM Role via Certificate).
      • Trust Anchor ARN: ARN for the trust anchor.
        Note: You can also access the IAM Roles Anywhere trust anchor by logging in to the CloudFormation console, launching the CloudFormation template in the us-west-2 Region, selecting the stack, and navigating to the Outputs tab.
      • Profile ARN: ARN of the IAM Roles Anywhere profile.
        Note: You can also access the IAM Roles Anywhere profile by logging in to the CloudFormation console, launching the CloudFormation template in the us-west-2 Region, selecting the stack, and navigating to the Outputs tab.
      • Signing Certificate: A certificate from AWS (via a CA) that’s uploaded to Salesforce.
      • STS Duration: 3600.

        

   5. Create a new principal for your external credential.
      1. With your new external credential selected, scroll to the Principals section and choose New.
      2. Enter a parameter name, for example IAMAW_Principal. Character requirements include [a-zA-Z0-9_+=,.@-]*.
      3. Enter the ARN of the IAM role.
         Note: You can also access the IAM role by logging in to the CloudFormation console, launching the CloudFormation template in the us-west-2 Region, selecting the stack, and navigating to the Outputs tab.
      4. Enter the sequence number.
      5. Save the principal.

         

Create the named credential

1. From the Setup menu in the Quick Find box, enter Named Credentials, then choose Named Credentials.
2. Choose New.
3. Provide values for the following fields:
   • Label: Enter APN API Connection. Note: Do not change this label. Otherwise, the connector won’t recognize the credentials.
   • Name: Enter APN_API_Connection.
   • URL: Enter https://sts.us-west-2.amazonaws.com. Note: After the validation step later in this article, you will change this value to the Amazon S3 service URL (https://s3.us-west-2.amazonaws.com).
4. Choose the external credential that you created in the previous step.
5. Choose the iamra client certificate that was created by importing the JKS file.
6. Enable the Generate Authorization Header option to generate a header and apply it to any callouts that reference the named credential.
7. Add the awsapn namespace of the managed app for callouts.
8. Save the named credential.

   

Step 3-E: Test and validate the IAM Roles Anywhere integration

Now that you’ve converted the private certificate into JKS, uploaded it to your Salesforce instance, and configured a named credential for the connector, you’re ready to test and validate the integration.

You test the IAM Roles Anywhere role configuration in Salesforce by confirming that the connector application from Salesforce AppExchange can use the named credential principal via the awsapn namespace.

As a prerequisite, create or edit the permission set required for the Salesforce user to access the principal that you created for the external named credential based on AWS Signature Version 4 authentication.

Create or edit a permission set for the principal

1. In the Salesforce Quick Find box, enter Permission Sets.
2. On the Permission Sets page, choose New.

   

3. Enter the label and API name for the permission set and choose Save.

   

4. With the newly created permission set open, choose External Credential Principal Access.

   

5. In the Available External Credential Principals field, choose the principal name and move it to the Enabled External Credential Principals field.
6. Save the permission set and assign it to your Salesforce user.

   

(Optional) Test the named credential

1. Open the Developer console in your Salesforce account.
2. In the Debug menu, choose Open Execute Anonymous Window to open a new window.

   

3. Copy and paste the following code into the window and update it with the details of your API and use case.

   HttpRequest req = new HttpRequest();
   //APN_API_Connection is the name of the named credential
   req.setEndpoint('callout:APN_API_Connection/?Action=GetCallerIdentity&Version=2011-06-15');
   req.setMethod('GET');
   Http http = new Http();
   HTTPResponse res = http.send(req);
   System.debug(res.getBody());

4. Choose Execute.

   

5. Open the log file to see the status. If successful, the log shows a 200 status code to indicate a successful Amazon STS API call from AWS.

   

Step 3-F: Update the URL for the named credential

Log in to your Salesforce environment, locate your named credential, and update the following fields:

1. In the Service field, change the value to S3.

   

2. In the URL field, enter the following URL: https://s3.us-west-2.amazonaws.com.

   

Cleanup

If you don’t plan to continue configuring IAM Roles Anywhere, delete the CloudFormation stack to avoid incurring additional costs on your AWS bill. For details, see Deleting a stack on the AWS CloudFormation console.

Conclusion

Congratulations! You’ve successfully configured authentication via IAM Roles Anywhere for your AWS Partner CRM Connector integration between Salesforce and AWS Partner Central. Your security team can rest assured that you no longer have to hardcode IAM user credentials into Salesforce, avoiding a potential security risk.

Now, you’re ready to take the next step and configure integration settings for the connector in your Salesforce environment. For details, see Configure AWS Partner CRM Connector Settings.

If you have comments or feedback about this post, please submit them in the discussion area of this page.

About the authors