Secrets

SubImage handles credentials for integrations two ways. Every secret field in a module form has an AWS ARN / Secret toggle — pick whichever fits your organization.

Option 1 — Managed vault

No setup required.

1. In the module form, switch the field to Secret.
2. Paste the credential value.
3. Save the module.

SubImage stores the value encrypted and scoped to your tenant. To rotate, repeat steps 1–3 with the new value.

Option 2 — AWS ARN

Each secret lives in your own AWS Secrets Manager. SubImage assumes a cross-account role named SubImageSecretsRole at sync time to read it.

Step 1. Register the account with SubImage

In Settings → Configuration, set SubImage Secrets Account to the 12-digit AWS account ID that will own the secrets. SubImage also generates an External ID — recommended for the trust policy below, but not required for access to work. If the account was already registered and no ID is shown, select Generate external ID.

Step 2. Deploy SubImageSecretsRole

Deploy the role in the AWS account that will own the secrets (typically a dedicated security-tools account). The trust policy only allows sts:AssumeRole from the SubImage principal for your tenant.

Use <EXTERNAL_ID_FROM_SUBIMAGE> from Step 1 as the sts:ExternalId value below. SubImage sends it on every assume. The condition is recommended (confused-deputy protection); roles without it keep working until you add it.

Option A — CloudFormation

AWSTemplateFormatVersion: "2010-09-09"
Description: IAM Role and Policy for SubImage to retrieve customer-owned secrets

Resources:
  SubImageSecretsRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: SubImageSecretsRole
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS:
                - arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: "<EXTERNAL_ID_FROM_SUBIMAGE>"

  AllowSubImageSecretsAccess:
    Type: AWS::IAM::Policy
    Properties:
      PolicyName: AllowSubImageSecretsAccess
      Roles:
        - !Ref SubImageSecretsRole
      PolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Action:
              - secretsmanager:GetSecretValue
              - secretsmanager:DescribeSecret
            Resource:
              # Adjust if you do not want to prefix SubImage secrets with "subimage/"
              - arn:aws:secretsmanager:*:<ACCOUNT_WITH_SECRETS>:secret:subimage/*

Outputs:
  SubImageSecretsRoleArn:
    Description: ARN of the created SubImage secrets IAM Role.
    Value: !GetAtt SubImageSecretsRole.Arn

Option B — Terraform

resource "aws_iam_role" "subimage_secrets" {
  name = "SubImageSecretsRole"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Principal = {
        AWS = [
          "arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly",
        ]
      }
      Action = "sts:AssumeRole"
      Condition = {
        StringEquals = {
          "sts:ExternalId" = "<EXTERNAL_ID_FROM_SUBIMAGE>"
        }
      }
    }]
  })
}

resource "aws_iam_role_policy" "subimage_secrets" {
  name = "AllowSubImageSecretsAccess"
  role = aws_iam_role.subimage_secrets.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret",
      ]
      Resource = [
        "arn:aws:secretsmanager:*:<ACCOUNT_WITH_SECRETS>:secret:subimage/*",
      ]
    }]
  })
}

output "subimage_secrets_role_arn" {
  value = aws_iam_role.subimage_secrets.arn
}

Step 3. Store a secret and reference it by ARN

For each credential:

1. In AWS Secrets Manager, create a new secret of type Other type of secret → Plaintext and paste only the raw value (no JSON wrapping).
2. Copy the Secret ARN.
3. In the module form, keep the field on AWS ARN and paste the ARN.