Package software.amazon.awscdk.services.iam

Class Role

java.lang.Object
software.amazon.jsii.JsiiObject
software.constructs.Construct
software.amazon.awscdk.Resource
software.amazon.awscdk.services.iam.Role
All Implemented Interfaces:
IResource, IGrantable, IIdentity, IPrincipal, IRole, IRoleRef, software.amazon.jsii.JsiiSerializable, software.constructs.IConstruct, software.constructs.IDependable
@Generated(value="jsii-pacmak/1.116.0 (build 0eddcff)", date="2025-10-29T11:15:41.231Z") @Stability(Stable) public class Role extends Resource implements IRole
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.

Example: 

 // Create a custom execution role
 Role executionRole = Role.Builder.create(this, "BrowserExecutionRole")
         .assumedBy(new ServicePrincipal("bedrock-agentcore.amazonaws.com"))
         .managedPolicies(List.of(ManagedPolicy.fromAwsManagedPolicyName("AmazonBedrockAgentCoreBrowserExecutionRolePolicy")))
         .build();
 // Create browser with custom execution role
 BrowserCustom browser = BrowserCustom.Builder.create(this, "MyBrowser")
         .browserCustomName("my_browser")
         .description("Browser with custom execution role")
         .networkConfiguration(BrowserNetworkConfiguration.usingPublicNetwork())
         .executionRole(executionRole)
         .build();

  • Field Details

    • PROPERTY_INJECTION_ID

      @Stability(Stable) public static final String PROPERTY_INJECTION_ID
      Uniquely identifies this class.

  • Constructor Details

    • Role

      protected Role(software.amazon.jsii.JsiiObjectRef objRef)

    • Role

      protected Role(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)

    • Role

      @Stability(Stable) public Role(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull RoleProps props)
      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      props - This parameter is required.

  • Method Details

    • customizeRoles

      @Stability(Stable) public static void customizeRoles(@NotNull software.constructs.Construct scope, @Nullable CustomizeRolesOptions options)
      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.

      Example: 

       App app;
 Role.customizeRoles(app, CustomizeRolesOptions.builder()
         .usePrecreatedRoles(Map.of(
                 "ConstructPath/To/Role", "my-precreated-role-name"))
         .build());

      Parameters:
      scope - construct scope to customize role creation. This parameter is required.
      options - options for configuring role creation.

    • customizeRoles

      @Stability(Stable) public static void customizeRoles(@NotNull software.constructs.Construct scope)
      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.

      Example: 

       App app;
 Role.customizeRoles(app, CustomizeRolesOptions.builder()
         .usePrecreatedRoles(Map.of(
                 "ConstructPath/To/Role", "my-precreated-role-name"))
         .build());

      Parameters:
      scope - construct scope to customize role creation. This parameter is required.

    • fromLookup

      @Stability(Stable) @NotNull public static IRole fromLookup(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull RoleLookupOptions options)
      Lookup an existing Role.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      options - This parameter is required.

    • fromRoleArn

      @Stability(Stable) @NotNull public static IRole fromRoleArn(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String roleArn, @Nullable FromRoleArnOptions options)
      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. This parameter is required.
      id - construct id. This parameter is required.
      roleArn - the ARN of the role to import. This parameter is required.
      options - allow customizing the behavior of the returned role.

    • fromRoleArn

      @Stability(Stable) @NotNull public static IRole fromRoleArn(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String roleArn)
      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. This parameter is required.
      id - construct id. This parameter is required.
      roleArn - the ARN of the role to import. This parameter is required.

    • fromRoleName

      @Stability(Stable) @NotNull public static IRole fromRoleName(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String roleName, @Nullable FromRoleNameOptions options)
      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. This parameter is required.
      id - construct id. This parameter is required.
      roleName - the name of the role to import. This parameter is required.
      options - allow customizing the behavior of the returned role.

    • fromRoleName

      @Stability(Stable) @NotNull public static IRole fromRoleName(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String roleName)
      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. This parameter is required.
      id - construct id. This parameter is required.
      roleName - the name of the role to import. This parameter is required.

    • isRole

      @Stability(Stable) @NotNull public static Boolean isRole(@NotNull Object x)
      Return whether the given object is a Role.

      Parameters:
      x - This parameter is required.

    • addManagedPolicy

      @Stability(Stable) public void addManagedPolicy(@NotNull IManagedPolicy policy)
      Attaches a managed policy to this role.

      Specified by:
      addManagedPolicy in interface IIdentity
      Parameters:
      policy - The the managed policy to attach. This parameter is required.

    • addToPolicy

      @Stability(Stable) @NotNull public Boolean addToPolicy(@NotNull PolicyStatement statement)
      Add to the policy of this principal.

      Parameters:
      statement - This parameter is required.

    • addToPrincipalPolicy

      @Stability(Stable) @NotNull public AddToPrincipalPolicyResult addToPrincipalPolicy(@NotNull PolicyStatement statement)
      Adds a permission to the role's default policy document.

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

      Specified by:
      addToPrincipalPolicy in interface IPrincipal
      Parameters:
      statement - The permission statement to add to the policy document. This parameter is required.

    • applyRemovalPolicy

      @Stability(Stable) public void applyRemovalPolicy(@NotNull RemovalPolicy policy)
      Skip applyRemovalPolicy if role synthesis is prevented by customizeRoles.

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

      Specified by:
      applyRemovalPolicy in interface IResource
      Overrides:
      applyRemovalPolicy in class Resource
      Parameters:
      policy - RemovalPolicy. This parameter is required.

    • attachInlinePolicy

      @Stability(Stable) public void attachInlinePolicy(@NotNull Policy policy)
      Attaches a policy to this role.

      Specified by:
      attachInlinePolicy in interface IIdentity
      Parameters:
      policy - The policy to attach. This parameter is required.

    • grant

      @Stability(Stable) @NotNull public Grant grant(@NotNull IPrincipal grantee, @NotNull String... actions)
      Grant the actions defined in actions to the identity Principal on this resource.

      Specified by:
      grant in interface IRole
      Parameters:
      grantee - This parameter is required.
      actions - This parameter is required.

    • grantAssumeRole

      @Stability(Stable) @NotNull public Grant grantAssumeRole(@NotNull IPrincipal identity)
      Grant permissions to the given principal to assume this role.

      Specified by:
      grantAssumeRole in interface IRole
      Parameters:
      identity - This parameter is required.

    • grantPassRole

      @Stability(Stable) @NotNull public Grant grantPassRole(@NotNull IPrincipal identity)
      Grant permissions to the given principal to pass this role.

      Specified by:
      grantPassRole in interface IRole
      Parameters:
      identity - This parameter is required.

    • withoutPolicyUpdates

      @Stability(Stable) @NotNull public IRole withoutPolicyUpdates(@Nullable WithoutPolicyUpdatesOptions options)
      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.

      Parameters:
      options -

    • withoutPolicyUpdates

      @Stability(Stable) @NotNull public IRole withoutPolicyUpdates()
      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.

    • getAssumeRoleAction

      @Stability(Stable) @NotNull public String getAssumeRoleAction()
      When this Principal is used in an AssumeRole policy, the action to use.
      Specified by:
      getAssumeRoleAction in interface IPrincipal

    • getGrantPrincipal

      @Stability(Stable) @NotNull public IPrincipal getGrantPrincipal()
      The principal to grant permissions to.
      Specified by:
      getGrantPrincipal in interface IGrantable

    • getPolicyFragment

      @Stability(Stable) @NotNull public PrincipalPolicyFragment getPolicyFragment()
      Returns the role.
      Specified by:
      getPolicyFragment in interface IPrincipal

    • getRoleArn

      @Stability(Stable) @NotNull public String getRoleArn()
      Returns the ARN of this role.
      Specified by:
      getRoleArn in interface IRole

    • getRoleId

      @Stability(Stable) @NotNull public String getRoleId()
      Returns the stable and unique string identifying the role.

      For example, AIDAJQABLZS4A3QDU576Q.

    • getRoleName

      @Stability(Stable) @NotNull public String getRoleName()
      Returns the name of the role.
      Specified by:
      getRoleName in interface IRole

    • getRoleRef

      @Stability(Stable) @NotNull public RoleReference getRoleRef()
      A reference to a Role resource.
      Specified by:
      getRoleRef in interface IRoleRef

    • getAssumeRolePolicy

      @Stability(Stable) @Nullable public PolicyDocument getAssumeRolePolicy()
      The assume role policy document associated with this role.

    • getPermissionsBoundary

      @Stability(Stable) @Nullable public IManagedPolicy getPermissionsBoundary()
      Returns the permissions boundary attached to this role.

    • getPrincipalAccount

      @Stability(Stable) @Nullable public String getPrincipalAccount()
      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.

      Specified by:
      getPrincipalAccount in interface IPrincipal