Table of Contents

Class Role

Namespace
Amazon.CDK.AWS.IAM
Assembly
Amazon.CDK.AWS.IAM.dll

IAM Role.

public class Role : Resource, IRole, IIdentity, IPrincipal, IGrantable, IResource, IConstruct, IConstruct, IDependable
Inheritance
Role
Implements
IResource
IConstruct
IConstruct
IDependable

Examples

var lambdaRole = new Role(this, "Role", new RoleProps {
                 AssumedBy = new ServicePrincipal("lambda.amazonaws.com"),
                 Description = "Example role..."
             });

             var stream = new Stream(this, "MyEncryptedStream", new StreamProps {
                 Encryption = StreamEncryption.KMS
             });

             // give lambda permissions to read stream
             stream.GrantRead(lambdaRole);

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

Constructors

Role(Construct, string, IRoleProps) 

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

Parameters

scope Construct
id 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

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

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

string

RoleId

Returns the stable and unique string identifying the role.

public virtual string RoleId { get; }

Property Value

string

Remarks

For example, AIDAJQABLZS4A3QDU576Q.

Attribute: true

RoleName

Returns the name of the role.

public virtual string RoleName { get; }

Property Value

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

bool

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.

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

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)

Import an external role by name.

public static IRole FromRoleName(Construct scope, string id, string roleName)

Parameters

scope Construct
id string
roleName string

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

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

Validate()

Validate the current construct.

protected override string[] Validate()

Returns

string[]

Remarks

This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.

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.