Integration Guide - Reco KMS - Bring-Your-Own-Key

This guide walks you through configuring an IAM role that allows Reco to securely access your new KMS. You will then provide the necessary details to Reco and inform Reco Customer Success before finalizing the integration.

Step 1: Create an IAM Role

We will start with the AWS Web Console instructions and provide alternative AWS CLI commands for each step.

1.1 Open AWS IAM Console

Using Web Console: Log in to the AWS Management Console and navigate to the IAM service.
Using AWS CLI: No CLI alternative for logging into the console.

1.2 Create a Role

Web Console:

1. In the IAM dashboard, click on **"Roles"**, then **"Create Role."**

2. Select **"Another AWS account"** as the trusted entity.

3. Enter **495155430317** (Reco's AWS Account ID).

4. For the **External ID**, enter a value agreed upon between you and Reco (this ensures only Reco can assume this role).

CLI Alternative:

aws iam create-role --role-name RecoKMSAccessRole --assume-role-policy-document file://trust-policy.json

The trust-policy.json file should contain:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::495155430317:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<YOUR-EXTERNAL-ID>"
                }
            }
        }
    ]
}

Replace <YOUR-EXTERNAL-ID> with your agreed External ID.

1.3 Attach Bucket Permissions

Web Console:

After setting the trust relationship, proceed to the permissions section.
Click "Create Policy" and choose the "JSON" editor.

Paste the following policy, replacing <YOUR-CUSTOM-KMS-ID> with your bucket name:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:PutObject",
                "kms:GetObject",
                "kms:ListKeys"
            ],
            "Resource": [
                "arn:aws:kms:::<YOUR-CUSTOM-KEY-ID>/*",
                "arn:aws:kms:::<YOUR-CUSTOM-KEY-ID>"
            ]
        }
    ]
}

Save the policy, attach it to the role, and finish creating the role.

CLI Alternative:

aws iam put-role-policy --role-name RecoKMSAccessRole --policy-name RecoKMSAccessRole --policy-document file://kms-access-policy.json

The kms-access-policy.json should contain the same policy as above.

1.4 Retrieve the Role ARN

Web Console:

After creating the role, go to "Roles" in IAM, select your role, and copy the Role ARN (Amazon Resource Name). You'll need this for the integration fields.

CLI Alternative:

aws iam get-role --role-name RecoKMSAccessRole --query 'Role.Arn' --output text

Step 2: Fill in the Reco Integration Fields

Once the role is set up, gather the following information and provide it to Reco:

Custom Key: Your custom key id (e.g., custom-kms-key-id).
Role ARN: The ARN of the IAM role you created (e.g., arn:aws:iam::<YOUR-AWS-ACCOUNT-ID>:role/RecoKmsAccessRole).
External ID: The External ID you set in the trust relationship.

You will input this information in Reco’s integration form.

Step 3: Inform Reco Customer Success

Finally, contact Reco Customer Success and ask them to enable your BYOK integration