@aws-cdk/iam

AWS IAM Construct Library

Define a role and add permissions to it. This will automatically create and attach an IAM policy to the role:

const role = new Role(this, 'MyRole', {
  assumedBy: new ServicePrincipal('sns.amazonaws.com')
});
role.addPermission(new Permission('*', 'lambda:InvokeFunction'));

Define a policy and attach it to groups, users and roles. Note that it is possible to attach the policy either by calling xxx.attachPolicy(policy) or policy.attachToXxx(xxx).

const user = new User(this, 'MyUser', { password: '1234' });
const group = new Group(this, 'MyGroup');

const policy = new Policy(this, 'MyPolicy');
policy.attachToUser(user);
group.attachPolicy(policy);

Managed policies can be attached using xxx.attachManagedPolicy(arn):

const group = new Group(this, 'MyGroup');
group.attachManagedPolicy('arn:aws:iam::aws:policy/AdministratorAccess');

Features

  • Policy name uniqueness is enforced. If two policies by the same name are attached to the same principal, the attachment will fail.
  • Policy names are not required - the CDK logical ID will be used and ensured to be unique.

Reference

Group

class _aws-cdk_iam.Group(parent, name[, props])
Extends:

Construct

Implements:

IIdentityResource

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (GroupProps or None) –
attachManagedPolicy(arn)

Attaches a managed policy to this group.

Parameters:arn (any) – The ARN of the managed policy to attach.
attachInlinePolicy(policy)

Attaches a policy to this group.

Parameters:policy (Policy) – The policy to attach.
addUser(user)

Adds a user to this group.

Parameters:user (User) –
addToPolicy(statement)

Adds an IAM statement to the default policy.

Parameters:statement (PolicyStatement) –
groupName

The runtime name of this group.

Type:GroupName (readonly)
groupArn

The ARN of this group.

Type:GroupArn (readonly)
principal

An “AWS” policy principal that represents this group.

Type:PolicyPrincipal (readonly)

GroupName

class _aws-cdk_iam.GroupName([valueOrFunction])
Extends:Token
Parameters:valueOrFunction (any or None) –

GroupProps (interface)

class _aws-cdk_iam.GroupProps
groupName

A name for the IAM group. For valid values, see the GroupName parameter for the CreateGroup action in the IAM API Reference. If you don’t specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the group name. If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template’s capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Type:string or None
managedPolicyArns

A list of ARNs for managed policies associated with group.

Type:any or None
path

The path to the group. For more information about paths, see [IAM Identifiers](http://docs.aws.amazon.com/IAM/latest/UserGuide/index.html?Using_Identifiers.html) in the IAM User Guide.

Type:string or None

IIdentityResource (interface)

class _aws-cdk_iam.IIdentityResource
principal

The IAM principal of this identity (i.e. AWS principal, service principal, etc).

Type:PolicyPrincipal (readonly)
addToPolicy(statement)

Adds an IAM statement to the default inline policy associated with this principal. If a policy doesn’t exist, it is created.

Parameters:statement (PolicyStatement) –
attachInlinePolicy(policy)

Attaches an inline policy to this principal. This is the same as calling policy.addToXxx(principal).

Parameters:policy (Policy) – The policy resource to attach to this principal.
attachManagedPolicy(arn)

Attaches a managed policy to this principal.

Parameters:arn (any) – The ARN of the managed policy

Policy

class _aws-cdk_iam.Policy(parent, name[, props])

The AWS::IAM::Policy resource associates an IAM policy with IAM users, roles, or groups. For more information about IAM policies, see [Overview of IAM Policies](http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html) in the IAM User Guide guide.

Extends:

Construct

Implements:

IDependable

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (PolicyProps or None) –
addStatement(statement)

Adds a statement to the policy document.

Parameters:statement (PolicyStatement) –
attachToUser(user)

Attaches this policy to a user.

Parameters:user (User) –
attachToRole(role)

Attaches this policy to a role.

Parameters:role (Role) –
attachToGroup(group)

Attaches this policy to a group.

Parameters:group (Group) –
validate() → string[]

This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.

Return type:string
document

The policy document.

Type:PolicyDocument (readonly)
policyName

The name of this policy.

Type:string (readonly)
dependencyElements

Lists all the elements consumers should “depend-on”.

Type:IDependable (readonly)

PolicyProps (interface)

class _aws-cdk_iam.PolicyProps
policyName

The name of the policy. If you specify multiple policies for an entity, specify unique names. For example, if you specify a list of policies for an IAM role, each policy must have a unique name.

Type:string or None
users

Users to attach this policy to. You can also use attachToUser(user) to attach this policy to a user.

Type:User or None
roles

Roles to attach this policy to. You can also use attachToRole(role) to attach this policy to a role.

Type:Role or None
groups

Groups to attach this policy to. You can also use attachToGroup(group) to attach this policy to a group.

Type:Group or None
statements

Initial set of permissions to add to this policy document. You can also use addPermission(statement) to add permissions later.

Type:PolicyStatement or None

Role

class _aws-cdk_iam.Role(parent, name, props)

IAM Role Defines an IAM role. The role is created with an assume policy document associated with the specified AWS service principal defined in serviceAssumeRole.

Extends:

Construct

Implements:

IIdentityResource

Implements:

IDependable

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (RoleProps) –
addToPolicy(statement)

Adds a permission to the role’s default policy document. If there is no default policy attached to this role, it will be created.

Parameters:statement (PolicyStatement) –
attachManagedPolicy(arn)

Attaches a managed policy to this role.

Parameters:arn (any) – The ARN of the managed policy to attach.
attachInlinePolicy(policy)

Attaches a policy to this role.

Parameters:policy (Policy) – The policy to attach
assumeRolePolicy

The assume role policy document associated with this role.

Type:PolicyDocument or None (readonly)
roleArn

Returns the ARN of this role.

Type:RoleArn (readonly)
roleName

Returns the name of the role.

Type:RoleName (readonly)
principal

Returns the ARN of this role.

Type:PolicyPrincipal (readonly)
dependencyElements

Returns the role.

Type:IDependable (readonly)

RoleName

class _aws-cdk_iam.RoleName([valueOrFunction])
Extends:Token
Parameters:valueOrFunction (any or None) –

RoleProps (interface)

class _aws-cdk_iam.RoleProps
assumedBy

The IAM principal (i.e. new ServicePrincipal(‘sns.amazonaws.com’)) which can assume this role. You can later modify the assume role policy document by accessing it via the assumeRolePolicy property.

Type:PolicyPrincipal
managedPolicyArns

A list of ARNs for managed policies associated with this role. You can add managed policies later using addManagedPolicy(arn).

Type:any or None
path

The path associated with this role. For information about IAM paths, see Friendly Names and Paths in IAM User Guide.

Type:string or None
roleName

A name for the IAM role. For valid values, see the RoleName parameter for the CreateRole action in the IAM API Reference. If you don’t specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the group name. IMPORTANT: If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name. If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template’s capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Type:string or None

User

class _aws-cdk_iam.User(parent, name[, props])
Extends:

Construct

Implements:

IIdentityResource

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (UserProps or None) –
addToGroup(group)

Adds this user to a group.

Parameters:group (Group) –
attachManagedPolicy(arn)

Attaches a managed policy to the user.

Parameters:arn (any) – The ARN of the managed policy to attach.
attachInlinePolicy(policy)

Attaches a policy to this user.

Parameters:policy (Policy) –
addToPolicy(statement)

Adds an IAM statement to the default policy.

Parameters:statement (PolicyStatement) –
userName

An attribute that represents the user name.

Type:UserName (readonly)
userArn

An attribute that represents the user’s ARN.

Type:UserArn (readonly)
principal

Returns the ARN of this user.

Type:PolicyPrincipal (readonly)

UserName

class _aws-cdk_iam.UserName([valueOrFunction])
Extends:Token
Parameters:valueOrFunction (any or None) –

UserProps (interface)

class _aws-cdk_iam.UserProps
groups

Groups to add this user to. You can also use addToGroup to add this user to a group.

Type:Group or None
managedPolicyArns

A list of ARNs for managed policies attacherd to this user. You can use addManagedPolicy(arn) to attach a managed policy to this user.

Type:any or None
path

The path for the user name. For more information about paths, see IAM Identifiers in the IAM User Guide.

Type:string or None
userName

A name for the IAM user. For valid values, see the UserName parameter for the CreateUser action in the IAM API Reference. If you don’t specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the user name. If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name. If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template’s capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Type:string or None
password

The password for the user. This is required so the user can access the AWS Management Console.

Type:string or None
passwordResetRequired

Specifies whether the user is required to set a new password the next time the user logs in to the AWS Management Console. If this is set to ‘true’, you must also specify “initialPassword”.

Type:boolean or None