Allowing users in other accounts to use a KMS key - AWS Key Management Service
Step 1: Add a key policy statement in the local accountStep 2: Add IAM policies in the external accountAllowing use of external KMS keys with AWS servicesUsing KMS keys in other accounts

Allowing users in other accounts to use a KMS key

You can allow users or roles in a different AWS account to use a KMS key in your account. Cross-account access requires permission in the key policy of the KMS key and in an IAM policy in the external user's account.

Cross-account permission is effective only for the following operations:

If you give a user in a different account permission for other operations, those permissions have no effect. For example, if you give a principal in a different account kms:ListKeys permission in an IAM policy, or kms:ScheduleKeyDeletion permission on a KMS key in a key policy, the user's attempts to call those operations on your resources still fail.

For details about using KMS keys in different accounts for AWS KMS operations, see the Cross-account use column in the AWS KMS permissions and Using KMS keys in other accounts. There is also a Cross-account use section in each API description in the AWS Key Management Service API Reference.

Warning

Be cautious about giving principals permissions to use your KMS keys. Whenever possible, follow the least privilege principle. Give users access only to the KMS keys they need for only the operations they require.

Also, be cautious about using any unfamiliar KMS key, especially a KMS key in a different account. Malicious users might give you permissions to use their KMS key to get information about you or your account.

For information about using policies to protect the resources in your account, see Best practices for IAM policies.

To give permission to use a KMS key to users and roles in another account, you must use two different types of policies:

  • The key policy for the KMS key must give the external account (or users and roles in the external account) permission to use the KMS key. The key policy is in the account that owns the KMS key.

  • IAM policies in the external account must delegate the key policy permissions to its users and roles. These policies are set in the external account and give permissions to users and roles in that account.

The key policy determines who can have access to the KMS key. The IAM policy determines who does have access to the KMS key. Neither the key policy nor the IAM policy alone is sufficient—you must change both.

To edit the key policy, you can use the Policy View in the AWS Management Console or use the CreateKey or PutKeyPolicy operations.

For help with editing IAM policies, see Using IAM policies with AWS KMS.

For an example that shows how the key policy and IAM policies work together to allow use of a KMS key in a different account, see Example 2: User assumes role with permission to use a KMS key in a different AWS account.

You can view the resulting cross-account AWS KMS operations on the KMS key in your AWS CloudTrail logs. Operations that use KMS keys in other accounts are logged in both the caller's account and the KMS key owner account.

Note

The examples in this topic show how to use a key policy and IAM policy together to provide and limit access to a KMS key. These generic examples are not intended to represent the permissions that any particular AWS service requires on a KMS key. For information about the permissions that an AWS service requires, see the encryption topic in the service documentation.

Step 1: Add a key policy statement in the local account

The key policy for a KMS key is the primary determinant of who can access the KMS key and which operations they can perform. The key policy is always in the account that owns the KMS key. Unlike IAM policies, key policies do not specify a resource. The resource is the KMS key that is associated with the key policy. When providing cross-account permission, the key policy for the KMS key must give the external account (or users and roles in the external account) permission to use the KMS key.

To give an external account permission to use the KMS key, add a statement to the key policy that specifies the external account. In the Principal element of the key policy, enter the Amazon Resource Name (ARN) of the external account.

When you specify an external account in a key policy, IAM administrators in the external account can use IAM policies to delegate those permissions to any users and roles in the external account. They can also decide which of the actions specified in the key policy the users and roles can perform.

Permissions given to the external account and its principals are effective only if the external account is enabled in the Region that hosts the KMS key and its key policy. For information about Regions that are not enabled by default ("opt-in Regions"), see Managing AWS Regions in the AWS General Reference.

For example, suppose you want to allow account 444455556666 to use a symmetric encryption KMS key in account 111122223333. To do that, add a policy statement like the one in the following example to the key policy for the KMS key in account 111122223333. This policy statement gives the external account, 444455556666, permission to use the KMS key in cryptographic operations for symmetric encryption KMS keys.

Note

The following example represents a sample key policy for sharing a KMS key with another account. Replace the example Sid, Principal, and Action values with valid values for the intended use of your KMS key. 

{
    "Sid": "Allow an external account to use this KMS key",
    "Effect": "Allow",
    "Principal": {
        "AWS": [
            "arn:aws:iam::444455556666:root"
        ]
    },
    "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
    ],
    "Resource": "*"
}

Instead of giving permission to the external account, you can specify particular external users and roles in the key policy . However, those users and roles cannot use the KMS key until IAM administrators in the external account attach the proper IAM policies to their identities. The IAM policies can give permission to all or a subset of the external users and roles that are specified in the key policy. And they can allow all or a subset of the actions specified in the key policy.

Specifying identities in a key policy restricts the permissions that IAM administrators in the external account can provide. However, it makes policy management with two accounts more complex. For example, assume that you need to add a user or role. You must add that identity to the key policy in the account that owns the KMS key and create IAM policies in the identity's account.

To specify particular external users or roles in a key policy, in the Principal element, enter the Amazon Resource Name (ARN) of a user or role in the external account.

For example, the following example key policy statement allows ExampleRole in account 444455556666 to use a KMS key in account 111122223333. This key policy statement gives the external account, 444455556666, permission to use the KMS key in cryptographic operations for symmetric encryption KMS keys.

Note

The following example represents a sample key policy for sharing a KMS key with another account. Replace the example Sid, Principal, and Action values with valid values for the intended use of your KMS key. 

{
    "Sid": "Allow an external account to use this KMS key",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::444455556666:role/ExampleRole"
    },
    "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
    ],
    "Resource": "*"
}
Note

Do not set the Principal to an asterisk (*) in any key policy statement that allows permissions unless you use conditions to limit the key policy. An asterisk gives every identity in every AWS account permission to use the KMS key, unless another policy statement explicitly denies it. Users in other AWS accounts can use your KMS key whenever they have corresponding permissions in their own account.

You also need to decide which permissions you want to give to the external account. For example, you might want to give users permission to decrypt but not encrypt, or permission to view the KMS key but not use it. For a list of permissions on KMS keys, see AWS KMS permissions.

Setting the key policy when you create a KMS key

When you use the CreateKey operation to create a KMS key, you can use its Policy parameter to specify a key policy that gives an external account, or external users and roles, permission to use the KMS key.

When you create a KMS key in the AWS Management Console, you also create its key policy. When you select identities in the Key Administrators and Key Users sections, AWS KMS adds policy statements for those identities to the KMS key's key policy. The Key Users section also lets you add external accounts as key users.

When you enter the account ID of an external account, AWS KMS adds two statements to the key policy. This action only affects the key policy. Users and roles in the external account cannot use the KMS key until you attach IAM policies to give them some or all of these permissions.

The first key policy statement gives the external account permission to use the KMS key in cryptographic operations. The second key policy statement allows the external account to create, view, and revoke grants on the KMS key, but only when the request comes from an AWS service that is integrated with AWS KMS. These permissions allow other AWS services that encrypt user data to use the KMS key. These permissions are designed for KMS keys that encrypt user data in AWS services

Step 2: Add IAM policies in the external account

The key policy in the account that owns the KMS key sets the valid range for permissions. But, users and roles in the external account cannot use the KMS key until you attach IAM policies that delegate those permissions, or use grants to manage access to the KMS key. The IAM policies are set in the external account.

If the key policy gives permission to the external account, you can attach IAM policies to any user or role in the account. But if the key policy gives permission to specified users or roles, the IAM policy can only give those permissions to all or a subset of the specified users and roles. If an IAM policy gives KMS key access to other external users or roles, it has no effect.

The key policy also limits the actions in the IAM policy. The IAM policy can delegate all or a subset of the actions specified in the key policy. If the IAM policy lists actions that are not specified in the key policy, those permissions are not effective.

The following example IAM policy allows the principal to use the KMS key in account 111122223333 for cryptographic operations. To give this permission to users and roles in account 444455556666, attach the policy to the users or roles in account 444455556666.

Note

The following example represents a sample IAM policy for sharing a KMS key with another account. Replace the example Sid, Resource, and Action values with valid values for the intended use of your KMS key.

{
    "Sid": "AllowUseOfKeyInAccount111122223333",
    "Effect": "Allow",
    "Action": [
      "kms:Encrypt",
      "kms:Decrypt",
      "kms:ReEncrypt*",
      "kms:GenerateDataKey*",
      "kms:DescribeKey"
    ],
    "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

Note the following details about this policy:

  • Unlike key policies, IAM policy statements do not contain the Principal element. In IAM policies, the principal is the identity to which the policy is attached.

  • The Resource element in the IAM policy identifies the KMS key that the principal can use. To specify a KMS key, add its key ARN to the Resource element.

  • You can specify more than one KMS key in the Resource element. But if you don't specify particular KMS keys in the Resource element, you might inadvertently give access to more KMS keys than you intend.

  • To allow the external user to use the KMS key with AWS services that integrate with AWS KMS, you might need to add permissions to the key policy or the IAM policy. For details, see Allowing use of external KMS keys with AWS services.

For more information about working with IAM policies, see IAM policies.

Allowing use of external KMS keys with AWS services

You can give a user in a different account permission to use your KMS key with a service that is integrated with AWS KMS. For example, a user in an external account can use your KMS key to encrypt the objects in an Amazon S3 bucket or to encrypt the secrets they store in AWS Secrets Manager.

The key policy must give the external user or the external user's account permission to use the KMS key. In addition, you need to attach IAM policies to the identity that gives the user permission to use the AWS service. The service might also require that users have additional permissions in the key policy or IAM policy. For a list of permissions that the AWS service requires on a customer managed key, see the Data Protection topic in the Security chapter of the user guide or developer guide for the service.

Using KMS keys in other accounts

If you have permission to use a KMS key in a different AWS account, you can use the KMS key in the AWS Management Console, AWS SDKs, AWS CLI, and AWS Tools for PowerShell.

To identify a KMS key in a different account in a shell command or API request, use the following key identifiers.

If you enter only a key ID or alias name, AWS assumes the KMS key is in your account.

The AWS KMS console does not display KMS keys in other accounts, even if you have permission to use them. Also, the lists of KMS keys displayed in the consoles of other AWS services do not include KMS keys in other accounts.

To specify a KMS key in a different account in the console of an AWS service, you must enter the key ARN or alias ARN of the KMS key. The required key identifier varies with the service, and might differ between the service console and its API operations. For details, see the service documentation.