class Group (construct)

Language	Type name
.NET	Amazon.CDK.AWS.IAM.Group
Go	github.com/aws/aws-cdk-go/awscdk/v2/awsiam#Group
Java	software.amazon.awscdk.services.iam.Group
Python	aws_cdk.aws_iam.Group
TypeScript (source)	aws-cdk-lib » aws_iam » Group

Implements IConstruct, IDependable, IResource, IGroup, IGrantable, IPrincipal, IIdentity

An IAM Group (collection of IAM users) lets you specify permissions for multiple users, which can make it easier to manage permissions for those users.

See also: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html

Example

const user = new iam.User(this, 'MyUser'); // or User.fromUserName(this, 'User', 'johnsmith');
const group = new iam.Group(this, 'MyGroup'); // or Group.fromGroupArn(this, 'Group', 'arn:aws:iam::account-id:group/group-name');

user.addToGroup(group);
// or
group.addUser(user);

Initializer

new Group(scope: Construct, id: string, props?: GroupProps)

Parameters

• scope Construct
• id string
• props GroupProps

Construct Props

Name	Type	Description
groupName?	string	A name for the IAM group.
managedPolicies?	IManagedPolicy[]	A list of managed policies associated with this role.
path?	string	The path to the group.

---

groupName?

Type: string (optional, default: Generated by CloudFormation (recommended))

A name for the IAM group.

For valid values, see the GroupName parameter for the CreateGroup action in the IAM API Reference. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the group name.

If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template's capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

---

managedPolicies?

Type: IManagedPolicy[] (optional, default: No managed policies.)

A list of managed policies associated with this role.

You can add managed policies later using addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName)).

---

path?

Type: string (optional, default: /)

The path to the group.

For more information about paths, see IAM Identifiers in the IAM User Guide.

Properties

Name	Type	Description
assumeRoleAction	string	When this Principal is used in an AssumeRole policy, the action to use.
env	ResourceEnvironment	The environment this resource belongs to.
grantPrincipal	IPrincipal	The principal to grant permissions to.
groupArn	string	Returns the IAM Group ARN.
groupName	string	Returns the IAM Group Name.
node	Node	The tree node.
policyFragment	PrincipalPolicyFragment	Return the policy fragment that identifies this principal in a Policy.
stack	Stack	The stack in which this resource is defined.
principalAccount?	string	The AWS account ID of this principal.

---

assumeRoleAction

Type: string

When this Principal is used in an AssumeRole policy, the action to use.

---

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

---

grantPrincipal

Type: IPrincipal

The principal to grant permissions to.

---

groupArn

Type: string

Returns the IAM Group ARN.

---

groupName

Type: string

Returns the IAM Group Name.

---

node

Type: Node

The tree node.

---

policyFragment

Type: PrincipalPolicyFragment

Return the policy fragment that identifies this principal in a Policy.

---

stack

Type: Stack

The stack in which this resource is defined.

---

principalAccount?

Type: string (optional)

The AWS account ID of this principal.

Can be undefined when the account is not known (for example, for service principals). Can be a Token - in that case, it's assumed to be AWS::AccountId.

Methods

Name	Description
addManagedPolicy(policy)	Attaches a managed policy to this group.
addToPolicy(statement)	Add to the policy of this principal.
addToPrincipalPolicy(statement)	Adds an IAM statement to the default policy.
addUser(user)	Adds a user to this group.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
attachInlinePolicy(policy)	Attaches a policy to this group.
toString()	Returns a string representation of this construct.
static fromGroupArn(scope, id, groupArn)	Import an external group by ARN.
static fromGroupName(scope, id, groupName)	Import an existing group by given name (with path).

---

addManagedPolicy(policy)

public addManagedPolicy(policy: IManagedPolicy): void

Parameters

• policy IManagedPolicy — The managed policy to attach.

Attaches a managed policy to this group.

See [IAM and AWS STS quotas, name requirements, and character limits] (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html#reference_iam-quotas-entities) for quota of managed policies attached to an IAM group.

---

addToPolicy(statement)

public addToPolicy(statement: PolicyStatement): boolean

Parameters

• statement PolicyStatement

Returns

• boolean

Add to the policy of this principal.

---

addToPrincipalPolicy(statement)

public addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult

Parameters

• statement PolicyStatement

Returns

• AddToPrincipalPolicyResult

Adds an IAM statement to the default policy.

---

addUser(user)

public addUser(user: IUser): void

Parameters

• user IUser

Adds a user to this group.

---

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

• policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

---

attachInlinePolicy(policy)

public attachInlinePolicy(policy: Policy): void

Parameters

• policy Policy — The policy to attach.

Attaches a policy to this group.

---

toString()

public toString(): string

Returns

• string

Returns a string representation of this construct.

---

static fromGroupArn(scope, id, groupArn)

public static fromGroupArn(scope: Construct, id: string, groupArn: string): IGroup

Parameters

• scope Construct — construct scope.
• id string — construct id.
• groupArn string — the ARN of the group to import (e.g. arn:aws:iam::account-id:group/group-name).

Returns

• IGroup

Import an external group by ARN.

If the imported Group ARN is a Token (such as a CfnParameter.valueAsString or a Fn.importValue()) and the referenced group has a path (like arn:...:group/AdminGroup/NetworkAdmin), the groupName property will not resolve to the correct value. Instead it will resolve to the first path component. We unfortunately cannot express the correct calculation of the full path name as a CloudFormation expression. In this scenario the Group ARN should be supplied without the path in order to resolve the correct group resource.

---

static fromGroupName(scope, id, groupName)

public static fromGroupName(scope: Construct, id: string, groupName: string): IGroup

Parameters

• scope Construct — construct scope.
• id string — construct id.
• groupName string — the groupName (path included) of the existing group to import.

Returns

• IGroup

Import an existing group by given name (with path).

This method has same caveats of fromGroupArn