Class Role
IAM Role.
Implements
Inherited Members
Namespace: Amazon.CDK.AWS.IAM
Assembly: Amazon.CDK.Lib.dll
Syntax (csharp)
public class Role : Resource, IRole, IIdentity, IPrincipal, IGrantable, IResource, IRoleRef, IConstruct, IDependable, IEnvironmentAwareSyntax (vb)
Public Class Role Inherits Resource Implements IRole, IIdentity, IPrincipal, IGrantable, IResource, IRoleRef, IConstruct, IDependable, IEnvironmentAwareRemarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
Examples
// Create a custom execution role
var executionRole = new Role(this, "BrowserExecutionRole", new RoleProps {
AssumedBy = new ServicePrincipal("bedrock-agentcore.amazonaws.com"),
ManagedPolicies = new [] { ManagedPolicy.FromAwsManagedPolicyName("AmazonBedrockAgentCoreBrowserExecutionRolePolicy") }
});
// Create browser with custom execution role
var browser = new BrowserCustom(this, "MyBrowser", new BrowserCustomProps {
BrowserCustomName = "my_browser",
Description = "Browser with custom execution role",
NetworkConfiguration = BrowserNetworkConfiguration.UsingPublicNetwork(),
ExecutionRole = executionRole
});Synopsis
Constructors
| Role(Construct, string, IRoleProps) | IAM Role. |
Properties
| AssumeRoleAction | When this Principal is used in an AssumeRole policy, the action to use. |
| AssumeRolePolicy | The assume role policy document associated with this role. |
| GrantPrincipal | The principal to grant permissions to. |
| PROPERTY_INJECTION_ID | Uniquely identifies this class. |
| PermissionsBoundary | Returns the permissions boundary attached to this role. |
| PolicyFragment | Returns the role. |
| PrincipalAccount | The AWS account ID of this principal. |
| RoleArn | Returns the ARN of this role. |
| RoleId | Returns the stable and unique string identifying the role. |
| RoleName | Returns the name of the role. |
| RoleRef | A reference to a Role resource. |
Methods
| AddManagedPolicy(IManagedPolicy) | Attaches a managed policy to this role. |
| AddToPolicy(PolicyStatement) | Add to the policy of this principal. |
| AddToPrincipalPolicy(PolicyStatement) | Adds a permission to the role's default policy document. |
| ApplyRemovalPolicy(RemovalPolicy) | Skip applyRemovalPolicy if role synthesis is prevented by customizeRoles. |
| AttachInlinePolicy(Policy) | Attaches a policy to this role. |
| CustomizeRoles(Construct, ICustomizeRolesOptions?) | Customize the creation of IAM roles within the given scope. |
| FromLookup(Construct, string, IRoleLookupOptions) | Lookup an existing Role. |
| FromRoleArn(Construct, string, string, IFromRoleArnOptions?) | Import an external role by ARN. |
| FromRoleName(Construct, string, string, IFromRoleNameOptions?) | Import an external role by name. |
| Grant(IPrincipal, params string[]) | Grant the actions defined in actions to the identity Principal on this resource. |
| GrantAssumeRole(IPrincipal) | Grant permissions to the given principal to assume this role. |
| GrantPassRole(IPrincipal) | Grant permissions to the given principal to pass this role. |
| IsRole(object) | Return whether the given object is a Role. |
| WithoutPolicyUpdates(IWithoutPolicyUpdatesOptions?) | Return a copy of this Role object whose Policies will not be updated. |
Constructors
Role(Construct, string, IRoleProps)
IAM Role.
public Role(Construct scope, string id, IRoleProps props)Parameters
- scope Construct
- id string
- props IRoleProps
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
Examples
// Create a custom execution role
var executionRole = new Role(this, "BrowserExecutionRole", new RoleProps {
AssumedBy = new ServicePrincipal("bedrock-agentcore.amazonaws.com"),
ManagedPolicies = new [] { ManagedPolicy.FromAwsManagedPolicyName("AmazonBedrockAgentCoreBrowserExecutionRolePolicy") }
});
// Create browser with custom execution role
var browser = new BrowserCustom(this, "MyBrowser", new BrowserCustomProps {
BrowserCustomName = "my_browser",
Description = "Browser with custom execution role",
NetworkConfiguration = BrowserNetworkConfiguration.UsingPublicNetwork(),
ExecutionRole = executionRole
});Properties
AssumeRoleAction
When this Principal is used in an AssumeRole policy, the action to use.
public virtual string AssumeRoleAction { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
AssumeRolePolicy
The assume role policy document associated with this role.
public virtual PolicyDocument? AssumeRolePolicy { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
GrantPrincipal
The principal to grant permissions to.
public virtual IPrincipal GrantPrincipal { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
PROPERTY_INJECTION_ID
Uniquely identifies this class.
public static string PROPERTY_INJECTION_ID { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
PermissionsBoundary
Returns the permissions boundary attached to this role.
public virtual IManagedPolicy? PermissionsBoundary { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
PolicyFragment
Returns the role.
public virtual PrincipalPolicyFragment PolicyFragment { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
PrincipalAccount
The AWS account ID of this principal.
public virtual string? PrincipalAccount { get; }Property Value
Remarks
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.
RoleArn
Returns the ARN of this role.
public virtual string RoleArn { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
RoleId
Returns the stable and unique string identifying the role.
public virtual string RoleId { get; }Property Value
Remarks
For example, AIDAJQABLZS4A3QDU576Q.
Attribute: true
RoleName
Returns the name of the role.
public virtual string RoleName { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
RoleRef
A reference to a Role resource.
public virtual IRoleReference RoleRef { get; }Property Value
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
Methods
AddManagedPolicy(IManagedPolicy)
Attaches a managed policy to this role.
public virtual void AddManagedPolicy(IManagedPolicy policy)Parameters
- policy IManagedPolicy
The the managed policy to attach.
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
AddToPolicy(PolicyStatement)
Add to the policy of this principal.
public virtual bool AddToPolicy(PolicyStatement statement)Parameters
- statement PolicyStatement
Returns
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
AddToPrincipalPolicy(PolicyStatement)
Adds a permission to the role's default policy document.
public virtual IAddToPrincipalPolicyResult AddToPrincipalPolicy(PolicyStatement statement)Parameters
- statement PolicyStatement
The permission statement to add to the policy document.
Returns
Remarks
If there is no default policy attached to this role, it will be created.
ApplyRemovalPolicy(RemovalPolicy)
Skip applyRemovalPolicy if role synthesis is prevented by customizeRoles.
public override void ApplyRemovalPolicy(RemovalPolicy policy)Parameters
- policy RemovalPolicy
RemovalPolicy.
Overrides
Remarks
Because in this case, this construct does not have a CfnResource in the tree.
Override: true
AttachInlinePolicy(Policy)
Attaches a policy to this role.
public virtual void AttachInlinePolicy(Policy policy)Parameters
- policy Policy
The policy to attach.
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
CustomizeRoles(Construct, ICustomizeRolesOptions?)
Customize the creation of IAM roles within the given scope.
public static void CustomizeRoles(Construct scope, ICustomizeRolesOptions? options = null)Parameters
- scope Construct
construct scope to customize role creation.
- options ICustomizeRolesOptions
options for configuring role creation.
Remarks
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.
Examples
App app;
Role.CustomizeRoles(app, new CustomizeRolesOptions {
UsePrecreatedRoles = new Dictionary<string, string> {
{ "ConstructPath/To/Role", "my-precreated-role-name" }
}
});FromLookup(Construct, string, IRoleLookupOptions)
Lookup an existing Role.
public static IRole FromLookup(Construct scope, string id, IRoleLookupOptions options)Parameters
- scope Construct
- id string
- options IRoleLookupOptions
Returns
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
FromRoleArn(Construct, string, string, IFromRoleArnOptions?)
Import an external role by ARN.
public static IRole FromRoleArn(Construct scope, string id, string roleArn, IFromRoleArnOptions? options = null)Parameters
- scope Construct
construct scope.
- id string
construct id.
- roleArn string
the ARN of the role to import.
- options IFromRoleArnOptions
allow customizing the behavior of the returned role.
Returns
Remarks
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.
FromRoleName(Construct, string, string, IFromRoleNameOptions?)
Import an external role by name.
public static IRole FromRoleName(Construct scope, string id, string roleName, IFromRoleNameOptions? options = null)Parameters
- scope Construct
construct scope.
- id string
construct id.
- roleName string
the name of the role to import.
- options IFromRoleNameOptions
allow customizing the behavior of the returned role.
Returns
Remarks
The imported role is assumed to exist in the same account as the account the scope's containing Stack is being deployed to.
Grant(IPrincipal, params string[])
Grant the actions defined in actions to the identity Principal on this resource.
public virtual Grant Grant(IPrincipal grantee, params string[] actions)Parameters
- grantee IPrincipal
- actions string[]
Returns
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
GrantAssumeRole(IPrincipal)
Grant permissions to the given principal to assume this role.
public virtual Grant GrantAssumeRole(IPrincipal identity)Parameters
- identity IPrincipal
Returns
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
GrantPassRole(IPrincipal)
Grant permissions to the given principal to pass this role.
public virtual Grant GrantPassRole(IPrincipal identity)Parameters
- identity IPrincipal
Returns
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
IsRole(object)
Return whether the given object is a Role.
public static bool IsRole(object x)Parameters
- x object
Returns
Remarks
Defines an IAM role. The role is created with an assume policy document associated with
the specified AWS service principal defined in serviceAssumeRole.
ExampleMetadata: fixture=default infused
WithoutPolicyUpdates(IWithoutPolicyUpdatesOptions?)
Return a copy of this Role object whose Policies will not be updated.
public virtual IRole WithoutPolicyUpdates(IWithoutPolicyUpdatesOptions? options = null)Parameters
- options IWithoutPolicyUpdatesOptions
Returns
Remarks
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.