Namespace Amazon.CDK.AWS.IAM

AWS Identity and Access Management Construct Library

---

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

// Example automatically generated. See https://github.com/aws/jsii/issues/826
Role role = new Role(this, "MyRole", new RoleProps {
    AssumedBy = new ServicePrincipal("sns.amazonaws.com")
});

role.AddToPolicy(new PolicyStatement(new PolicyStatementProps {
    Resources = new [] { "*" },
    Actions = new [] { "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.attachInlinePolicy(policy) or policy.attachToXxx(xxx).

// Example automatically generated. See https://github.com/aws/jsii/issues/826
User user = new User(this, "MyUser", new UserProps { Password = SecretValue.PlainText("1234") });
Group group = new Group(this, "MyGroup");

Policy policy = new Policy(this, "MyPolicy");
policy.AttachToUser(user);
group.AttachInlinePolicy(policy);

Managed policies can be attached using xxx.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName)):

// Example automatically generated. See https://github.com/aws/jsii/issues/826
Group group = new Group(this, "MyGroup");
group.AddManagedPolicy(ManagedPolicy.FromAwsManagedPolicyName("AdministratorAccess"));

Granting permissions to resources

Many of the AWS CDK resources have grant* methods that allow you to grant other resources access to that resource. As an example, the following code gives a Lambda function write permissions (Put, Update, Delete) to a DynamoDB table.

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var fn = new lambda.Function(...);
var table = new dynamodb.Table(...);

table.GrantWriteData(fn);

The more generic grant method allows you to give specific permissions to a resource:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var fn = new lambda.Function(...);
var table = new dynamodb.Table(...);

table.Grant(fn, "dynamodb:PutItem");

The grant* methods accept an IGrantable object. This interface is implemented by IAM principlal resources (groups, users and roles) and resources that assume a role such as a Lambda function, EC2 instance or a Codebuild project.

You can find which grant* methods exist for a resource in the AWS CDK API Reference.

Roles

Many AWS resources require Roles to operate. These Roles define the AWS API calls an instance or other AWS service is allowed to make.

Creating Roles and populating them with the right permissions Statements is a necessary but tedious part of setting up AWS infrastructure. In order to help you focus on your business logic, CDK will take care of creating roles and populating them with least-privilege permissions automatically.

All constructs that require Roles will create one for you if don't specify one at construction time. Permissions will be added to that role automatically if you associate the construct with other constructs from the AWS Construct Library (for example, if you tell an AWS CodePipeline to trigger an AWS Lambda Function, the Pipeline's Role will automatically get lambda:InvokeFunction permissions on that particular Lambda Function), or if you explicitly grant permissions using grant functions (see the previous section).

Opting out of automatic permissions management

You may prefer to manage a Role's permissions yourself instead of having the CDK automatically manage them for you. This may happen in one of the following cases:

To prevent constructs from updating your Role's policy, pass the object returned by myRole.withoutPolicyUpdates() instead of myRole itself.

For example, to have an AWS CodePipeline not automatically add the required permissions to trigger the expected targets, do the following:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var role = new iam.Role(this, "Role", new Struct {
    AssumedBy = new iam.ServicePrincipal("codepipeline.amazonaws.com"),
    // custom description if desired
    Description = "This is a custom role..."
});

new codepipeline.Pipeline(this, "Pipeline", new Struct {
    // Give the Pipeline an immutable view of the Role
    Role = role.WithoutPolicyUpdates()
});

// You now have to manage the Role policies yourself
role.AddToPolicy(new iam.PolicyStatement(new Struct {
    Action = new [] {  },
    Resource = new [] {  }
}));

Using existing roles

If there are Roles in your account that have already been created which you would like to use in your CDK application, you can use Role.fromRoleArn to import them, as follows:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var role = iam.Role.FromRoleArn(this, "Role", "arn:aws:iam::123456789012:role/MyExistingRole", new Struct {
    // Set 'mutable' to 'false' to use the role as-is and prevent adding new
    // policies to it. The default is 'true', which means the role may be
    // modified as part of the deployment.
    Mutable = false
});

Configuring an ExternalId

If you need to create Roles that will be assumed by third parties, it is generally a good idea to require an ExternalId to assume them. Configuring an ExternalId works like this:

// Example automatically generated. See https://github.com/aws/jsii/issues/826
Role role = new Role(this, "MyRole", new RoleProps {
    AssumedBy = new AccountPrincipal("123456789012"),
    ExternalIds = new [] { "SUPPLY-ME" }
});

Principals vs Identities

When we say Principal, we mean an entity you grant permissions to. This entity can be an AWS Service, a Role, or something more abstract such as "all users in this account" or even "all users in this organization". An Identity is an IAM representing a single IAM entity that can have a policy attached, one of Role, User, or Group.

IAM Principals

When defining policy statements as part of an AssumeRole policy or as part of a resource policy, statements would usually refer to a specific IAM principal under Principal.

IAM principals are modeled as classes that derive from the iam.PolicyPrincipal abstract class. Principal objects include principal type (string) and value (array of string), optional set of conditions and the action that this principal requires when it is used in an assume role policy document.

To add a principal to a policy statement you can either use the abstract statement.addPrincipal, one of the concrete addXxxPrincipal methods:

If multiple principals are added to the policy statement, they will be merged together:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var statement = new PolicyStatement();
statement.AddServicePrincipal("cloudwatch.amazonaws.com");
statement.AddServicePrincipal("ec2.amazonaws.com");
statement.AddArnPrincipal("arn:aws:boom:boom");

Will result in:

{
  "Principal": {
    "Service": [ "cloudwatch.amazonaws.com", "ec2.amazonaws.com" ],
    "AWS": "arn:aws:boom:boom"
  }
}

The CompositePrincipal class can also be used to define complex principals, for example:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var role = new iam.Role(this, "MyRole", new Struct {
    AssumedBy = new iam.CompositePrincipal(
    new iam.ServicePrincipal("ec2.amazonaws.com"),
    new iam.AccountPrincipal("1818188181818187272"))
});

The PrincipalWithConditions class can be used to add conditions to a principal, especially those that don't take a conditions parameter in their constructor. The principal.withConditions() method can be used to create a PrincipalWithConditions from an existing principal, for example:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var principal = new iam.AccountPrincipal("123456789000").WithConditions(new Struct { StringEquals = new Struct { Foo = "baz" } });

Parsing JSON Policy Documents

The PolicyDocument.fromJson and PolicyStatement.fromJson static methods can be used to parse JSON objects. For example:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
__object policyDocument = new Dictionary<string, object> {
    { "Version", "2012-10-17" },
    { "Statement", new [] { new Dictionary<string, object> {
        { "Sid", "FirstStatement" },
        { "Effect", "Allow" },
        { "Action", new [] { "iam:ChangePassword" } },
        { "Resource", "*" }
    }, new Dictionary<string, string> {
        { "Sid", "SecondStatement" },
        { "Effect", "Allow" },
        { "Action", "s3:ListAllMyBuckets" },
        { "Resource", "*" }
    }, new Dictionary<string, object> {
        { "Sid", "ThirdStatement" },
        { "Effect", "Allow" },
        { "Action", new [] { "s3:List*", "s3:Get*" } },
        { "Resource", new [] { "arn:aws:s3:::confidential-data", "arn:aws:s3:::confidential-data/*" } },
        { "Condition", new Dictionary<string, IDictionary<string, string>> { { "Bool", new Dictionary<string, string> { { "aws:MultiFactorAuthPresent", "true" } } } } }
    } } }
};

var newPolicyDocument = PolicyDocument.FromJson(policyDocument);

Features

Classes

AccountPrincipal
AccountRootPrincipal
Anyone	A principal representing all identities in all accounts.
AnyPrincipal	A principal representing all identities in all accounts.
ArnPrincipal
CanonicalUserPrincipal	A policy prinicipal for canonicalUserIds - useful for S3 bucket policies that use Origin Access identities.
CfnAccessKey	A CloudFormation `AWS::IAM::AccessKey`.
CfnAccessKeyProps	Properties for defining a `AWS::IAM::AccessKey`.
CfnGroup	A CloudFormation `AWS::IAM::Group`.
CfnGroup.PolicyProperty
CfnGroupProps	Properties for defining a `AWS::IAM::Group`.
CfnInstanceProfile	A CloudFormation `AWS::IAM::InstanceProfile`.
CfnInstanceProfileProps	Properties for defining a `AWS::IAM::InstanceProfile`.
CfnManagedPolicy	A CloudFormation `AWS::IAM::ManagedPolicy`.
CfnManagedPolicyProps	Properties for defining a `AWS::IAM::ManagedPolicy`.
CfnPolicy	A CloudFormation `AWS::IAM::Policy`.
CfnPolicyProps	Properties for defining a `AWS::IAM::Policy`.
CfnRole	A CloudFormation `AWS::IAM::Role`.
CfnRole.PolicyProperty
CfnRoleProps	Properties for defining a `AWS::IAM::Role`.
CfnServiceLinkedRole	A CloudFormation `AWS::IAM::ServiceLinkedRole`.
CfnServiceLinkedRoleProps	Properties for defining a `AWS::IAM::ServiceLinkedRole`.
CfnUser	A CloudFormation `AWS::IAM::User`.
CfnUser.LoginProfileProperty
CfnUser.PolicyProperty
CfnUserProps	Properties for defining a `AWS::IAM::User`.
CfnUserToGroupAddition	A CloudFormation `AWS::IAM::UserToGroupAddition`.
CfnUserToGroupAdditionProps	Properties for defining a `AWS::IAM::UserToGroupAddition`.
CommonGrantOptions	Basic options for a grant operation.
CompositePrincipal
Effect
FederatedPrincipal
FromRoleArnOptions	Options allowing customizing the behavior of {@link Role.fromRoleArn}.
Grant	Result of a grant() operation.
GrantOnPrincipalAndResourceOptions	Options for a grant operation to both identity and resource.
GrantOnPrincipalOptions	Options for a grant operation that only applies to principals.
GrantWithResourceOptions	Options for a grant operation.
Group
GroupProps
LazyRole	An IAM role that only gets attached to the construct tree once it gets used, not before.
LazyRoleProps
ManagedPolicy	Managed policy.
ManagedPolicyProps
OrganizationPrincipal	A principal that represents an AWS Organization.
Policy	The AWS::IAM::Policy resource associates an IAM policy with IAM users, roles, or groups.
PolicyDocument	A PolicyDocument is a collection of statements.
PolicyDocumentProps	Properties for a new PolicyDocument.
PolicyProps
PolicyStatement	Represents a statement in an IAM policy document.
PolicyStatementProps	Interface for creating a policy statement.
PrincipalBase	Base class for policy principals.
PrincipalPolicyFragment	A collection of the fields in a PolicyStatement that can be used to identify a principal.
PrincipalWithConditions	An IAM principal with additional conditions specifying when the policy is in effect.
Role	IAM Role.
RoleProps
ServicePrincipal	An IAM principal that represents an AWS service (i.e. sqs.amazonaws.com).
ServicePrincipalOpts	Options for a service principal.
UnknownPrincipal	A principal for use in resources that need to have a role but it's unknown.
UnknownPrincipalProps	Properties for an UnknownPrincipal.
User	Define a new IAM user.
UserProps

Interfaces

CfnGroup.IPolicyProperty
CfnRole.IPolicyProperty
CfnUser.ILoginProfileProperty
CfnUser.IPolicyProperty
ICfnAccessKeyProps	Properties for defining a `AWS::IAM::AccessKey`.
ICfnGroupProps	Properties for defining a `AWS::IAM::Group`.
ICfnInstanceProfileProps	Properties for defining a `AWS::IAM::InstanceProfile`.
ICfnManagedPolicyProps	Properties for defining a `AWS::IAM::ManagedPolicy`.
ICfnPolicyProps	Properties for defining a `AWS::IAM::Policy`.
ICfnRoleProps	Properties for defining a `AWS::IAM::Role`.
ICfnServiceLinkedRoleProps	Properties for defining a `AWS::IAM::ServiceLinkedRole`.
ICfnUserProps	Properties for defining a `AWS::IAM::User`.
ICfnUserToGroupAdditionProps	Properties for defining a `AWS::IAM::UserToGroupAddition`.
ICommonGrantOptions	Basic options for a grant operation.
IFromRoleArnOptions	Options allowing customizing the behavior of {@link Role.fromRoleArn}.
IGrantable	Any object that has an associated principal that a permission can be granted to.
IGrantOnPrincipalAndResourceOptions	Options for a grant operation to both identity and resource.
IGrantOnPrincipalOptions	Options for a grant operation that only applies to principals.
IGrantWithResourceOptions	Options for a grant operation.
IGroup
IGroupProps
IIdentity	A construct that represents an IAM principal, such as a user, group or role.
ILazyRoleProps
IManagedPolicy	A managed policy.
IManagedPolicyProps
IPolicy
IPolicyDocumentProps	Properties for a new PolicyDocument.
IPolicyProps
IPolicyStatementProps	Interface for creating a policy statement.
IPrincipal	Represents a logical IAM principal.
IResourceWithPolicy	A resource with a resource policy that can be added to.
IRole	A Role object.
IRoleProps
IServicePrincipalOpts	Options for a service principal.
IUnknownPrincipalProps	Properties for an UnknownPrincipal.
IUser
IUserProps