Set up your AWS account and create a KMS key policy

Customer-managed keys (CMK) give you greater control and visibility over your encryption keys to protect your organization’s Atlassian Cloud data. CMK is currently in Open Beta, and customers not already enrolled in BYOK can enroll in it. BYOK will eventually be deprecated and migrated to CMK.

Use AWS KMS as the root of trust

Use AWS KMS to manage keys that are used to protect your Atlassian app data. While it's advisable to dedicate this account specifically for Atlassian cloud usage, it's not a strict requirement.

You may need to create an AWS account if you don’t already have one. Understand how to create and activate an AWS account. If you need help creating an AWS account, contact AWS support.

Anticipate AWS costs

Since you’re using your own KMS keys in your AWS accounts, additional AWS costs may be incurred. Based on AWS KMS key pricing, you'll only need to pay for key storage costs. KMS API request costs will be billed to Atlassian.

Set up AWS KMS keys and a provisional key policy

Set up AWS KMS keys with a baseline key policy to grant Atlassian the necessary operation permissions.

Available realms for hosting customer-managed keys (CMK) are listed below. You’ll need to create one KMS key per region within the chosen realm.

What key access do you need to provide?

Atlassian will ask you to provide API-level operation access. It’s important that the requested access is granted, otherwise your CMK-enabled cloud apps may not function correctly. Additionally, Atlassian may need to suspend access to these apps until you provide the necessary access.

We have provided two setup methods below, one via AWS CloudFormation and the other by manual configuration. You can follow either method to create the KMS keys and a provisional key policy.

Method 1: Set up via CloudFormation

1. Go to Cloud Computing Services - Amazon Web Services (AWS) and sign into your account.

2. Select the IAM user option (with admin-level permissions) or the Root user option, and enter your credentials.

3. From the top navigation bar, select the region dropdown and select a region that you'll create the KMS key in, for example, eu-central-1 for Europe.

4. On your dashboard, search for CloudFormation.

5. From the search results, hover on CloudFormation and select Stacks from the list of top features, or select CloudFormation, then select Stacks from the side menu.

6. On the Stacks screen, select the Create stack dropdown menu in the right corner, then select with new resources (standard).

7. On the subsequent Create stack screen, ensure Prerequisite - Prepare template box has Choose an existing template selected.

8. Specify the Amazon S3 URL as: https://cmk-atlassian.s3.us-east-1.amazonaws.com/latest/atlassian-isolated-cmk-key-template-cf.json, then select Next. It will take you to the Specify stack details screen.

9. Go to Specify stack details > Provide a stack name > Stack name, and enter atlassian-cmk-key or optionally any preferred name that you’d like to use to identify the stack.

   1. Under Parameters > AliasName, enter atlassian-cmk-key or any other name that you’d like to identify the key via a KMS key alias.

   2. Under Parameters > OrganisationalUnits, enter the OrgPath provided by your Atlassian Isolated Cloud contact. Select Next. It will take you to the Configure stack options screen.

   3. [Optional] Under Configure stack options > Tags - optional, you can enter new tags to the KMS key created by this stack.

   4. Under the Configure stack options > Stack failure options, select Roll back all stack resources and Use Deletion Policy, then select Next. It will take you to the Review and create screen.

10. Review all entries again, then select Submit.

11. Once completed (it may take a few minutes), the state of the newly created stack will automatically change from CREATE_IN_PROGRESS to CREATE_COMPLETE and the KMS key will be set up. To verify it, search for Key Management Service on your dashboard and select it. Then select Customer managed keys from the sidebar and check for the atlassian-cmk-key or the name that you used as the AliasName earlier.

12. Select the key you’ve created, then copy the AWS ARN of the key and note it down for later.

If you haven’t created one key per region in your chosen realm, repeat the steps for the other region.

Method 2: Set up via manual key creation and policy application

1. Go to Cloud Computing Services - Amazon Web Services (AWS) and sign into your account.

2. Select the IAM user option (with admin-level permissions) or the Root user option, and enter your credentials.

3. From the top navigation bar, select the region dropdown and select a region that you’ll create the KMS key in, for example, eu-central-1 for Europe.

4. On your dashboard, search for Key management service.

5. From the search results, hover on Key management service and select Customer managed keys.

6. From the Customer managed keys screen, select Create key.

7. Ensure the Key type is Symmetric, and the Key usage is Encrypt and decrypt.

8. Select to expand Advanced options.

9. Ensure Key material origin is “KMS - recommended” and the Regionality is Single-region key.

10. Select Next. This will take you to the Add labels screen.

11. Under Add labels, then Alias, enter atlassian-cmk-key or any other name that you’d like to use to identify the key via a KMS key alias.

12. [Optional] Add a Description and/or Tags, then select Next on subsequent screens until you reach the Edit key policy screen.

13. Under Edit key policy > Key policy, select Edit to copy and paste the contents of the sample JSON: https://cmk-atlassian.s3.us-east-1.amazonaws.com/latest/atlassian-isolated-cmk-key-template.json. Replace all sample values as detailed in the following steps. You'll notice all the values to be replaced have their line numbers highlighted in red once you paste the template in the AWS Console.

    1. Under the EnableRoleDelegation statement, replace AWSACCOUNTID with your AWS account ID (with no separators between numbers). This is crucial for enabling IAM roles in your account to have access to this key (including your admin role). If you enter an invalid AWSACCOUNTID, the key will fail to create.

    2. Replace the AWSREGION placeholders in the AwsManagedService section and in the AtlassianRdsPerformanceInsightsUsage section with the AWS region of the KMS Key. For example, if the KMS key is created in us-east-1, then the AWSREGION placeholders should be replaced with “us-east-1”.

    3. Replace the OrganisationalUnits parameter in the AwsManagedService section and in the AtlassianRdsPerformanceInsightsUsage section with the OrgPath for the Isolated Context. An example of an OrgPath is o-rab3nm4fez/*/<isolatedContextOU>/*.

14. Review all the settings are in alignment with the steps taken previously, then select Finish.

15. Select the key you’ve created, then copy the AWS ARN of the key and note it down for later.

If you haven’t created one key per region in your chosen realm, repeat the steps for the other region.

Next step

Once you've set up your AWS account and created KMS keys and your provisional key policy, we’ll enrol your AWS Key Management Service (KMS) keys in the CMK encryption policy of your organization and provision the requested app instances to your plan.