# Role

IAM Role.

Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in `serviceAssumeRole`.

Extends: Construct › Resource › Role
Implements: IResource, IGrantable, IIdentity, IPrincipal, IRole, IEnvironmentAware, IRoleRef, IConstruct, IDependable

- CloudFormation: [`AWS::IAM::Role`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-iam-role.html)
- L1 type: [`CfnRole`](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.CfnRole.html)
- Source: [`aws-iam/lib/role.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-iam/lib/role.ts#L288)
- Type last changed: v2.227.0 · 21 Nov 2025

## Example

```ts
// Create a browser
const browser = new agentcore.BrowserCustom(this, "MyBrowser", {
  browserCustomName: "my_browser",
  description: "Browser for web automation",
  networkConfiguration: agentcore.BrowserNetworkConfiguration.usingPublicNetwork(),
});

// Create a role that needs access to the browser
const userRole = new iam.Role(this, "UserRole", {
  assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
});

// Grant read permissions (Get and List actions)
browser.grantRead(userRole);

// Grant use permissions (Start, Update, Connect to the automation stream, and Stop actions)
browser.grantUse(userRole);

// Grant specific custom permissions
browser.grant(userRole, "bedrock-agentcore:GetBrowserSession");
```

## Initializer

```ts
new Role(scope: Construct, id: string, props: RoleProps)
```

## Construct Props

- `assumedBy`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) (required) — 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.

- `description`: string — A description of the role.

  **Default:** No description.

  It can be up to 1000 characters long.

- `externalIds`: 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.

- `inlinePolicies`: { [key: string]: [PolicyDocument](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyDocument.html) } — 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).

- `managedPolicies`: [IManagedPolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IManagedPolicy.html)[] — A list of managed policies associated with this role.

  **Default:** No managed policies.

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

- `maxSessionDuration`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.hours(1) — The maximum session duration that you want to set for the specified role.

  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.

- `path`: string = / — The path associated with this role.

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

- `permissionsBoundary`: [IManagedPolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IManagedPolicy.html) — AWS supports permissions boundaries for IAM entities (users or roles).

  **Default:** No permissions boundary.

  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.

- `roleName`: string — A name for the IAM role.

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

  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.

## Properties

- `assumeRoleAction`: string — When this Principal is used in an AssumeRole policy, the action to use.

- `assumeRolePolicy`: [PolicyDocument](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyDocument.html) — The assume role policy document associated with this role.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `grantPrincipal`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) — The principal to grant permissions to.

- `grants`: [RoleGrants](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.RoleGrants.html) — Collection of grant methods for a Role.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `permissionsBoundary`: [IManagedPolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IManagedPolicy.html) — Returns the permissions boundary attached to this role.

- `policyFragment`: [PrincipalPolicyFragment](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PrincipalPolicyFragment.html) — Returns the role.

- `principalAccount`: string — 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.

- `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class.

- `roleArn`: string — Returns the ARN of this role.

- `roleId`: string — Returns the stable and unique string identifying the role.

  For example,
  AIDAJQABLZS4A3QDU576Q.

- `roleName`: string — Returns the name of the role.

- `roleRef`: [RoleReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_iam.RoleReference.html) — A reference to a Role resource.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) — The stack in which this resource is defined.

## Methods

- `addManagedPolicy(policy: IManagedPolicy): void` — Attaches a managed policy to this role.

  **Parameters**

  - `policy` — The the managed policy to attach.

- `addToPolicy(statement: PolicyStatement): boolean` — Add to the policy of this principal.

- `addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult` — Adds a permission to the role's default policy document.

  If there is no default policy attached to this role, it will be created.

  **Parameters**

  - `statement` — The permission statement to add to the policy document.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — Skip applyRemovalPolicy if role synthesis is prevented by customizeRoles.

  Because in this case, this construct does not have a CfnResource in the tree.

  **Parameters**

  - `policy` — RemovalPolicy.

- `attachInlinePolicy(policy: Policy): void` — Attaches a policy to this role.

  **Parameters**

  - `policy` — The policy to attach.

- `customizeRoles(scope: Construct, options?: CustomizeRolesOptions): void` (static) — Customize the creation of IAM roles within the given scope.

  It is recommended that you **do not** use this method and instead allow
  CDK to manage role creation. This should only be used
  in environments where CDK applications are not allowed to created IAM roles.

  This can be used to prevent the CDK application from creating roles
  within the given scope and instead replace the references to the roles with
  precreated role names. A report will be synthesized in the cloud assembly (i.e. cdk.out)
  that will contain the list of IAM roles that would have been created along with the
  IAM policy statements that the role should contain. This report can then be used
  to create the IAM roles outside of CDK and then the created role names can be provided
  in `usePrecreatedRoles`.

  **Parameters**

  - `scope` — construct scope to customize role creation.
  - `options` — options for configuring role creation.

  ```ts
  declare const app: App;
  iam.Role.customizeRoles(app, {
    usePrecreatedRoles: {
      'ConstructPath/To/Role': 'my-precreated-role-name',
    },
  });
  ```

- `fromLookup(scope: Construct, id: string, options: RoleLookupOptions): IRole` (static) — Lookup an existing Role.

- `fromRoleArn(scope: Construct, id: string, roleArn: string, options?: FromRoleArnOptions): IRole` (static) — Import an external role by ARN.

  If the imported Role ARN is a Token (such as a
  `CfnParameter.valueAsString` or a `Fn.importValue()`) *and* the referenced
  role has a `path` (like `arn:...:role/AdminRoles/Alice`), the
  `roleName` 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 Role ARN should be supplied without the
  `path` in order to resolve the correct role resource.

  **Parameters**

  - `scope` — construct scope.
  - `id` — construct id.
  - `roleArn` — the ARN of the role to import.
  - `options` — allow customizing the behavior of the returned role.

- `fromRoleName(scope: Construct, id: string, roleName: string, options?: FromRoleNameOptions): IRole` (static) — Import an external role by name.

  The imported role is assumed to exist in the same account as the account
  the scope's containing Stack is being deployed to.

  **Parameters**

  - `scope` — construct scope.
  - `id` — construct id.
  - `roleName` — the name of the role to import.
  - `options` — allow customizing the behavior of the returned role.

- `grant(grantee: IPrincipal, ...actions: string[]): Grant` — Grant the actions defined in actions to the identity Principal on this resource.

- `grantAssumeRole(identity: IPrincipal): Grant` — Grant permissions to the given principal to assume this role.

- `grantPassRole(identity: IPrincipal): Grant` — Grant permissions to the given principal to pass this role.

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `isRole(x: any): boolean` (static) — Return whether the given object is a Role.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.

- `withoutPolicyUpdates(options?: WithoutPolicyUpdatesOptions): IRole` — Return a copy of this Role object whose Policies will not be updated.

  Use the object returned by this method if you want this Role to be used by
  a construct without it automatically updating the Role's Policies.

  If you do, you are responsible for adding the correct statements to the
  Role's policies yourself.