Skip to main content

Prerequisites — cross-account IAM role

Openbox provisions in your AWS account via a customer-created IAM role that trusts Openbox's provisioning account. Openbox never receives long-lived credentials.

Step 1 — Confirm Openbox's principal ARN​

Openbox will give you a principal ARN of the form:

arn:aws:iam::<openbox-provisioning-account-id>:role/openbox-provisioning

Openbox rotates this per engagement — do not hard-code from an old runbook.

Step 2 — Create the trust role​

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowOpenboxProvisioningToAssume",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<openbox-provisioning-account-id>:role/openbox-provisioning"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<random-external-id-you-generate>"
        }
      }
    }
  ]
}

Set the ExternalId to something random (Openbox will use it — coordinate on the exact value out-of-band). This defends against the confused-deputy problem.

Step 3 — Attach minimum permissions​

The role needs enough permissions to run the Terraform snippets Openbox will apply. Recommended: attach the AWS-managed PowerUserAccess policy for the initial terraform apply, then downgrade to a scoped custom policy for day-2.

Scoped custom policy (attach after initial provisioning):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "eks:*",
        "ec2:Describe*",
        "iam:GetRole",
        "iam:PassRole",
        "s3:*Object",
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:GenerateDataKey",
        "rds:Describe*",
        "cloudwatch:GetMetricData",
        "logs:GetLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

Openbox will help scope tighter if your compliance program requires per-resource ARNs.

Step 4 — Share with Openbox​

Provide these to Openbox via a secure channel (encrypted email, SSO'd file share — your call, Openbox does not dictate the medium):

  • Account ID: <12-digit AWS account>
  • Role ARN: arn:aws:iam::<your-account>:role/openbox-provisioning-role
  • ExternalId: <value from step 2>
  • Region(s) where OpenBox should provision
  • VPC layout preference: dedicated VPC (recommended) OR reuse existing VPC by ID

Rotation​

  • Rotate ExternalId if compromise suspected (Openbox re-provisions with new value)
  • Openbox rotates its provisioning principal quarterly — you must update the trust policy each rotation
  • Openbox will send 14-day advance notice before each rotation

Break-glass​

The role remains under your control. To sever Openbox access in an emergency, remove the AllowOpenboxProvisioningToAssume statement from the trust policy — takes effect within seconds.

Handoff & SLA →