AWS CDK Reference

Appearance

v2.275.0

RoleProps Struct ​

Properties for defining an IAM Role.

Source
aws-iam/lib/role.ts

Example ​

ts
declare const vpc: ec2.Vpc;

const logGroup = new logs.LogGroup(this, 'MyCustomLogGroup');

const role = new iam.Role(this, 'MyCustomRole', {
  assumedBy: new iam.ServicePrincipal('vpc-flow-logs.amazonaws.com')
});

new ec2.FlowLog(this, 'FlowLog', {
  resourceType: ec2.FlowLogResourceType.fromVpc(vpc),
  destination: ec2.FlowLogDestination.toCloudWatchLogs(logGroup, role)
});

Properties ​

assumedByIPrincipalassumed_byIPrincipalassumedByIPrincipalAssumedByIPrincipalAssumedByIPrincipalrequired#
The IAM principal (i.e. `new ServicePrincipal('sns.amazonaws.com')`) which can assume this role.

You can later modify the assume role policy document by accessing it via the assumeRolePolicy property.

descriptionoptionalstringdescriptionoptionalstrdescriptionoptionalStringDescriptionoptionalstringDescriptionoptional*string#
A description of the role.

Default: No description.

It can be up to 1000 characters long.

externalIdsoptionalstring[]external_idsoptionaltyping.List[str]externalIdsoptionalList<String>ExternalIdsoptionalstring[]ExternalIdsoptional*[]*string#
List of IDs that the role assumer needs to provide one of when assuming this role.

Default: No external ID required

If the configured and provided external IDs do not match, the AssumeRole operation will fail.

inlinePoliciesoptional{ [key: string]: PolicyDocument }inline_policiesoptionaltyping.Mapping[str, PolicyDocument]inlinePoliciesoptionalMap<String, PolicyDocument>InlinePoliciesoptionalIDictionary<string, PolicyDocument>InlinePoliciesoptional*map[string]PolicyDocument#
A list of named policies to inline into this role.

Default: No policy is inlined in the Role resource.

These policies will be created with the role, whereas those added by addToPolicy are added using a separate CloudFormation resource (allowing a way around circular dependencies that could otherwise be introduced).

managedPoliciesoptionalIManagedPolicy[]managed_policiesoptionaltyping.List[IManagedPolicy]managedPoliciesoptionalList<IManagedPolicy>ManagedPoliciesoptionalIManagedPolicy[]ManagedPoliciesoptional*[]IManagedPolicy#
A list of managed policies associated with this role.

Default: No managed policies.

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

maxSessionDurationoptionalDurationmax_session_durationoptionalDurationmaxSessionDurationoptionalDurationMaxSessionDurationoptionalDurationMaxSessionDurationoptionalDuration= Duration.hours(1)#
The maximum session duration that you want to set for the specified role.
notes

This setting can have a value from 1 hour (3600sec) to 12 (43200sec) hours.

Anyone who assumes the role from the AWS CLI or API can use the DurationSeconds API parameter or the duration-seconds CLI parameter to request a longer session. The MaxSessionDuration setting determines the maximum duration that can be requested using the DurationSeconds parameter.

If users don't specify a value for the DurationSeconds parameter, their security credentials are valid for one hour by default. This applies when you use the AssumeRole* API operations or the assume-role* CLI operations but does not apply when you use those operations to create a console URL.

pathoptionalstringpathoptionalstrpathoptionalStringPathoptionalstringPathoptional*string= /#
The path associated with this role.

For information about IAM paths, see Friendly Names and Paths in IAM User Guide.

permissionsBoundaryoptionalIManagedPolicypermissions_boundaryoptionalIManagedPolicypermissionsBoundaryoptionalIManagedPolicyPermissionsBoundaryoptionalIManagedPolicyPermissionsBoundaryoptionalIManagedPolicy#
AWS supports permissions boundaries for IAM entities (users or roles).

Default: No permissions boundary.

notes

A permissions boundary is an advanced feature for using a managed policy to set the maximum permissions that an identity-based policy can grant to an IAM entity. An entity's permissions boundary allows it to perform only the actions that are allowed by both its identity-based policies and its permissions boundaries.

roleNameoptionalstringrole_nameoptionalstrroleNameoptionalStringRoleNameoptionalstringRoleNameoptional*string#
A name for the IAM role.

Default: AWS CloudFormation generates a unique physical ID and uses that ID for the role name.

notes

For valid values, see the RoleName parameter for the CreateRole action in the IAM API Reference.

IMPORTANT: If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new 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.