AWS IAM Construct Library
Define a role and add permissions to it. This will automatically create and
attach an IAM policy to the role:
attaching permissions to role
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)
.
attaching policies to user and group
Managed policies can be attached using xxx.attachManagedPolicy(arn)
:
attaching managed policies
Configuring an ExternalId
If you need to create roles that will be assumed by 3rd parties, it is generally a good idea to require an ExternalId
to assume them. Configuring
an ExternalId
works like this:
supplying an external ID
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:
addAwsPrincipal
, addArnPrincipal
or new ArnPrincipal(arn)
for { "AWS": arn }
addAwsAccountPrincipal
or new AccountPrincipal(accountId)
for { "AWS": account-arn }
addServicePrincipal
or new ServicePrincipal(service)
for { "Service": service }
addAccountRootPrincipal
or new AccountRootPrincipal()
for { "AWS": { "Ref: "AWS::AccountId" } }
addCanonicalUserPrincipal
or new CanonicalUserPrincipal(id)
for { "CanonicalUser": id }
addFederatedPrincipal
or new FederatedPrincipal(federated, conditions, assumeAction)
for
{ "Federated": arn }
and a set of optional conditions and the assume role action to use.addAnyPrincipal
or new AnyPrincipal
for { "AWS": "*" }
If multiple principals are added to the policy statement, they will be merged together:
const statement = new PolicyStatement();
statement.addServicePrincipal('cloudwatch.amazonaws.com');
statement.addServicePrincipal('ec2.amazonaws.com');
statement.addAwsPrincipal('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:
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.CompositePrincipal(
new iam.ServicePrincipal('ec2.amazonaws.com'),
new iam.AccountPrincipal('1818188181818187272')
)
});
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.