IAM Role Examples in AWS CDK - Complete Guide

Table of Contents #

1. Creating IAM Roles in AWS CDK
2. Avoid Circular Dependency with inline Policies and IAM Roles
3. Attach a Managed Policy to an IAM Role after Role Creation
4. Attach an Inline Policy to an IAM Role after Role Creation
5. Add a Principal to an IAM Role after Role Creation
6. Importing Existing IAM Roles in AWS CDK

Creating IAM Roles in AWS CDK #

IAM Roles are collections of policies that grant specific permissions to access resources.

In order to create an IAM Role in AWS CDK we have to use the Role construct.

To demo using IAM Roles in CDK, let's provision a stack that consists of a single IAM role:

Copied!
import * as iam from 'aws-cdk-lib/aws-iam';
import * as cdk from 'aws-cdk-lib';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 👇 Create ACM Permission Policy
    const describeAcmCertificates = new iam.PolicyDocument({
      statements: [
        new iam.PolicyStatement({
          resources: ['arn:aws:acm:*:*:certificate/*'],
          actions: ['acm:DescribeCertificate'],
        }),
      ],
    });

    // 👇 Create Role
    const role = new iam.Role(this, 'example-iam-role', {
      assumedBy: new iam.ServicePrincipal('apigateway.amazonaws.com'),
      description: 'An example IAM role in AWS CDK',
      inlinePolicies: {
        DescribeACMCerts: describeAcmCertificates,
      },
      managedPolicies: [
        iam.ManagedPolicy.fromAwsManagedPolicyName(
          'AmazonAPIGatewayInvokeFullAccess',
        ),
      ],
    });
  }
}

Let's go over what we did in the code snippet:

1. We created an IAM Policy document, named describeAcmCertificates. A Policy Document is a collection of Policy Statements

   In this case, the only Policy Statement we've passed to the document grants DescribeCertificate action permission for Amazon Certificate Manager resources.

2. We created an IAM Role. The props we've passed to the role are:

• assumedBy - the IAM Principal, which can assume the role. In this case this is the API Gateway service.

  We can specify different types of principals, common ones include:

  • ArnPrincipal - specify a principal by the ARN (users, roles, accounts)
  • AccountPrincipal - specify a principal by the AWS account ID (123456789)
  • ServicePrincipal - specify an AWS service as a principal (lambda.amazonaws.com)

• description - a short description of the IAM role

• inlinePolicies - a map of policies that will be inlined into the role. The name of the inline policy is taken from the key of the map, in our case DescribeACMCerts. The inline policies are created with the role, which can sometimes cause circular dependencies. We will see how we can attach policies after role creation later in the article.

• managedPolicies - a list of managed policies to associate with the role

Note that we didn't provide a role name, so a unique name will be automatically generated for us, based on the role's logical ID.

Let's deploy the CDK Stack:

Copied!
npx aws-cdk deploy

The CloudFormation stack has provisioned a single IAM role. The role has 2 Permission policies (policies that describe the permissions of the role):

The role's trust policy (describes who can assume the role) includes the API Gateway service, as we specified in the assumedBy prop:

Avoid Circular dependencies with inline Policies and IAM Roles #

Policies we attach using the inlinePolicies prop on the role are created when the IAM role is created. Depending on the resources we have to reference in the IAM role, this can lead to a circular dependency.

In order to add policies to a role by provisioning a separate CloudFormation resource we have to use the addToPolicy method.

Copied!
import * as iam from 'aws-cdk-lib/aws-iam';
import * as cdk from 'aws-cdk-lib';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ... rest

    // 👇 add an Inline Policy to the Role
    role.addToPolicy(
      new iam.PolicyStatement({
        actions: ['logs:CreateLogGroup', 'logs:CreateLogStream'],
        resources: ['*'],
      }),
    );
  }
}

Let's run the deploy command:

Copied!
npx aws-cdk deploy

After the resources have been provisioned, we can see that our stack now consists of 2 resources - the IAM Role and a separately provisioned IAM Policy:

The policy has also been applied to the IAM role:

Attach a Managed Policy to an IAM Role after Role Creation #

In order to attach a Managed Policy to a role, after we've created the role, we have to use the addManagedPolicy method.

Copied!
import * as iam from 'aws-cdk-lib/aws-iam';
import * as cdk from 'aws-cdk-lib';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ... rest

    // 👇 add a Managed Policy to role
    role.addManagedPolicy(
      iam.ManagedPolicy.fromAwsManagedPolicyName(
        'service-role/AmazonAPIGatewayPushToCloudWatchLogs',
      ),
    );
  }
}

The addManagedPolicy method attaches a managed policy to the role.

When using the fromAwsManagedPolicyName method, we have to provide the name of the managed policy.

However, some managed policy names have a prefix of service-role, job-function, and other managed policy names have no prefix at all. We have to include the managed policy prefix when invoking the fromAwsManagedPolicyName method.

In this case we've included the service-role/ prefix. The easiest way to see if the policy has a prefix is to look at the ARN of the policy:

In the screenshot, we can see that the service-role/ prefix is present in the Policy ARN, therefore we should include it.

After I run the npx aws-cdk deploy command, I can see that the AmazonAPIGatewayPushToCloudWatchLogs managed policy has been attached to the role.

Attach an Inline Policy to an IAM Role after Role Creation #

In order to attach an Inline Policy to an IAM Role after the role has been created, we need to use the attachInlinePolicy method.

Copied!
import * as iam from 'aws-cdk-lib/aws-iam';
import * as cdk from 'aws-cdk-lib';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ... rest

    // 👇 attach an Inline Policy to role
    role.attachInlinePolicy(
      new iam.Policy(this, 'cw-logs', {
        statements: [
          new iam.PolicyStatement({
            actions: ['logs:PutLogEvents'],
            resources: ['*'],
          }),
        ],
      }),
    );
  }
}

We attached an inline IAM Policy that grants a single action to cloudwatch logs resources to the principal of the role.

Let's deploy the changes:

Copied!
npx aws-cdk deploy

The inline policy has been created as a separate CloudFormation resource and it has been attached to the role.

Add a Principal to an IAM Role after Role Creation #

In order to add a Principal to an IAM Role after the role has been created we have to modify the assumeRolePolicy property of the role.

Copied!
import * as iam from 'aws-cdk-lib/aws-iam';
import * as cdk from 'aws-cdk-lib';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ... rest

    // 👇 Add the Lambda service as a Principal
    role.assumeRolePolicy?.addStatements(
      new iam.PolicyStatement({
        actions: ['sts:AssumeRole'],
        effect: iam.Effect.ALLOW,
        principals: [new iam.ServicePrincipal('lambda.amazonaws.com')],
      }),
    );
  }
}

We modified the assume role policy document of the role to allow the lambda service to assume the role.

Let's deploy the changes:

Copied!
npx aws-cdk deploy

If we take a look at the Trust Relationship of the role, we can see that the lambda service has been added as a principal:

If multiple principals are added to a policy, they will be merged together.

Clean up #

To delete the resources we've provisioned, issue the destroy command:

Copied!
npx aws-cdk destroy

Importing Existing IAM Roles in AWS CDK #

In order to import an existing IAM Role in CDK, we have to use the fromRoleArn static method on the Role construct.

Copied!
import * as iam from 'aws-cdk-lib/aws-iam';
import * as cdk from 'aws-cdk-lib';

export class CdkStarterStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 👇 import existing IAM Role
    const importedRole = iam.Role.fromRoleArn(
      this,
      'imported-role',
      `arn:aws:iam::${cdk.Stack.of(this).account}:role/Existing-Role-Name`,
      {mutable: false},
    );

    console.log('importedRole 👉', importedRole.roleName);
  }
}

We used the fromRoleArn method to import an external IAM Role in our CDK stack. The third parameter we passed to the method is the ARN of the IAM role we want to import.

The mutable prop specifies whether the imported role can be modified by attaching policies to it. By default, the mutable prop is set to true.

It doesn't make much sense to import a role and then modify its permissions, so most of the time it's best to avoid this behavior.

If I run the cdk synth command to run the code from the snippet with a role ARN that exists in my account, I can see that the role name is resolved at synthesis time:

Further Reading #

• AWS CDK IAM Policy Example - Complete Guide
• IAM Principal Examples in AWS CDK - Complete Guide
• IAM Condition Examples in AWS CDK - Complete Guide
• Managed Policy Examples in AWS CDK - Complete Guide
• IAM Group Examples in AWS CDK - Complete Guide
• AWS CDK Tutorial for Beginners - Step-by-Step Guide
• What is a Token in AWS CDK
• CDK Constructs - Complete Guide
• How to use Context in AWS CDK
• How to use Parameters in AWS CDK