This is the AWS CDK v2 Developer Guide. CDK v1 entered maintenance on June 1, 2022 and will now receive only critical bug fixes and security patches. New features will be developed for CDK v2 exclusively.
Permissions
The AWS Construct Library uses a few common, widely-implemented idioms to manage access and permissions. The IAM module provides you with the tools you need to use these idioms.
Principals
An IAM principal is an entity that can be authenticated in order to access AWS resources, such as a user, a service, or an application. The AWS Construct Library supports many types of principals, including:
-
Service principals (
new iam.ServicePrincipal('service.amazonaws.com')
) -
Federated principals (
new iam.FederatedPrincipal('cognito-identity.amazonaws.com')
) -
Account principals (
new iam.AccountPrincipal('0123456789012'))
-
Canonical user principals (
new iam.CanonicalUserPrincipal('79a59d[...]7ef2be')
) -
AWS organizations principals (
new iam.OrganizationPrincipal('org-id')
) -
Arbitrary ARN principals (
new iam.ArnPrincipal(res.arn)
) -
An
iam.CompositePrincipal(principal1, principal2, ...)
to trust multiple principals
Grants
Every construct that represents a resource that can be accessed, such as an Amazon S3 bucket or
Amazon DynamoDB table, has methods that grant access to another entity. All such methods have names
starting with grant. For example, Amazon S3 buckets have the
methods grantRead
and grantReadWrite
(Python: grant_read
,
grant_read_write
) to enable read and read/write access, respectively, from an
entity to the bucket without having to know exactly which Amazon S3 IAM permissions are required
to perform these operations.
The first argument of a grant method is always of type
IGrantable. This interface represents entities that can be granted
permissions—that is, resources with roles, such as the IAM objects Role
, User
, and
Group
.
Other entities can also be granted permissions. For example, later in this topic, we show
how to grant a CodeBuild project access to an Amazon S3 bucket. Generally, the associated role is
obtained via a role
property on the entity being granted access. Other entities
that can be granted permissions are Amazon EC2 instances and CodeBuild projects.
Resources that use execution roles, such as lambda.Function
, also implement IGrantable
, so you can grant
them access directly instead of granting access to their role. For example, if
bucket
is an Amazon S3 bucket, and function
is a Lambda function, the
code below grants the function read access to the bucket.
Sometimes permissions must be applied while your stack is being deployed. One such case is when you grant a AWS CloudFormation custom resource access to some other resource. The custom resource will be invoked during deployment, so it must have the specified permissions at deployment time. Another case is when a service verifies that the role you pass to it has the right policies applied (a number of AWS services do this to make sure you didn't forget to set the policies). In those cases, the deployment may fail if the permissions are applied too late.
To force the grant's permissions to be applied before another resource is created, you
can add a dependency on the grant itself, as shown here. Though the return value of grant
methods is commonly discarded, every grant method in fact returns an iam.Grant
object.
Roles
The IAM package contains a Role
construct
that represents IAM roles. The following code creates a new role, trusting the Amazon EC2
service.
You can add permissions to a role by calling the role's addToPolicy
method (Python: add_to_policy
), passing in a
PolicyStatement
that defines the rule to be added. The statement is added
to the role's default policy; if it has none, one is created.
The following example adds a Deny
policy statement to the role for the
actions ec2:SomeAction
and s3:AnotherAction
on the resources
bucket
and otherRole
(Python: other_role
), under the
condition that the authorized service is AWS CodeBuild.
In our example above, we've created a new PolicyStatement
inline with the addToPolicy
(Python: add_to_policy
) call. You can also pass
in an existing policy statement or one you've modified. The PolicyStatement
object has numerous
methods for adding principals, resources, conditions, and actions.
If you're using a construct that requires a role to function correctly, you can either pass in an existing role when instantiating the construct object, or let the construct create a new role for you, trusting the appropriate service principal. The following example uses such a construct: a CodeBuild project.
Once the object is created, the role (whether the role passed in or the default one
created by the construct) is available as the property role
. This property is not
available on external resources, however, so such constructs have an
addToRolePolicy
(Python: add_to_role_policy
) method that does
nothing if the construct is an external resource, and calls the addToPolicy
(Python: add_to_policy
) method of the role
property otherwise,
saving you the trouble of handling the undefined case explicitly. The following example
demonstrates:
Resource policies
A few resources in AWS, such as Amazon S3 buckets and IAM roles, also have a resource
policy. These constructs have an addToResourcePolicy
method (Python:
add_to_resource_policy
), which takes a PolicyStatement
as its argument. Every policy statement added to a
resource policy must specify at least one principal.
In the following example, the Amazon S3 bucket
bucket
grants a role with the s3:SomeAction
permission to
itself.
Using external IAM objects
If you have defined an IAM user, principal, group, or role outside your AWS CDK app, you can use that IAM object in your AWS CDK app by creating a reference to it using its ARN or (for users, groups, and roles) its name. The returned reference can then be used to grant permissions or to construct policy statements as explained above.
-
For users, call
User.fromUserArn()
orUser.fromUserName()
.User.fromUserAttributes()
is also available, but currently provides the same functionality asUser.fromUserArn()
. -
For principals, instantiate an
ArnPrincipal
object. -
For groups, call
Group.fromGroupArn()
orGroup.fromGroupName()
. -
For roles, call
Role.fromRoleArn()
orRole.fromRoleName()
.
Policies (including managed policies) can be used in similar fashion using the methods listed below. You can use references to these objects anywhere an IAM policy is required.
As with all references to external AWS resources, you cannot modify external IAM objects in your CDK app.