IAM Aliases

Lists AWS account(s) with their IAM account aliases.

Sync Type: Full

Requirements

This input requires IAM roles to be configured in each AWS account you want to monitor. The roles must allow Monad to assume them and have permissions to list IAM account aliases.

Step 1: Create IAM Role in Each Account

Create an IAM role named monad-iam-aliases-reader (or your preferred name) in each target AWS account with the following configuration:

Required IAM Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListAccountAliases",
      "Effect": "Allow",
      "Action": ["iam:ListAccountAliases"],
      "Resource": "*"
    }
  ]
}

Trust Relationship:

For details on configuring the trust relationship, see IAM Role Assumption / Static Credentials.

Step 2: Programmatically Create Roles Across Multiple Accounts (Optional)

If you need to create the same role across many AWS accounts, you can use AWS CloudFormation StackSets or a script. Here's a CloudFormation template:

CloudFormation Template (iam-aliases-role.yaml):

AWSTemplateFormatVersion: "2010-09-09"
Description: "IAM Role for Monad IAM Aliases Input"

Parameters:
  MonadOrganizationId:
    Type: String
    Description: Your Monad Organization ID for External ID validation
    AllowedPattern: ".+"

  RoleName:
    Type: String
    Default: monad-iam-aliases-reader
    Description: Name of the IAM role to create

Resources:
  MonadIAMAliasesRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Ref RoleName
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Sid: AssumeRoleWithExternalId
            Effect: Allow
            Principal:
              AWS: arn:aws:iam::339712996529:role/monad-app
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !Ref MonadOrganizationId
          - Sid: TagSession
            Effect: Allow
            Principal:
              AWS: arn:aws:iam::339712996529:role/monad-app
            Action: sts:TagSession
      ManagedPolicyArns: []
      Policies:
        - PolicyName: IAMAliasesReadPolicy
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Sid: ListAccountAliases
                Effect: Allow
                Action:
                  - iam:ListAccountAliases
                Resource: "*"
      Tags:
        - Key: ManagedBy
          Value: Monad
        - Key: Purpose
          Value: IAM-Aliases-Collection

Outputs:
  RoleArn:
    Description: ARN of the created IAM role
    Value: !GetAtt MonadIAMAliasesRole.Arn
    Export:
      Name: !Sub "${AWS::StackName}-RoleArn"

Deploy using AWS CloudFormation StackSets:

# Create StackSet
aws cloudformation create-stack-set \
  --stack-set-name monad-iam-aliases-roles \
  --template-body file://iam-aliases-role.yaml \
  --parameters ParameterKey=MonadOrganizationId,ParameterValue=YOUR_ORG_ID \
  --capabilities CAPABILITY_NAMED_IAM \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false

# Deploy to specific accounts
aws cloudformation create-stack-instances \
  --stack-set-name monad-iam-aliases-roles \
  --accounts 123456789012 234567890123 345678901234 \
  --regions us-east-1

Alternative: Bash Script for Multiple Accounts:

#!/bin/bash
# deploy-iam-roles.sh

MONAD_ORG_ID="your-monad-org-id"
ROLE_NAME="monad-iam-aliases-reader"
ACCOUNTS=("123456789012" "234567890123" "345678901234")

for ACCOUNT_ID in "${ACCOUNTS[@]}"; do
  echo "Creating role in account $ACCOUNT_ID..."

  # Assume a role in the target account (requires OrganizationAccountAccessRole or similar)
  aws cloudformation create-stack \
    --stack-name monad-iam-aliases-role \
    --template-body file://iam-aliases-role.yaml \
    --parameters ParameterKey=MonadOrganizationId,ParameterValue=$MONAD_ORG_ID \
                 ParameterKey=RoleName,ParameterValue=$ROLE_NAME \
    --capabilities CAPABILITY_NAMED_IAM \
    --region us-east-1 \
    --profile "account-$ACCOUNT_ID"  # Use appropriate AWS CLI profile

  echo "Role creation initiated for account $ACCOUNT_ID"
done

Step 3: Verify Role Creation

After creating the roles, verify they exist and are properly configured:

# Test role assumption from your local environment
aws sts assume-role \
  --role-arn "arn:aws:iam::123456789012:role/monad-iam-aliases-reader" \
  --role-session-name "test-session" \
  --external-id "your-monad-org-id"

# List account alias using assumed role credentials
aws iam list-account-aliases \
  --profile assumed-role-profile

Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

Settings

Setting	Type	Required	Description
Cron	string	Yes	Cron expression for scheduling the input (e.g., 0 */6 * * * for every 6 hours)
Accounts	array	Yes	List of AWS accounts to fetch IAM aliases from. Each account requires an account ID and the name of an IAM role that Monad can assume to access IAM data.

Accounts array items:

Field	Type	Required	Description
Account ID	string	Yes	The 12-digit AWS account ID
Role Name	string	Yes	Name of the IAM role to assume for accessing IAM aliases in this account

Secrets

This input uses IAM role authentication and does not require additional secrets.

Troubleshooting

Access Denied Errors

Symptoms: AccessDenied or failed to assume role errors

Solutions:

• Verify the IAM role exists in the target account
• Check the role's trust policy allows Monad to assume it
• Ensure the role has iam:ListAccountAliases permission
• Verify the account ID is correct (12 digits)
• Check if the role name matches exactly (case-sensitive)

Empty Results

Symptoms: No data returned for an account

Solutions:

• The account may not have an IAM alias configured (this is normal)
• Check AWS console to verify if an alias exists: IAM Dashboard → Account Alias
• Verify you have permissions to view the alias
• AWS allows only one alias per account; if none is configured, the result will be empty

Role Assumption Failures

Symptoms: STS AssumeRole errors or timeout errors

Solutions:

• Verify the external ID matches your Monad organization ID
• Check that the trust policy is correctly configured
• Ensure STS endpoints are accessible from your network
• Verify the role ARN format: arn:aws:iam::<account-id>:role/<role-name>
• Check CloudTrail logs for more details on the failure

Connection Timeouts

Symptoms: Timeout errors or slow responses

Solutions:

• Check network connectivity to AWS endpoints
• Verify security groups/firewall rules allow HTTPS (443) to AWS
• Consider increasing timeout settings if processing many accounts
• Check AWS service health dashboard for regional issues

CloudFormation StackSet Deployment Issues

Symptoms: StackSet creation or instance deployment fails

Solutions:

• Service-Managed Permissions: Ensure your organization has enabled CloudFormation StackSets with service-managed permissions
• Enable Trusted Access: Run aws organizations enable-aws-service-access --service-principal stacksets.cloudformation.amazonaws.com
• OU Permissions: Verify the management account has permissions to deploy to target OUs
• Account Access: For self-managed StackSets, ensure AWSCloudFormationStackSetExecutionRole exists in target accounts
• Regional Availability: CloudFormation StackSets must be created in a region that supports the feature

Role Name Inconsistencies

Symptoms: Some accounts work while others fail with "role not found" errors

Solutions:

• Verify the role name is exactly the same in all accounts (case-sensitive)
• Check that the role was successfully created in each target account
• Use AWS CloudFormation StackSets to ensure consistent deployment
• Run the verification script to test all accounts:

for account in 123456789012 234567890123; do
  echo "Testing account $account..."
  aws sts assume-role \
    --role-arn "arn:aws:iam::$account:role/monad-iam-aliases-reader" \
    --role-session-name "verify" \
    --external-id "your-org-id" \
    --profile default || echo "FAILED: $account"
done

Related Articles

• AWS IAM Account Aliases
• AWS STS AssumeRole
• IAM Service Quotas

Sample Record

{
  "AccountID": "123456789012",
  "Alias": "Production Account"
}

Sample Record Fields

• AccountID: The 12-digit AWS account ID
• Alias: Descriptive name of the AWS account