Getting Started
Getting Started
Give Atlassian Cloud an AWS KMS key whose material stays in DuoKey
Overview
You will deploy the DuoKey XKS proxy, create an external key store and an XKS-backed KMS key in your AWS account with Atlassian's key policy, then enroll that key in Atlassian Administration. Repeat the key steps for each region of a dual-region realm.
Architecture
What you are setting up
Your AWS account holds an external key store and an XKS-backed KMS key; DuoKey holds the key material behind it.
Prerequisites
- Atlassian organization admin rights, and a plan where CMK is available (see Atlassian CMK page)
- A dedicated AWS account for the KMS keys used by your Atlassian cloud apps
- The Atlassian realm chosen, and its AWS region(s): one key per region
- DuoKey Cockpit with the AWS XKS app and an MPC vault (or HSM) for the key
- AWS CLI v2 with permissions to create custom key stores and KMS keys in that account
Step-by-step guide
Deploy the DuoKey XKS proxy for high availability
Deploy the XKS endpoint from the Cockpit (Apps, AWS XKS) as described in AWS XKS Getting Started. For Atlassian, use the high-availability pattern: Atlassian suspends its sites when it loses access to the key, so the proxy must answer AWS KMS within 250 ms from every region of the realm.
- Create an AES-256 key in the MPC vault for each region of the realm.
- Note each External Key ID, the proxy URI endpoint and path, and the SigV4 access key pair.
- Check that the proxy health endpoint answers.
Create and connect the external key store
In each region of the realm, create an external key store that points to the DuoKey proxy, then connect it.
REGION=eu-central-2 # the Atlassian realm region
aws kms create-custom-key-store --region $REGION \
--custom-key-store-name "duokey-xks-atlassian" \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-uri-endpoint "https://<your-duokey-xks-host>" \
--xks-proxy-uri-path "/xks/<prefix>/kms/xks/v1" \
--xks-proxy-connectivity PUBLIC_ENDPOINT \
--xks-proxy-authentication-credential \
AccessKeyId=<sigv4-access-key-id>,RawSecretAccessKey=<sigv4-secret>
KEYSTORE_ID=$(aws kms describe-custom-key-stores --region $REGION \
--custom-key-store-name "duokey-xks-atlassian" \
--query 'CustomKeyStores[0].CustomKeyStoreId' --output text)
aws kms connect-custom-key-store --region $REGION --custom-key-store-id $KEYSTORE_ID
# Wait until ConnectionState is CONNECTED
aws kms describe-custom-key-stores --region $REGION --custom-key-store-id $KEYSTORE_ID \
--query 'CustomKeyStores[0].ConnectionState'
Prepare Atlassian's key policy
Download Atlassian's key policy template and replace the two placeholders with your AWS account ID and the key's region. The template grants Atlassian kms:CreateGrant for its services (RDS, OpenSearch, EBS), grant management, kms:DescribeKey, and keeps full control for your account through the EnableRoleDelegation statement.
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
curl -s https://cmk-atlassian.s3.amazonaws.com/latest/atlassian-cmk-key-template.json \
| sed -e "s/\${AWS::AccountId}/$ACCOUNT_ID/g" -e "s/\${AWS::Region}/$REGION/g" \
> atlassian-cmk-policy-$REGION.json
Use this manual path, not Atlassian's CloudFormation template. The CloudFormation template sets EnableKeyRotation: true, and AWS KMS does not support automatic rotation for keys in an external key store.
Create the XKS-backed KMS key
Create a symmetric, single-Region key in the external key store, linked to the DuoKey External Key ID, with Atlassian's policy attached. Add an alias so the key is easy to find.
KEY_ARN=$(aws kms create-key --region $REGION \
--origin EXTERNAL_KEY_STORE \
--custom-key-store-id $KEYSTORE_ID \
--xks-key-id "<duokey-external-key-id>" \
--description "Atlassian CMK key (DuoKey XKS)" \
--policy file://atlassian-cmk-policy-$REGION.json \
--query KeyMetadata.Arn --output text)
aws kms create-alias --region $REGION \
--alias-name alias/atlassian-cmk-key --target-key-id $KEY_ARN
# Check: Origin EXTERNAL_KEY_STORE, KeySpec SYMMETRIC_DEFAULT, MultiRegion false
aws kms describe-key --region $REGION --key-id $KEY_ARN \
--query 'KeyMetadata.[Origin,KeySpec,KeyUsage,MultiRegion,KeyState]'
echo $KEY_ARN
Run a test encryption with your own role before enrolling (aws kms encrypt --key-id $KEY_ARN --plaintext fileb://test.txt). The request should appear in the DuoKey journal within seconds.
Enroll the key in Atlassian Administration
- Go to Atlassian Administration and select your organization.
- Select Security, then Data protection, then Encryption.
- Select Set up CMK encryption, then Begin.
- Enter the AWS account ID that holds the keys.
- Select the region (realm). The KMS keys and the app data are co-located, and the data cannot be migrated out of the realm later.
- Enter the key ARN(s): two for a dual-region realm, one otherwise.
- Create the context tag: up to 12 alphanumeric characters. It cannot be changed once it takes effect.
- Select Enroll in CMK encryption.
If you find an error after enrollment, contact Atlassian Support before provisioning the first CMK-enabled app: recovery options become more limited once an app is provisioned.
Optional: harden the key policy
After enrollment, Atlassian shows the encryption tenant identifier and its VPC endpoint(s) under Security, Encryption, Encryption context & VPCE. You can add conditions on the encryption context and restrict inbound requests to those VPC endpoints. Atlassian supports these two deviations only; other policy changes after provisioning can break the apps.
Verify
- Provision a CMK-enabled app on a new site.
- In CloudTrail, find KMS events on the key with Atlassian's encryption context.
- In the DuoKey Cockpit, check that the XKS requests from AWS KMS appear in the journal for the same key.
Operations
Monitoring
| Where | What to watch |
|---|---|
| AWS CloudTrail | KMS calls on the key with Atlassian encryption context; KMSInvalidStateException errors |
| AWS KMS console | External key store connection state for each region |
| DuoKey Cockpit | XKS proxy health, latency and request journal per key |
| Atlassian Administration | CMK encryption policy status and support tickets sent to the organization admin |
Rotation
Keys in an external key store cannot be rotated automatically by AWS KMS. Rotation means moving the Atlassian CMK policy to a new XKS-backed key: create it with steps 2 to 4, then follow Atlassian's re-encryption process. Do not disable the old key while re-encryption is running.
Revocation and restore
| Action | How | Effect |
|---|---|---|
| Revoke | Disable the KMS key (both regions for a dual-region realm), or block the key in DuoKey | Atlassian suspends the sites, typically within 30 to 60 minutes; up to 1 hour of data loss |
| Restore | Enable the key again, then reply to the Atlassian support ticket | Sites reinstated within 10 days; beyond 20 days full recovery may not be possible |