Class Role

IAM Role.

Inheritance

System.Object

Resource

Role

Implements

Constructs.IConstruct

Constructs.IDependable

Inherited Members

Resource.IsOwnedResource(IConstruct)

Resource.IsResource(IConstruct)

Resource.ApplyRemovalPolicy(RemovalPolicy)

Resource.GeneratePhysicalName()

Resource.GetResourceArnAttribute(String, IArnComponents)

Resource.GetResourceNameAttribute(String)

Resource.Env

Resource.PhysicalName

Resource.Stack

Namespace: Amazon.CDK.AWS.IAM

Assembly: Amazon.CDK.Lib.dll

Syntax (csharp)

public class Role : Resource, IRole, IIdentity, IPrincipal, IGrantable, IResource

Syntax (vb)

Public Class Role
    Inherits Resource
    Implements IRole, IIdentity, IPrincipal, IGrantable, IResource

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: infused

Examples

// Option 3: Create a new role that allows the account root principal to assume. Add this role in the `system:masters` and witch to this role from the AWS console.
Cluster cluster;


var consoleReadOnlyRole = new Role(this, "ConsoleReadOnlyRole", new RoleProps {
    AssumedBy = new ArnPrincipal("arn_for_trusted_principal")
});
consoleReadOnlyRole.AddToPolicy(new PolicyStatement(new PolicyStatementProps {
    Actions = new [] { "eks:AccessKubernetesApi", "eks:Describe*", "eks:List*" },
    Resources = new [] { cluster.ClusterArn }
}));

// Add this role to system:masters RBAC group
cluster.AwsAuth.AddMastersRole(consoleReadOnlyRole);

Synopsis

Constructors

Role(ByRefValue)	Used by jsii to construct an instance of this class from a Javascript-owned object reference
Role(DeputyBase.DeputyProps)	Used by jsii to construct an instance of this class from DeputyProps
Role(Construct, String, IRoleProps)

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.
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.

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.
AttachInlinePolicy(Policy)	Attaches a policy to this role.
CustomizeRoles(Construct, ICustomizeRolesOptions)	Customize the creation of IAM roles within the given scope.
FromRoleArn(Construct, String, String, IFromRoleArnOptions)	Import an external role by ARN.
FromRoleName(Construct, String, String, IFromRoleNameOptions)	Import an external role by name.
Grant(IPrincipal, 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(ByRefValue)

Used by jsii to construct an instance of this class from a Javascript-owned object reference

protected Role(ByRefValue reference)

Parameters

reference Amazon.JSII.Runtime.Deputy.ByRefValue: The Javascript-owned object reference

Role(DeputyBase.DeputyProps)

Used by jsii to construct an instance of this class from DeputyProps

protected Role(DeputyBase.DeputyProps props)

Parameters

props Amazon.JSII.Runtime.Deputy.DeputyBase.DeputyProps: The deputy props

Role(Construct, String, IRoleProps)

public Role(Construct scope, string id, IRoleProps props)

Parameters

scope Constructs.Construct
id System.String
props IRoleProps

Properties

AssumeRoleAction

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

public virtual string AssumeRoleAction { get; }

Property Value

System.String

AssumeRolePolicy

The assume role policy document associated with this role.

public virtual PolicyDocument AssumeRolePolicy { get; }

Property Value

PolicyDocument

GrantPrincipal

The principal to grant permissions to.

public virtual IPrincipal GrantPrincipal { get; }

Property Value

IPrincipal

PermissionsBoundary

Returns the permissions boundary attached to this role.

public virtual IManagedPolicy PermissionsBoundary { get; }

Property Value

IManagedPolicy

PolicyFragment

Returns the role.

public virtual PrincipalPolicyFragment PolicyFragment { get; }

Property Value

PrincipalPolicyFragment

PrincipalAccount

The AWS account ID of this principal.

public virtual string PrincipalAccount { get; }

Property Value

System.String

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

System.String

RoleId

Returns the stable and unique string identifying the role.

public virtual string RoleId { get; }

Property Value

System.String

Remarks

For example, AIDAJQABLZS4A3QDU576Q.

Attribute: true

RoleName

Returns the name of the role.

public virtual string RoleName { get; }

Property Value

System.String

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.

AddToPolicy(PolicyStatement)

Add to the policy of this principal.

public virtual bool AddToPolicy(PolicyStatement statement)

Parameters

statement PolicyStatement

Returns

System.Boolean

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

IAddToPrincipalPolicyResult

Remarks

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

AttachInlinePolicy(Policy)

Attaches a policy to this role.

public virtual void AttachInlinePolicy(Policy policy)

Parameters

policy Policy: The policy to attach.

CustomizeRoles(Construct, ICustomizeRolesOptions)

Customize the creation of IAM roles within the given scope.

public static void CustomizeRoles(Construct scope, ICustomizeRolesOptions options = null)

Parameters

scope Constructs.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" }
    }
});

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 Constructs.Construct: construct scope.
id System.String: construct id.
roleArn System.String: the ARN of the role to import.
options IFromRoleArnOptions: allow customizing the behavior of the returned role.

Returns

IRole

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 Constructs.Construct: construct scope.
id System.String: construct id.
roleName System.String: the name of the role to import.
options IFromRoleNameOptions: allow customizing the behavior of the returned role.

Returns

IRole

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, 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 System.String[]

Returns

Grant

GrantAssumeRole(IPrincipal)

Grant permissions to the given principal to assume this role.

public virtual Grant GrantAssumeRole(IPrincipal identity)

Parameters

identity IPrincipal

Returns

Grant

GrantPassRole(IPrincipal)

Grant permissions to the given principal to pass this role.

public virtual Grant GrantPassRole(IPrincipal identity)

Parameters

identity IPrincipal

Returns

Grant

IsRole(Object)

Return whether the given object is a Role.

public static bool IsRole(object x)

Parameters

x System.Object

Returns

System.Boolean

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

IRole

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.

Implements

IRole

IIdentity

IPrincipal

IGrantable

IResource

Constructs.IConstruct

Constructs.IDependable