@aws-cdk/aws-iam
Advanced tools
CDK routines for easily assigning correct and minimal IAM permissions
@aws-cdk/aws-iam is an AWS Cloud Development Kit (CDK) library that allows you to define AWS Identity and Access Management (IAM) resources in your CDK applications. This package provides constructs for creating and managing IAM roles, users, policies, and groups, enabling you to manage permissions and access control in your AWS environment programmatically.
Create IAM Role
This code sample demonstrates how to create an IAM role that can be assumed by EC2 instances and has read-only access to Amazon S3.
const iam = require('@aws-cdk/aws-iam');
const cdk = require('@aws-cdk/core');
class MyStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),
managedPolicies: [
iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonS3ReadOnlyAccess')
]
});
}
}
const app = new cdk.App();
new MyStack(app, 'MyStack');Create IAM User
This code sample demonstrates how to create an IAM user with administrator access.
const iam = require('@aws-cdk/aws-iam');
const cdk = require('@aws-cdk/core');
class MyStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
new iam.User(this, 'MyUser', {
userName: 'my-user',
managedPolicies: [
iam.ManagedPolicy.fromAwsManagedPolicyName('AdministratorAccess')
]
});
}
}
const app = new cdk.App();
new MyStack(app, 'MyStack');Attach Inline Policy to Role
This code sample demonstrates how to create an IAM role and attach an inline policy that allows listing objects in a specific S3 bucket.
const iam = require('@aws-cdk/aws-iam');
const cdk = require('@aws-cdk/core');
class MyStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com')
});
role.addToPolicy(new iam.PolicyStatement({
actions: ['s3:ListBucket'],
resources: ['arn:aws:s3:::my-bucket']
}));
}
}
const app = new cdk.App();
new MyStack(app, 'MyStack');The aws-sdk package is the official AWS SDK for JavaScript, which allows you to interact with AWS services, including IAM, using JavaScript. Unlike @aws-cdk/aws-iam, which is used for defining and deploying AWS infrastructure, aws-sdk is used for making API calls to AWS services.
The serverless framework is a toolkit for deploying and operating serverless architectures, including AWS Lambda functions and associated IAM roles and policies. It provides a higher-level abstraction compared to @aws-cdk/aws-iam and is focused on serverless applications.
Terraform is an open-source infrastructure as code software tool that provides a consistent CLI workflow to manage hundreds of cloud services, including AWS IAM. It is similar to @aws-cdk/aws-iam in that it allows you to define and manage AWS infrastructure, but it is not limited to AWS and supports multiple cloud providers.
Define a role and add permissions to it. This will automatically create and attach an IAM policy to the 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.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName)):
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.
const fn = new lambda.Function(...);
const table = new dynamodb.Table(...);
table.grantWriteData(fn);
The more generic grant method allows you to give specific permissions to a resource:
const fn = new lambda.Function(...);
const 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.
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).
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:
const role = new iam.Role(this, 'Role', {
assumedBy: new iam.ServicePrincipal('codepipeline.amazonaws.com'),
// custom description if desired
description: 'This is a custom role...',
});
new codepipeline.Pipeline(this, 'Pipeline', {
// 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({
action: [/* whatever actions you want */],
resource: [/* whatever resources you intend to touch */],
});
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:
const role = iam.Role.fromRoleArn(this, 'Role', 'arn:aws:iam::123456789012:role/MyExistingRole', {
// 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,
});
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:
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.
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.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:
const role = new iam.Role(this, 'MyRole', {
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:
const principal = new iam.AccountPrincipal('123456789000')
.withConditions({ StringEquals: { foo: "baz" } });
NOTE: If you need to define an IAM condition that uses a token (such as a deploy-time attribute of another resource) in a JSON map key, use
CfnJsonto render this condition. See this test for an example.
The WebIdentityPrincipal class can be used as a principal for web identities like
Cognito, Amazon, Google or Facebook, for example:
const principal = new iam.WebIdentityPrincipal('cognito-identity.amazonaws.com')
.withConditions({
"StringEquals": { "cognito-identity.amazonaws.com:aud": "us-east-2:12345678-abcd-abcd-abcd-123456" },
"ForAnyValue:StringLike": {"cognito-identity.amazonaws.com:amr": "unauthenticated"}
});
The PolicyDocument.fromJson and PolicyStatement.fromJson static methods can be used to parse JSON objects. For example:
const policyDocument = {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "FirstStatement",
"Effect": "Allow",
"Action": ["iam:ChangePassword"],
"Resource": "*"
},
{
"Sid": "SecondStatement",
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "*"
},
{
"Sid": "ThirdStatement",
"Effect": "Allow",
"Action": [
"s3:List*",
"s3:Get*"
],
"Resource": [
"arn:aws:s3:::confidential-data",
"arn:aws:s3:::confidential-data/*"
],
"Condition": {"Bool": {"aws:MultiFactorAuthPresent": "true"}}
}
]
};
const newPolicyDocument = PolicyDocument.fromJson(policyDocument);
OIDC identity providers are entities in IAM that describe an external identity provider (IdP) service that supports the OpenID Connect (OIDC) standard, such as Google or Salesforce. You use an IAM OIDC identity provider when you want to establish trust between an OIDC-compatible IdP and your AWS account. This is useful when creating a mobile app or web application that requires access to AWS resources, but you don't want to create custom sign-in code or manage your own user identities. For more information about this scenario, see About Web Identity Federation and the relevant documentation in the Amazon Cognito Identity Pools Developer Guide.
The following examples defines an OpenID Connect provider. Two client IDs (audiences) are will be able to send authentication requests to https://openid/connect.
const provider = new OpenIdConnectProvider(this, 'MyProvider', {
url: 'https://openid/connect',
clients: [ 'myclient1', 'myclient2' ]
});
You can specify an optional list of thumbprints. If not specified, the
thumbprint of the root certificate authority (CA) will automatically be obtained
from the host as described
here.
Once you define an OpenID connect provider, you can use it with AWS services that expect an IAM OIDC provider. For example, when you define an Amazon Cognito identity pool you can reference the provider's ARN as follows:
new cognito.CfnIdentityPool(this, 'IdentityPool', {
openIdConnectProviderARNs: [ provider.openIdConnectProviderArn ]
});
The OpenIdConnectPrincipal class can be used as a principal used with a OpenIdConnectProvider, for example:
const provider = new OpenIdConnectProvider(this, 'MyProvider', {
url: 'https://openid/connect',
clients: [ 'myclient1', 'myclient2' ]
});
const principal = new iam.OpenIdConnectPrincipal(provider);
1.71.0 (2020-10-29)
runtime is now a required property.Lazy values are no longer
captured by default. The CDK_DEBUG=true environment variable must be
set in order to capture stack traces (this is also achieved by using the
--debug option of the cdk CLI). Users should not need those stack
traces most of the time, and should only enable creation stack trace
captures when tyring to troubleshoot a resolution error that they are
otherwise unable to trace back.--all flag to select all stacks (#10745) (bcd9d0a), closes #3222.venv to comply with python recommendation (#10995) (a4a41b5), closes #9134credentials.fromSecret does not access secretsmanager.ISecret (#11033) (35ad608), closes #11015CfnInit cannot be used with custom constructs (#11167) (01c52c8)FAQs
CDK routines for easily assigning correct and minimal IAM permissions
The npm package @aws-cdk/aws-iam receives a total of 166,021 weekly downloads. As such, @aws-cdk/aws-iam popularity was classified as popular.
We found that @aws-cdk/aws-iam demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.