# 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:**

```json
{
  "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](./index.mdx#authentication-methods).

### 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):**

```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:**

```bash
# 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:**

```bash
#!/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:

```bash
# 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:

```bash
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html)
- [AWS STS AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
- [IAM Service Quotas](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html)

## Sample Record

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

### Sample Record Fields

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

## Sync frequency

This input runs on a cron schedule (default hourly, `0 * * * *`), which you can configure on the pipeline. See [Input Sync Frequency](../../guides/sync-frequency) for details.