Implementing customer managed KMS keys in Amazon IAM Identity Center - Amazon IAM Identity Center
Step 1: Identify use cases for your organizationStep 2: Prepare KMS key policy statementsStep 3: Create a KMS keyStep 4: Configure IAM policiesStep 5: Configure the KMS key in IAM Identity Center
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Implementing customer managed KMS keys in Amazon IAM Identity Center

Note

Customer managed KMS keys for Amazon IAM Identity Center are currently available in select Amazon Regions.

Customer managed keys are Amazon Key Management Service keys that you create, own, and manage. To implement a customer managed KMS key for encryption at rest in Amazon IAM Identity Center, follow these steps:

Important

Some Amazon managed applications cannot be used with Amazon IAM Identity Center configured with a customer managed KMS key. See Amazon managed applications that you can use with IAM Identity Center.

  1. Step 1: Identify use cases for your organization - To define correct permissions for use of the KMS key you need to identify the relevant use cases across your organization. The KMS key permissions consist of KMS key policy statements and identity-based policies that work together to allow appropriate IAM principals to use the KMS key for their specific use cases.

  2. Step 2: Prepare KMS key policy statements - Choose pertinent KMS key policy statement templates based on the use cases identified in Step 1, and fill in required identifiers and IAM principal names. Start with the baseline KMS key policy statements, and if your security policies require it, refine them as described in Advanced KMS key policy statements.

  3. Step 3: Create a customer managed KMS key - Create a KMS key in Amazon KMS that meets the IAM Identity Center requirements, and add the KMS key policy statements prepared in Step 2 to the KMS key policy.

  4. Step 4: Configure IAM policies for cross-account use of the KMS key - Choose pertinent IAM policy statement templates based on the use cases identified in Step 1, and prepare them for use by filling in the key ARN. Then, allow the IAM principals for each specific use case to use the KMS key across accounts by adding the prepared IAM policy statements to the principals' IAM policies.

  5. Step 5: Configure the KMS key in IAM Identity Center - IMPORTANT: Before proceeding with this step, thoroughly validate all KMS key permissions configured in the previous steps. Once completed, IAM Identity Center will begin using the KMS key for encryption at rest.

Step 1: Identify use cases for your organization

Before creating and configuring your customer managed KMS key, identify your use cases and prepare the required KMS key permissions. Refer to Amazon KMS Developer Guide for more information on the KMS key policy.

IAM principals that call the IAM Identity Center and Identity Store APIs require permissions. For example, a delegated administrator can be authorized to use these APIs through a permission set policy. When IAM Identity Center is configured with a customer managed key, IAM principals must also have permissions to use the KMS API through the IAM Identity Center and Identity Store APIs. You define these KMS API permissions in two places: the KMS key policy and in the IAM policies associated with the IAM principals.

The KMS key permissions consist of:

  1. KMS key policy statements that you specify on the KMS key during its creation in Step 3: Create a customer managed KMS key.

  2. IAM policy statements for IAM principals that you specify in Step 4: Configure IAM policies for cross-account use of the KMS key after you create the KMS key.

The following table specifies the relevant use cases and IAM principals that need permissions to use your KMS key.

Use case IAM principals that need permissions to use the KMS key Required/Optional
Use of Amazon IAM Identity Center

  • Administrators of Amazon IAM Identity Center

  • IAM Identity Center service and the associated Identity Store service

 Required
Use of Amazon managed applications with IAM Identity Center

  • Administrators of Amazon managed applications

  • Amazon managed applications

  • Service roles that Amazon managed applications assume to call IAM Identity Center and Identity Store APIs

 Optional
Use of Amazon Control Tower on the Amazon IAM Identity Center instance it enabled

  • Amazon Control Tower administrators

 Optional
SSO to Amazon EC2 Windows instances with Amazon IAM Identity Center

  • IAM principals authorized to perform SSO to Amazon EC2 Windows instances

 Optional
Any other use case that makes calls to IAM Identity Center API or Identity Store API, such as permission set provisioning workflows, or Amazon Lambda functions

  • IAM principals used by these workflows to call IAM Identity Center API and Identity Store API

 Optional
Note

Multiple IAM principals listed in the table require Amazon KMS API permissions. However, to protect your user and group data in IAM Identity Center, only IAM Identity Center and Identity Store services directly call the Amazon KMS API.

Step 2: Prepare KMS key policy statements

After identifying the use cases relevant to your organization, you can prepare the corresponding KMS key policy statements.

  1. Choose the KMS key policy statements that match the use cases for your organization. Begin with the baseline policy templates. If you need more specific policies based on your security requirements, you can modify the policy statements using the examples in Advanced KMS key policy statements. For guidance on this decision, see Considerations for choosing baseline vs. advanced KMS key policy statements. In addition, each baseline section in Baseline KMS key and IAM policy statements includes relevant considerations.

  2. Copy the relevant policies to an editor and insert the required identifiers and IAM principal names in the KMS key policy statements. For help finding the values of the referenced identifiers, see Find the required identifiers.

Following are baseline policy templates for each use case. Only the first set of permissions for Amazon IAM Identity Center is required to use a KMS key. We recommend that you review the applicable subsections for additional use case-specific information.

Important

Exercise caution when modifying KMS key policies for keys already in use by IAM Identity Center. While IAM Identity Center validates encryption and decryption permissions when you initially configure a KMS key, it cannot verify subsequent policy changes. Inadvertently removing necessary permissions could disrupt your IAM Identity Center's normal operation. For guidance troubleshooting common errors related to customer managed keys in IAM Identity Center, refer to Troubleshoot customer managed keys in Amazon IAM Identity Center.

Note

IAM Identity Center and its associated Identity Store require service-level permissions to use your customer managed KMS key. This requirement extends to Amazon managed applications that call IAM Identity Center's APIs using service credentials. For other use cases where IAM Identity Center's APIs are called with forward access sessions, only the initiating IAM principal (such as an administrator) needs KMS key permissions. Notably, end users using the Amazon access portal and Amazon managed applications don't need direct KMS key permissions, as they are granted through the respective services.

Step 3: Create a customer managed KMS key

You can create a customer managed key using the Amazon Management Console or the Amazon KMS APIs. While creating the key, add the KMS key policy statements you prepared in Step 2 into the KMS key policy. For detailed instructions, including guidance on the default KMS key policy, see the Amazon Key Management Service Developer Guide.

The key must meet the following requirements:

  • The KMS key must be in the same Amazon Region as the IAM Identity Center instance

  • You can choose either a multi-Region or a single-Region key. To remain forward-compatible with your future use cases across multiple Amazon Regions, we recommend choosing a multi-Region key

  • The KMS key must be a symmetric key configured for "encrypt and decrypt" usage

  • The KMS key must be in the same Amazon Organizations management account as the organization instance of IAM Identity Center

Step 4: Configure IAM policies for cross-account use of the KMS key

Any IAM principal that uses the IAM Identity Center and Identity Store APIs from another Amazon account, such as IAM Identity Center delegated administrators, also needs an IAM policy statement that allows use of the KMS key through these APIs.

For each use case identified in step 1:

  1. Locate the pertinent IAM policy statement templates in Baseline KMS key and IAM policy statements.

  2. Copy the templates to an editor and fill in the key ARN, which is now available following the creation of the KMS key in step 3. For help finding the key ARN value, see Find the required identifiers.

  3. In the Amazon Web Services Management Console, locate the IAM policy of the IAM principal that is associated with the use case. The location of this policy varies depending on the use case and how access is granted.

    • For access granted directly in IAM, you can locate IAM principals, such as IAM roles in the IAM console.

    • For access granted through IAM Identity Center, you can locate the pertinent permission set in the IAM Identity Center console.

  4. Add the use case-specific IAM policy statements to the IAM role and save the change.

Note

The IAM policies described here are identity-based policies. While such policies can be attached to IAM users, groups, and roles, we recommend the use of IAM roles when possible. See the IAM user guide for more information about IAM roles versus IAM users.

Additional configuration in some Amazon managed applications

Some Amazon managed applications require you to configure a service role to allow the applications to use the IAM Identity Center and Identity Store APIs. If your organization uses Amazon managed applications with IAM Identity Center, complete the following steps for each deployed application:

  1. See the application's user guide to confirm whether the permissions have been updated to include KMS key-related permissions for use of the application with IAM Identity Center.

  2. If so, update the permissions as instructed in the application's user guide to avoid disruption to the application's operations.

Note

If you're unsure whether an Amazon managed application uses these permissions, we recommend that you check the user guides of all deployed Amazon managed applications. You only need to perform this configuration once for each application that requires the configuration.

Step 5: Configure the KMS key in IAM Identity Center

Important

Before proceeding with this step:

  • Verify that your Amazon managed applications are compatible with customer managed KMS keys. For a list of compatible applications, see Amazon managed applications that you can use with IAM Identity Center. If you have incompatible applications, do not proceed.

  • Configure the necessary permissions for use of the KMS key. Without proper permissions, this step may fail or disrupt IAM Identity Center administration and Amazon managed applications. For more information, see Step 1: Identify use cases for your organization.

  • Ensure that permissions for Amazon managed applications also allow the use of the KMS key via IAM Identity Center and Identity Store APIs. Some Amazon managed applications require you to configure permissions, such as a service role, for the use of these APIs. Refer to the User Guide of each deployed Amazon managed application to confirm if you need to add specific KMS key permissions.

Console

To specify a KMS key when enabling a new organization instance of IAM Identity Center

When enabling a new organization instance of IAM Identity Center, you can specify a customer managed KMS key during setup. This ensures the instance uses your key for encryption at rest from the start. Before you start, refer to Considerations for customer managed KMS keys and advanced KMS key policies.

  1. On the Enable IAM Identity Center page, expand the Encryption at rest section.

  2. Choose Manage Encryption.

  3. Choose Customer managed key.

  4. For KMS key, do one of the following:

    1. Choose Select from your KMS keys and select the key you created from the dropdown list.

    2. Choose Enter KMS key ARN and enter the full ARN of your key.

  5. Choose Save.

  6. Choose Enable to complete the setup.

For more information, see Enable IAM Identity Center.

To specify a KMS key for an existing organization instance of IAM Identity Center

  1. Open the IAM Identity Center console at https://console.aws.amazon.com/singlesignon/.

  2. In the navigation pane, choose Settings.

  3. On the Settings page in the Encryption section, choose Edit.

  4. For Encryption type, choose Customer managed key.

  5. For KMS key, do one of the following:

    1. Choose Select from your KMS keys and select the key you created from the dropdown list.

      Note

      Note that the pull-down list will only show the KMS keys you have access to in the same Amazon account. Therefore, if you're doing this in the delegated administration account, you will need to specify the ARN of the key from your Amazon Organizations management account.

    2. Choose Enter KMS key ARN and enter the full ARN of your key.

  6. Choose Save changes.

Amazon CLI
aws ssoadmin update-instance \
  --configuration KeyType=string,KmsKeyArn=string \
  --instance-arn string \
  --name string

Change your KMS key configuration

You can change your customer managed KMS key to another key or switch to an Amazon owned key at any time.

To change your KMS key configuration

  1. Open the IAM Identity Center console.

  2. In the navigation pane, choose Settings.

  3. Choose the Additional settings tab.

  4. Choose Manage encryption.

  5. Choose one of the following:

    1. Customer managed key - Select a different customer managed key from the dropdown or enter a new key ARN.

    2. Amazon owned key - Switch to the default encryption option.

  6. Choose Save.

Customer managed key considerations

  • Updating the KMS key configuring for IAM Identity Center operation has no effect on active user sessions in your IAM Identity Center. You can continue using the Amazon access portal, the IAM Identity Center console, and IAM Identity Center APIs during this process.

  • When switching to a new KMS key, IAM Identity Center validates that it can use the key successfully for encryption and decryption. If you made a mistake during the setup of the key policy or IAM policy, the console will show an explanatory error message, and the previous KMS key will remain in use.

  • The default annual KMS key rotation will take place automatically. You can refer to the Amazon KMS Developer Guide for information on topics such as key rotation, monitoring Amazon KMS keys and controlling access to key deletion.

Important

If the customer managed KMS key in use by your IAM Identity Center instance is deleted, disabled, or inaccessible due to an incorrect KMS key policy, your workforce users and IAM Identity Center administrators will not be able to use IAM Identity Center. The loss of access can be temporary (a key policy can be corrected) or permanent (a deleted key cannot be restored) depending on the circumstances. We recommend you restrict access to critical operations, such as deleting or disabling the KMS key. Also, we recommend that your organization set up Amazon break-glass access procedures to ensure your privileged users can access Amazon in the unlikely event that IAM Identity Center is inaccessible.

Find the required identifiers

When configuring permissions for your customer managed KMS key, you'll need specific Amazon resource identifiers to complete the key policy and IAM policy statement templates. Insert the required identifiers (for example, organization ID) and IAM principal names in the KMS key policy statements.

Below is a guide to locating these identifiers in the Amazon Management Console.

IAM Identity Center Amazon Resource Name (ARN) and Identity Store ARN

An IAM Identity Center instance is an Amazon resource with its own unique ARN such as arn:aws:sso:::instance/ssoins-1234567890abcdef. The ARN follows the pattern documented in the IAM Identity Center resource types section of the Service Authorization Reference.

Every IAM Identity Center instance has an associated Identity Store that stores the user and group identities. An Identity Store has a unique identifier called Identity Store ID (for example, d-123456789a). The ARN follows the pattern documented in the Identity Store resource types section of the Service Authorization Reference.

You can find both the ARN and the Identity Store ID values on the Settings page of your IAM Identity Center. Note that the Identity store ID is in the Identity source tab.

Amazon Organizations ID

If you want to specify an organization ID (for example, o-exampleorg1) in your key policy you can find its value in the Settings page of your IAM Identity Center and Organizations consoles. The ARN follows the pattern documented in the Organizations resource types section of the Service Authorization Reference.

KMS key ARN

You can find the ARN of a KMS key in the Amazon KMS console. Choose Customer managed keys on the left, click the key whose ARN you want to look up, and you'll see it in the General configuration section. The ARN follows the pattern documented in the Amazon KMS resource types section of the Service Authorization Reference.

See the Amazon Key Management Service Service Developer Guide for more information about Key policies in Amazon KMS and troubleshooting Amazon KMS permissions. For more information about IAM policies and their JSON representation see the IAM User Guide.