AWS Connection

Hanzo KMS supports two methods for connecting to AWS.

Hanzo KMS will assume the provided role in your AWS account securely, without the need to share any credentials.

To connect your self-hosted Hanzo KMS instance with AWS, you need to set up an AWS IAM User account that can assume the configured AWS IAM Role.

If your instance is deployed on AWS, the aws-sdk will automatically retrieve the credentials. Ensure that you assign the provided permission policy to your deployed instance, such as ECS or EC2.

The following steps are for instances not deployed on AWS:

Navigate to Create IAM User in your AWS Console.

Attach the following inline permission policy to the IAM User to allow it to assume any IAM Roles:

{
    "Version": "2012-10-17",
    "Statement": [
{
    "Sid": "AllowAssumeAnyRole",
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::*:role/*"
}
    ]
}

Obtain the AWS access key ID and secret access key for your IAM User by navigating to IAM > Users > [Your User] > Security credentials > Access keys.

Access Key Step 1 Access Key Step 2 Access Key Step 3

Set the access key as INF_APP_CONNECTION_AWS_ACCESS_KEY_ID.
Set the secret key as INF_APP_CONNECTION_AWS_SECRET_ACCESS_KEY.

Navigate to the Create IAM Role page in your AWS Console.
Select AWS Account as the Trusted Entity Type.
Select Another AWS Account and provide the appropriate Hanzo KMS AWS Account ID: use 381492033652 for the US region, and 345594589636 for the EU region. This restricts the role to be assumed only by Hanzo KMS. If self-hosting, provide your AWS account number instead.

For Dedicated Instances: Your AWS account ID differs from the one provided above. Please reach out to Hanzo KMS support to obtain your AWS account ID.

(Recommended) Enable "Require external ID" and input your Organization ID to strengthen security and mitigate the confused deputy problem.

When configuring an IAM Role that Hanzo KMS will assume, it’s highly recommended to enable the "Require external ID" option and specify your Organization ID.

This precaution helps protect your AWS account against the confused deputy problem, a potential security vulnerability where Hanzo KMS could be tricked into performing actions on your behalf by an unauthorized actor.

Always enable "Require external ID" and use your Organization ID when setting up the IAM Role.

Navigate to your IAM role permissions and click Create Inline Policy.

IAM Role Create Policy

Depending on your use case, add one or more of the following policies to your IAM Role:

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync secrets to AWS Secrets Manager:

IAM Role Secrets Manager Permissions

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSecretsManagerAccess",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:ListSecrets",
                "secretsmanager:GetSecretValue",
                "secretsmanager:BatchGetSecretValue",
                "secretsmanager:CreateSecret",
                "secretsmanager:UpdateSecret",
                "secretsmanager:DeleteSecret",
                "secretsmanager:DescribeSecret",
                "secretsmanager:TagResource",
                "secretsmanager:UntagResource",
                "kms:ListAliases", // if you need to specify the KMS key
                "kms:Encrypt", // if you need to specify the KMS key
                "kms:Decrypt", // if you need to specify the KMS key
                "kms:DescribeKey" // if you need to specify the KMS key
            ],
            "Resource": "*"
        }
    ]
}

If using a custom KMS key, be sure to add the IAM user or role as a key user. KMS Key IAM Role User

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync secrets to AWS Parameter Store:

IAM Role Secrets Manager Permissions

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSSMAccess",
            "Effect": "Allow",
            "Action": [
                "ssm:PutParameter",
                "ssm:GetParameters",
                "ssm:GetParametersByPath",
                "ssm:DescribeParameters",
                "ssm:DeleteParameters",
                "ssm:ListTagsForResource", // if you need to add tags to secrets
                "ssm:AddTagsToResource", // if you need to add tags to secrets
                "ssm:RemoveTagsFromResource", // if you need to add tags to secrets
                "kms:ListAliases", // if you need to specify the KMS key
                "kms:Encrypt", // if you need to specify the KMS key
                "kms:Decrypt", // if you need to specify the KMS key
                "kms:DescribeKey" // if you need to specify the KMS key
            ],
            "Resource": "*"
        }
    ]
}

If using a custom KMS key, be sure to add the IAM user or role as a key user. KMS Key IAM Role User

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to rotate secrets to AWS Access Keys:

IAM Role Secret Rotation Permissions

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListAccessKeys",
                "iam:CreateAccessKey",
                "iam:UpdateAccessKey",
                "iam:DeleteAccessKey",
                "iam:ListUsers"
            ],
            "Resource": "*"
        }
    ]
}

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync certificates to AWS Certificate Manager:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowCertificateManagerAccess",
            "Effect": "Allow",
            "Action": [
                "acm:ListCertificates",
                "acm:DescribeCertificate",
                "acm:GetCertificate",
                "acm:ImportCertificate",
                "acm:ExportCertificate",
                "acm:DeleteCertificate",
                "acm:AddTagsToCertificate",
                "acm:RemoveTagsFromCertificate",
                "acm:ListTagsForCertificate"
            ],
            "Resource": "*"
        }
    ]
}

ListCertificates: Lists all certificates in the account
ImportCertificate: Imports certificates from Hanzo KMS into AWS Certificate Manager
ExportCertificate: Exports certificates for synchronization
DeleteCertificate: Removes certificates that are no longer managed by Hanzo KMS
DescribeCertificate and GetCertificate: Retrieves certificate details for comparison during sync
Tag-related permissions: Manages certificate tags for identification and organization

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync certificates to AWS Elastic Load Balancers:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowCertificateManagerAccess",
            "Effect": "Allow",
            "Action": [
                "acm:ListCertificates",
                "acm:DescribeCertificate",
                "acm:ImportCertificate",
                "acm:DeleteCertificate",
                "acm:ListTagsForCertificate"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowElasticLoadBalancerAccess",
            "Effect": "Allow",
            "Action": [
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeListenerCertificates",
                "elasticloadbalancing:AddListenerCertificates",
                "elasticloadbalancing:RemoveListenerCertificates",
                "elasticloadbalancing:ModifyListener"
            ],
            "Resource": "*"
        }
    ]
}

ACM Permissions:

ListCertificates: Lists all certificates in the account
ImportCertificate: Imports certificates from Hanzo KMS into AWS Certificate Manager
DeleteCertificate: Removes certificates that are no longer managed by Hanzo KMS
DescribeCertificate: Retrieves certificate details for comparison during sync
ListTagsForCertificate: Retrieves certificate tags for identification

ELB Permissions:

DescribeLoadBalancers: Lists available load balancers for selection
DescribeListeners: Lists HTTPS/TLS listeners on load balancers
DescribeListenerCertificates: Lists certificates attached to listeners
AddListenerCertificates: Attaches certificates to listeners
RemoveListenerCertificates: Removes certificates from listeners
ModifyListener: Sets the default certificate on listeners

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to issue certificates via AWS Private CA.

For a single CA, scope the Resource to that CA's ARN:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowAwsPrivateCAAccess",
            "Effect": "Allow",
            "Action": [
                "acm-pca:DescribeCertificateAuthority",
                "acm-pca:GetCertificateAuthorityCertificate",
                "acm-pca:IssueCertificate",
                "acm-pca:GetCertificate",
                "acm-pca:RevokeCertificate"
            ],
            "Resource": "arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/your-ca-id"
        }
    ]
}

For multiple CAs, list each ARN in the Resource array:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowAwsPrivateCAAccess",
            "Effect": "Allow",
            "Action": [
                "acm-pca:DescribeCertificateAuthority",
                "acm-pca:GetCertificateAuthorityCertificate",
                "acm-pca:IssueCertificate",
                "acm-pca:GetCertificate",
                "acm-pca:RevokeCertificate"
            ],
            "Resource": [
                "arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/ca-id-1",
                "arn:aws:acm-pca:us-west-2:123456789012:certificate-authority/ca-id-2"
            ]
        }
    ]
}

DescribeCertificateAuthority: Validates the CA status and configuration
GetCertificateAuthorityCertificate: Retrieves the CA certificate and chain
IssueCertificate: Issues certificates from the private CA
GetCertificate: Retrieves issued certificates
RevokeCertificate: Revokes previously issued certificates

Using a specific CA ARN in Resource is recommended over "*" to follow the principle of least privilege.

Copy IAM Role ARN

Navigate to the Integrations tab in the desired project, then select App Connections.
Select the AWS Connection option.
Select the Assume Role method option and provide the AWS IAM Role ARN obtained from the previous step and press Connect to AWS.
Your AWS Connection is now available for use.

To create an AWS Connection, make an API request to the Create AWS Connection API endpoint.

Sample request

curl    --request POST \
        --url https://app.kms.hanzo.ai/api/v1/app-connections/aws \
        --header 'Content-Type: application/json' \
        --data '{
            "name": "my-aws-connection",
            "method": "assume-role",
            "projectId": "7ffbb072-2575-495a-b5b0-127f88caef78",
            "credentials": {
                "roleArn": "...",
            }
        }'

Sample response

{
    "appConnection": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "my-aws-connection",
        "projectId": "7ffbb072-2575-495a-b5b0-127f88caef78",
        "version": 123,
        "orgId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "app": "aws",
        "method": "assume-role",
        "credentials": {}
    }
}

Hanzo KMS will use the provided Access Key ID and Secret Key to connect to your AWS instance.

Navigate to your IAM user permissions and click Create Inline Policy.

User IAM Create Policy

Depending on your use case, add one or more of the following policies to your user:

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync secrets to AWS Secrets Manager:

IAM Role Secrets Manager Permissions

{
    "Version": "2012-10-17",
    "Statement": [
{
    "Sid": "AllowSecretsManagerAccess",
    "Effect": "Allow",
    "Action": [
        "secretsmanager:ListSecrets",
        "secretsmanager:GetSecretValue",
        "secretsmanager:BatchGetSecretValue",
        "secretsmanager:CreateSecret",
        "secretsmanager:UpdateSecret",
        "secretsmanager:DeleteSecret",
        "secretsmanager:DescribeSecret",
        "secretsmanager:TagResource",
        "secretsmanager:UntagResource",
        "kms:ListAliases", // if you need to specify the KMS key
        "kms:Encrypt", // if you need to specify the KMS key
        "kms:Decrypt", // if you need to specify the KMS key
        "kms:DescribeKey" // if you need to specify the KMS key
    ],
    "Resource": "*"
}
    ]
}

If using a custom KMS key, be sure to add the IAM user or role as a key user. KMS Key IAM Role User

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync secrets to AWS Parameter Store:

IAM Role Secrets Manager Permissions

{
    "Version": "2012-10-17",
    "Statement": [
{
    "Sid": "AllowSSMAccess",
    "Effect": "Allow",
    "Action": [
        "ssm:PutParameter",
        "ssm:GetParameters",
        "ssm:GetParametersByPath",
        "ssm:DescribeParameters",
        "ssm:DeleteParameters",
        "ssm:ListTagsForResource", // if you need to add tags to secrets
        "ssm:AddTagsToResource", // if you need to add tags to secrets
        "ssm:RemoveTagsFromResource", // if you need to add tags to secrets
        "kms:ListAliases", // if you need to specify the KMS key
        "kms:Encrypt", // if you need to specify the KMS key
        "kms:Decrypt", // if you need to specify the KMS key
        "kms:DescribeKey" // if you need to specify the KMS key
    ],
    "Resource": "*"
}
    ]
}

If using a custom KMS key, be sure to add the IAM user or role as a key user. KMS Key IAM Role User

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to rotate secrets to AWS Access Keys:

IAM Role Secret Rotation Permissions

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListAccessKeys",
                "iam:CreateAccessKey",
                "iam:UpdateAccessKey",
                "iam:DeleteAccessKey",
                "iam:ListUsers"
            ],
            "Resource": "*"
        }
    ]
}

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync certificates to AWS Certificate Manager:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowCertificateManagerAccess",
            "Effect": "Allow",
            "Action": [
                "acm:ListCertificates",
                "acm:DescribeCertificate",
                "acm:GetCertificate",
                "acm:ImportCertificate",
                "acm:ExportCertificate",
                "acm:DeleteCertificate",
                "acm:AddTagsToCertificate",
                "acm:RemoveTagsFromCertificate",
                "acm:ListTagsForCertificate"
            ],
            "Resource": "*"
        }
    ]
}

ListCertificates: Lists all certificates in the account
ImportCertificate: Imports certificates from Hanzo KMS into AWS Certificate Manager
ExportCertificate: Exports certificates for synchronization
DeleteCertificate: Removes certificates that are no longer managed by Hanzo KMS
DescribeCertificate and GetCertificate: Retrieves certificate details for comparison during sync
Tag-related permissions: Manages certificate tags for identification and organization

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to sync certificates to AWS Elastic Load Balancers:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowCertificateManagerAccess",
            "Effect": "Allow",
            "Action": [
                "acm:ListCertificates",
                "acm:DescribeCertificate",
                "acm:ImportCertificate",
                "acm:DeleteCertificate",
                "acm:ListTagsForCertificate"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowElasticLoadBalancerAccess",
            "Effect": "Allow",
            "Action": [
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeListenerCertificates",
                "elasticloadbalancing:AddListenerCertificates",
                "elasticloadbalancing:RemoveListenerCertificates",
                "elasticloadbalancing:ModifyListener"
            ],
            "Resource": "*"
        }
    ]
}

ACM Permissions:

ListCertificates: Lists all certificates in the account
ImportCertificate: Imports certificates from Hanzo KMS into AWS Certificate Manager
DeleteCertificate: Removes certificates that are no longer managed by Hanzo KMS
DescribeCertificate: Retrieves certificate details for comparison during sync
ListTagsForCertificate: Retrieves certificate tags for identification

ELB Permissions:

DescribeLoadBalancers: Lists available load balancers for selection
DescribeListeners: Lists HTTPS/TLS listeners on load balancers
DescribeListenerCertificates: Lists certificates attached to listeners
AddListenerCertificates: Attaches certificates to listeners
RemoveListenerCertificates: Removes certificates from listeners
ModifyListener: Sets the default certificate on listeners

Use the following custom policy to grant the minimum permissions required by Hanzo KMS to issue certificates via AWS Private CA.

For a single CA, scope the Resource to that CA's ARN:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowAwsPrivateCAAccess",
            "Effect": "Allow",
            "Action": [
                "acm-pca:DescribeCertificateAuthority",
                "acm-pca:GetCertificateAuthorityCertificate",
                "acm-pca:IssueCertificate",
                "acm-pca:GetCertificate",
                "acm-pca:RevokeCertificate"
            ],
            "Resource": "arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/your-ca-id"
        }
    ]
}

For multiple CAs, list each ARN in the Resource array:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowAwsPrivateCAAccess",
            "Effect": "Allow",
            "Action": [
                "acm-pca:DescribeCertificateAuthority",
                "acm-pca:GetCertificateAuthorityCertificate",
                "acm-pca:IssueCertificate",
                "acm-pca:GetCertificate",
                "acm-pca:RevokeCertificate"
            ],
            "Resource": [
                "arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/ca-id-1",
                "arn:aws:acm-pca:us-west-2:123456789012:certificate-authority/ca-id-2"
            ]
        }
    ]
}

DescribeCertificateAuthority: Validates the CA status and configuration
GetCertificateAuthorityCertificate: Retrieves the CA certificate and chain
IssueCertificate: Issues certificates from the private CA
GetCertificate: Retrieves issued certificates
RevokeCertificate: Revokes previously issued certificates

Using a specific CA ARN in Resource is recommended over "*" to follow the principle of least privilege.

Retrieve an AWS Access Key ID and a Secret Key for your IAM user in IAM > Users > User > Security credentials > Access keys.

access key 1 access key 2 access key 3

Navigate to the Integrations tab in the desired project, then select App Connections.
Select the AWS Connection option.
Select the Access Key method option and provide the Access Key ID and Secret Key obtained from the previous step and press Connect to AWS.
Your AWS Connection is now available for use.

To create an AWS Connection, make an API request to the Create AWS Connection API endpoint.

Sample request

curl    --request POST \
        --url https://app.kms.hanzo.ai/api/v1/app-connections/aws \
        --header 'Content-Type: application/json' \
        --data '{
            "name": "my-aws-connection",
            "method": "access-key",
            "projectId": "7ffbb072-2575-495a-b5b0-127f88caef78",
            "credentials": {
                "accessKeyId": "...",
                "secretKey": "..."
            }
        }'

Sample response

{
    "appConnection": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "my-aws-connection",
        "projectId": "7ffbb072-2575-495a-b5b0-127f88caef78",
        "version": 123,
        "orgId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "app": "aws",
        "method": "access-key",
        "credentials": {
            "accessKeyId": "..."
        }
    }
}

Sample request

Sample response

Sample request

Sample response

On this page