Permissions

フォーカスモード

Permissions - AWS Cloud Development Kit (AWS CDK) v1

Principals Grants Roles Resource policies Using external IAM objects

このページはお客様の言語に翻訳されていません。翻訳のリクエスト

This is the AWS CDK v1 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and will now only receive critical bug fixes and security patches. New features will be developed for CDK v2 exclusively. Support for CDK v1 will end entirely on June 1, 2023. Migrate to CDK v2 to have access to the latest features and fixes.

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.

AWS CDK uses AWS CloudFormation to deploy changes. Every deployment involves an actor (either a developer, or an automated system) that starts a AWS CloudFormation deployment. In the course of doing this, the actor will assume one or more IAM Identities (user or roles) and optionally pass a role to AWS CloudFormation.

If you use AWS IAM Identity Center to authenticate as a user, then the single sign-on provider supplies short-lived session credentials that authorize you to act as a pre-defined IAM role. To learn how the AWS CDK obtains AWS credentials from IAM Identity Center authentication, see Understand IAM Identity Center authentication in the AWS SDKs and Tools Reference Guide.

Principals

An IAM principal is an authenticated AWS entity representing a user, service, or application that can call AWS APIs. The AWS Construct Library supports specifying principals in several flexible ways to grant them access your AWS resources.

The AWS Construct Library supports specifying principals in several flexible ways to grant them access your AWS resources. In security contexts, the term "principal" refers specifically to authenticated entities such as users. Objects like groups and roles do not represent users (and other authenticated entities) but rather identify them indirectly for the purpose of granting permissions. For example, if you create an IAM group, you can grant the group (i.e. its members) write access to a Amazon RDS table, but the group itself is not a principal since it does not represent a single entity (also, you cannot log in to a group).

In the CDK's IAM library, classes that directly or indirectly identify principals implement the IPrincipal interface, allowing these objects to be used interchangeably in access policies. However, not all of them are principals in the security sense. These objects include:

Traditional IAM resources such as Role, User, and Group
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.

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.

anchor anchor anchor anchor anchor


bucket.grantRead(function);

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.

anchor anchor anchor anchor anchor


const grant = bucket.grantRead(lambda);
const custom = new CustomResource(...);
custom.node.addDependency(grant);

Roles

The IAM package contains a Role construct that represents IAM roles. The following code creates a new role, trusting the Amazon EC2 service.

anchor anchor anchor anchor anchor


import * as iam from '@aws-cdk/aws-iam';

const role = new iam.Role(this, 'Role', {
  assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),   // required
});

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.

anchor anchor anchor anchor anchor


role.addToPolicy(new iam.PolicyStatement({
  effect: iam.Effect.DENY,
  resources: [bucket.bucketArn, otherRole.roleArn],
  actions: ['ec2:SomeAction', 's3:AnotherAction'],
  conditions: {StringEquals: {
    'ec2:AuthorizedService': 'codebuild.amazonaws.com',
}}}));

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.

TypeScript


import * as codebuild from '@aws-cdk/aws-codebuild';

// imagine roleOrUndefined is a function that might return a Role object
// under some conditions, and undefined under other conditions
const someRole: iam.IRole | undefined = roleOrUndefined();

const project = new codebuild.Project(this, 'Project', {
  // if someRole is undefined, the Project creates a new default role, 
  // trusting the codebuild.amazonaws.com service principal
  role: someRole,
});

JavaScript


const codebuild = require('@aws-cdk/aws-codebuild');

// imagine roleOrUndefined is a function that might return a Role object
// under some conditions, and undefined under other conditions
const someRole = roleOrUndefined();

const project = new codebuild.Project(this, 'Project', {
  // if someRole is undefined, the Project creates a new default role, 
  // trusting the codebuild.amazonaws.com service principal
  role: someRole
});

Python


import aws_cdk.aws_codebuild as codebuild

# imagine role_or_none is a function that might return a Role object
# under some conditions, and None under other conditions
some_role = role_or_none();

project = codebuild.Project(self, "Project",
# if role is None, the Project creates a new default role, 
# trusting the codebuild.amazonaws.com service principal
role=some_role)

Java


import software.amazon.awscdk.services.iam.Role;
import software.amazon.awscdk.services.codebuild.Project;

// imagine roleOrNull is a function that might return a Role object
// under some conditions, and null under other conditions
Role someRole = roleOrNull();

// if someRole is null, the Project creates a new default role, 
// trusting the codebuild.amazonaws.com service principal
Project project = Project.Builder.create(this, "Project")
        .role(someRole).build();

C#


using Amazon.CDK.AWS.CodeBuild;

// imagine roleOrNull is a function that might return a Role object
// under some conditions, and null under other conditions
var someRole = roleOrNull();

// if someRole is null, the Project creates a new default role, 
// trusting the codebuild.amazonaws.com service principal
var project = new Project(this, "Project", new ProjectProps
{
    Role = someRole
});

anchor anchor anchor anchor anchor


import * as codebuild from '@aws-cdk/aws-codebuild';

// imagine roleOrUndefined is a function that might return a Role object
// under some conditions, and undefined under other conditions
const someRole: iam.IRole | undefined = roleOrUndefined();

const project = new codebuild.Project(this, 'Project', {
  // if someRole is undefined, the Project creates a new default role, 
  // trusting the codebuild.amazonaws.com service principal
  role: someRole,
});

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 a reference to 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:

anchor anchor anchor anchor anchor


// project is imported into the CDK application
const project = codebuild.Project.fromProjectName(this, 'Project', 'ProjectName');

// project is imported, so project.role is undefined, and this call has no effect
project.addToRolePolicy(new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,   // ... and so on defining the policy
}));

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.

anchor anchor anchor anchor anchor


bucket.addToResourcePolicy(new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,
  actions: ['s3:SomeAction'],
  resources: [bucket.bucketArn],
  principals: [role]
}));

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() or User.fromUserName(). User.fromUserAttributes() is also available, but currently provides the same functionality as User.fromUserArn().
For principals, instantiate an ArnPrincipal object.
For groups, call Group.fromGroupArn() or Group.fromGroupName().
For roles, call Role.fromRoleArn() or Role.fromRoleName().

Policies (including managed policies) can be referenced in similar fashion using the methods listed below. You can use references to these objects anywhere an IAM policy is required.