This guide covers how to configure Scalr's Bring Your Own Key feature using an AWS KMS key.

Requirements

Before configuring BYOK, create a KMS key in AWS with the following settings:

Scalr requires the key to be in one of these regions to minimise latency for KMS API calls.

📘

Note

We recommend creating a multi-region key (key ID starts with mrk-) even if you only use it in one region. This makes it possible to replicate the key to additional regions later without replacing it and re-encrypting your data.

The key ARN has the format:

arn:aws:kms:{REGION}:{ACCOUNT_ID}:key/{KEY_ID}

IAM Permissions

These permissions apply to all authentication methods below. The IAM principal used by Scalr needs the following permissions on your KMS key:

{
  "Effect": "Allow",
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:DescribeKey"
  ],
  "Resource": "arn:aws:kms:{REGION}:{ACCOUNT_ID}:key/{KEY_ID}"
}

kms:Encrypt and kms:Decrypt are required. kms:DescribeKey is recommended - it allows Scalr to detect issues such as a disabled or deleted key before they affect your operations.

Access Keys

Provide an IAM user access key and secret key. This is the simplest method, but requires storing long-lived credentials in Scalr.

AWS Steps

Create an IAM user and attach a policy granting the required KMS permissions. Then create an access key for the user:

1. In IAM > Users, select your user.
2. Go to the Security credentials tab and click Create access key.
3. Save the access key ID and secret access key.

See the AWS documentation for full steps on creating IAM users and access keys.

Scalr Steps

In Scalr, go to Account Settings > Security > Encryption, click Enable, select AWS KMS, and choose Access Keys:

• KMS key ARN: full key ARN
• Credentials type: Access Keys
• Access key ID: your IAM user access key
• Secret access key: your IAM user secret key

Assume Role

Scalr assumes an IAM role in your account using a cross-account trust policy and an external ID. No long-lived credentials are stored in Scalr.

AWS Steps

Create an IAM role with a custom trust policy, replacing {YOUR_EXTERNAL_ID} with a unique string you generate:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::615271354814:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "{YOUR_EXTERNAL_ID}"
        }
      }
    }
  ]
}

615271354814 is Scalr's AWS account ID. Attach a policy granting the required KMS permissions to the role and save its ARN.

See the AWS documentation for full steps on creating IAM roles with external ID conditions.

Scalr Steps

In Scalr, go to Account Settings > Security > Encryption, click Enable, select AWS KMS, and choose Assume Role:

• KMS key ARN: full key ARN
• Credentials type: Assume Role
• Role ARN: ARN of the role created above
• External ID: the same external ID used in the trust policy

OIDC (Web Identity)

Scalr authenticates using a short-lived OIDC token exchanged for temporary AWS credentials via sts:AssumeRoleWithWebIdentity. No long-lived credentials are stored anywhere.

AWS Steps

Create an OIDC identity provider

Register Scalr as an identity provider in AWS IAM:

1. Go to IAM > Identity providers > Add provider.
2. Configure the provider:
   • Provider type: OpenID Connect
   • Provider URL: https://scalr.io
   • Audience: a string of your choice (e.g. scalr_kms). You will use this value in the trust policy.
3. Click Add provider.

Create an IAM role

Create a role with a web identity trust policy, replacing the your-aws-account-id, your-audience, and scalr-account-name placeholders:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<your-aws-account-id>:oidc-provider/scalr.io"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "scalr.io:aud": "<your-audience>"
        },
        "StringLike": {
          "scalr.io:sub": "account:<scalr-account-name>"
        }
      }
    }
  ]
}

Attach a policy granting the required KMS permissions to the role and save its ARN.

See the AWS documentation for full steps on creating roles for OIDC identity providers.

Scalr Steps

In Scalr, go to Account Settings > Security > Encryption, click Enable, select AWS KMS, and choose OIDC:

• KMS key ARN: full key ARN
• Credentials type: OIDC
• Role ARN: ARN of the role created above
• Audience: the audience string from the identity provider (must match the value in the trust policy)