AWS Secrets Manager

Phase Cloud

To allow Phase Cloud to securely access your AWS Secrets Manager, you need to set up an IAM Role in your AWS account. Phase Cloud will then assume this role using an External ID for added security. The setup involves creating an IAM policy with the necessary permissions, then creating an IAM role that trusts Phase's AWS entity and has this policy attached.

Step 1: Create IAM Policy for Secrets Manager Access (in your AWS account)

This policy grants Phase the specific permissions needed to manage secrets within your AWS Secrets Manager.

1. Run the following AWS CLI command in your terminal. You can customize the policy name (e.g., phase-console-aws-secrets-manager-integration-policy):

aws iam create-policy --policy-name phase-console-aws-secrets-manager-integration-policy --policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowSecretsManagerAccess",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret",
        "secretsmanager:PutSecretValue",
        "secretsmanager:ListSecrets",
        "secretsmanager:CreateSecret",
        "secretsmanager:DeleteSecret",
        "secretsmanager:TagResource",
        "secretsmanager:UpdateSecret"
      ],
      "Resource": "*"
    }
  ]
}'

2. After running the command, AWS will return the policy details. Make a note of the Policy ARN (e.g., arn:aws:iam::YOUR_ACCOUNT_ID:policy/phase-console-aws-secrets-manager-integration-policy). You will need this ARN in Step 3.

Step 2: Obtain External ID from Phase Console

An External ID is a security measure that helps prevent the "confused deputy" problem. You'll generate this in the Phase Console.

1. In the Phase Console, navigate to Integrations (from the sidebar) > Third-party credentials.
2. Click on AWS to create new AWS credentials.
3. Select the Assume Role tab.
4. You will see a field for EXTERNAL ID (Optional). Click the Generate button next to it, as shown in the UI below.
   
5. Copy the generated External ID. You will need this for the trust policy of the IAM role in the next step. Keep this ID secure.

Step 3: Create IAM Role (in your AWS account)

This role will be assumed by Phase Cloud. It needs to trust Phase's AWS role and have the Secrets Manager access policy attached.

1. Prepare the trust policy JSON. Create a file named phase-cloud-trust-policy.json with the following content.
   • Replace YOUR_PHASE_GENERATED_EXTERNAL_ID with the External ID you copied from the Phase Console in Step 2.
   • The Principal.AWS value arn:aws:iam::499502749186:role/PhaseIntegrationTrustAnchor is Phase's designated role ARN that will assume this role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::499502749186:role/PhaseIntegrationTrustAnchor"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_PHASE_GENERATED_EXTERNAL_ID"
        }
      }
    }
  ]
}

Alternatively, if you are using the AWS Console to create this role, please select the Custom trust policy option when selecting the trusted entity and paste the following JSON:

2. Run the following AWS CLI command to create the IAM role. You can customize the role name (e.g., phase-console-aws-secrets-manager-integration):

aws iam create-role --role-name phase-console-aws-secrets-manager-integration --assume-role-policy-document phase-cloud-trust-policy.json

3. After the role is created, AWS will return its details. Make a note of the Role ARN (e.g., arn:aws:iam::YOUR_ACCOUNT_ID:role/phase-console-aws-secrets-manager-integration). This is the ARN you will provide to Phase.

4. Attach the Secrets Manager access policy (created in Step 1) to this new role.

   • Replace phase-console-aws-secrets-manager-integration with your chosen role name if different.
   • Replace YOUR_POLICY_ARN_FROM_STEP_1 with the Policy ARN you noted earlier.

aws iam attach-role-policy --role-name phase-console-aws-secrets-manager-integration --policy-arn YOUR_POLICY_ARN_FROM_STEP_1

Step 4: Configure Credentials in Phase Console

1. Return to the Phase Console where you generated the External ID (Integrations > Third-party credentials > AWS > Assume Role).
2. In the ARN OF ROLE TO BE ASSUMED field, paste the Role ARN of the phase-console-aws-secrets-manager-integration (or your custom name) that you just created in your AWS account (from Step 3.3).
3. The EXTERNAL ID field should already contain the ID you generated in Step 2. Verify it.
4. Select the appropriate AWS Region where your Secrets Manager secrets are or will be stored.
5. Provide a descriptive Name for these credentials in Phase (e.g., "AWS Secrets Manager Assume role integration credentials").
6. Click Save.

Phase is now configured to securely access your AWS Secrets Manager using the Assume Role method.

Self-hosted Phase

To allow your self-hosted Phase instance to securely access AWS Secrets Manager, you need to create a dedicated IAM Role in your AWS account. This role will have permissions to manage secrets in Secrets Manager and will trust the primary IAM principal (Role or User) already configured for your Phase instance.

Step 1: Create IAM Policy for Secrets Manager Access

This policy grants Phase the specific permissions needed to manage secrets within your AWS Secrets Manager. If you've already created a similar policy, you can adapt or reuse it.

1. Define the policy document. Create a file named phase-sm-policy.json with the following content:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowSecretsManagerAccess",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret",
        "secretsmanager:PutSecretValue",
        "secretsmanager:ListSecrets",
        "secretsmanager:CreateSecret",
        "secretsmanager:DeleteSecret",
        "secretsmanager:TagResource",
        "secretsmanager:UpdateSecret"
      ],
      "Resource": "*"
    }
  ]
}

2. Run the following AWS CLI command to create the policy. You can customize the policy name (e.g., phase-console-aws-secrets-manager-integration-policy):

aws iam create-policy \
  --policy-name phase-console-aws-secrets-manager-integration-policy \
  --policy-document file://phase-sm-policy.json

3. After running the command, AWS will return the policy details. Make a note of the Policy ARN (e.g., arn:aws:iam::YOUR_ACCOUNT_ID:policy/phase-console-aws-secrets-manager-integration-policy). You will need this ARN in Step 2.

Step 2: Create IAM Role for Secrets Manager Access

This role will be assumed by your Phase instance's primary AWS integration principal. It needs the Secrets Manager access policy (created in Step 1) attached.

1. Prepare the trust policy JSON. The trust policy must allow your self-hosted Phase instance's primary AWS IAM principal to assume this role. This principal is the IAM Role or User that you configured when setting up the AWS integration for your self-hosted Phase instance.

   Create a file named phase-sm-trust-policy.json with the following content. You will need to replace "<ARN_OF_YOUR_PHASE_INTEGRATION_PRINCIPAL>" with the actual ARN of the IAM role or user that your self-hosted Phase instance uses.

   • If your Phase instance uses IMDSv2 (EC2 Instance Profile Role), the ARN will be like arn:aws:iam::YOUR_ACCOUNT_ID:role/PhaseEC2InstanceRole. Refer to the IMDS setup guide for your specific role name.
   • If your Phase instance uses Kubernetes IRSA (IAM Role for Service Account), the ARN will be like arn:aws:iam::YOUR_ACCOUNT_ID:role/PhaseGlobalAssumeRoleEKS. Refer to the IRSA setup guide for your specific role name.
   • If your Phase instance uses Access Keys (IAM User), the ARN will be like arn:aws:iam::YOUR_ACCOUNT_ID:user/phase-integration-user. Refer to the Access Keys setup guide for your specific user name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<ARN_OF_YOUR_PHASE_INTEGRATION_PRINCIPAL>"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

2. Run the following AWS CLI command to create the IAM role. You can customize the role name (e.g., phase-console-aws-secrets-manager-integration-policy):

aws iam create-role \
  --role-name phase-console-aws-secrets-manager-integration-policy \
  --assume-role-policy-document file://phase-sm-trust-policy.json \
  --description "IAM role for self-hosted Phase to access Secrets Manager"

3. After the role is created, AWS will return its details. Make a note of the Role ARN (e.g., arn:aws:iam::YOUR_ACCOUNT_ID:role/phase-console-aws-secrets-manager-integration-policy). This is the ARN you will provide to your Phase Console.

4. Attach the Secrets Manager access policy (created in Step 1) to this new role.

   • Replace phase-console-aws-secrets-manager-integration-policy with your chosen role name if different.
   • Replace YOUR_POLICY_ARN_FROM_STEP_1 with the Policy ARN you noted earlier.

aws iam attach-role-policy \
  --role-name phase-console-aws-secrets-manager-integration-policy \
  --policy-arn YOUR_POLICY_ARN_FROM_STEP_1

Step 3: Configure Credentials in Phase

1. In your Phase Console, navigate to Integrations (from the sidebar) > Third-party credentials.
2. Click on Add credentials, select AWS to create new AWS credentials (or edit existing ones if appropriate).
3. Select the Assume Role tab.

4. In the ARN OF ROLE TO BE ASSUMED field, paste the Role ARN of the phase-console-aws-secrets-manager-integration-policy (or your custom name) that you just created (from Step 2.3).
5. The EXTERNAL ID field can be left blank. If you using a different AWS account than the one with the integration user, you can generate an External ID in the Phase Console.
6. Select the appropriate AWS Region where your Secrets Manager secrets are or will be stored.
7. Provide a descriptive Name for these credentials in Phase (e.g., "AWS Secrets Manager Self-Hosted Integration").
8. Click Save.