Secrets

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.

Managed vault AWS ARN
AWS setup none one-time: deploy an IAM role
Where the value lives Subimage's vault your AWS account
Rotation update in Subimage update the secret value in AWS (ARN unchanged)
Best for fast onboarding orgs that centralize secrets in AWS

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.

For a new role, return to Settings → Configuration after saving the account and select Deploy SubImageSecretsRole. The CloudFormation link pre-fills this deployment's IAM principal and the generated external ID. If the role already belongs to a stack, update that stack's trust policy instead of creating another stack with the same role name.

Option A — CloudFormation

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

Parameters:
  TrustedPrincipalArns:
    Type: CommaDelimitedList
    Default: "arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly"
    Description: IAM role ARNs for the SubImage deployments allowed to assume this role.
  ExternalId:
    Type: String
    Default: "<EXTERNAL_ID_FROM_SUBIMAGE>"
    Description: Optional SubImage-generated external ID for confused-deputy protection.
  RoleName:
    Type: String
    Default: SubImageSecretsRole
    Description: Name of the customer-side IAM role SubImage assumes.
    AllowedPattern: '^[\w+=,.@-]{1,64}$'
  SecretNamePrefix:
    Type: String
    Default: subimage/
    Description: Secrets Manager name prefix SubImage can read.

Conditions:
  HasExternalId: !Not [!Equals [!Ref ExternalId, ""]]

Resources:
  SubImageSecretsRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Ref RoleName
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS: !Ref TrustedPrincipalArns
            Action: sts:AssumeRole
            Condition: !If
              - HasExternalId
              - StringEquals:
                  sts:ExternalId: !Ref ExternalId
              - !Ref AWS::NoValue

  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:
              - !Sub arn:${AWS::Partition}:secretsmanager:*:${AWS::AccountId}:secret:${SecretNamePrefix}*

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

Option B — Terraform

variable "trusted_principal_arns" {
  description = "IAM role ARNs for the SubImage deployments allowed to assume this role."
  type        = list(string)
  default     = ["arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly"]
}

variable "external_id" {
  description = "Optional SubImage-generated external ID for confused-deputy protection."
  type        = string
  default     = "<EXTERNAL_ID_FROM_SUBIMAGE>"
  nullable    = true
}

variable "role_name" {
  description = "Name of the customer-side IAM role SubImage assumes."
  type        = string
  default     = "SubImageSecretsRole"
}

variable "secret_name_prefix" {
  description = "Secrets Manager name prefix SubImage can read."
  type        = string
  default     = "subimage/"
}

data "aws_caller_identity" "current" {}

resource "aws_iam_role" "subimage_secrets" {
  name = var.role_name

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      merge({
        Effect = "Allow"
        Principal = {
          AWS = var.trusted_principal_arns
        }
        Action = "sts:AssumeRole"
        }, var.external_id == null || var.external_id == "" ? {} : {
        Condition = {
          StringEquals = {
            "sts:ExternalId" = var.external_id
          }
        }
      })
    ]
  })
}

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:*:${data.aws_caller_identity.current.account_id}:secret:${var.secret_name_prefix}*"
        ]
      }
    ]
  })
}

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

Tighten the Resource list to specific secret ARNs if you want to further limit what Subimage can read.

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.