Skip to main content

role

Gets an individual role resource

Overview

Namerole
TypeResource
Descriptionrole
Idawscc.iam.role

Fields

NameDatatypeDescription
arnstring
assume_role_policy_documentobjectThe trust policy that is associated with this role. Trust policies define which entities can assume the role. You can associate only one trust policy with a role. For an example of a policy that can be used to assume a role, see [Template Examples](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#aws-resource-iam-role--examples). For more information about the elements that you can use in an IAM policy, see [Policy Elements Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *User Guide*.
descriptionstringA description of the role that you provide.
managed_policy_arnsarrayA list of Amazon Resource Names (ARNs) of the IAM managed policies that you want to attach to the role.<br/> For more information about ARNs, see [Amazon Resource Names (ARNs) and Service Namespaces](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in the *General Reference*.
max_session_durationintegerThe maximum session duration (in seconds) that you want to set for the specified role. If you do not specify a value for this setting, the default value of one hour is applied. This setting can have a value from 1 hour to 12 hours.<br/> Anyone who assumes the role from the 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. For more information, see [Using IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) in the *IAM User Guide*.
pathstringThe path to the role. For more information about paths, see [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html) in the *IAM User Guide*.<br/> This parameter is optional. If it is not included, it defaults to a slash (/).<br/> This parameter allows (through its [regex pattern](https://docs.aws.amazon.com/http://wikipedia.org/wiki/regex)) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (``\u0021``) through the DEL character (``\u007F``), including most punctuation characters, digits, and upper and lowercased letters.
permissions_boundarystringThe ARN of the policy used to set the permissions boundary for the role.<br/> For more information about permissions boundaries, see [Permissions boundaries for IAM identities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*.
policiesarrayAdds or updates an inline policy document that is embedded in the specified IAM role.<br/> When you embed an inline policy in a role, the inline policy is used as part of the role's access (permissions) policy. The role's trust policy is created at the same time as the role. You can update a role's trust policy later. For more information about IAM roles, go to [Using Roles to Delegate Permissions and Federate Identities](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-toplevel.html).<br/> A role can also have an attached managed policy. For information about policies, see [Managed Policies and Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/policies-managed-vs-inline.html) in the *User Guide*.<br/> For information about limits on the number of inline policies that you can embed with a role, see [Limitations on Entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/LimitationsOnEntities.html) in the *User Guide*.<br/> If an external policy (such as ``AWS::IAM::Policy`` or
role_idstring
role_namestringA name for the IAM role, up to 64 characters in length. For valid values, see the ``RoleName`` parameter for the [CreateRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html) action in the *User Guide*.<br/> This parameter allows (per its [regex pattern](https://docs.aws.amazon.com/http://wikipedia.org/wiki/regex)) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: _+=,.@-. The role name must be unique within the account. Role names are not distinguished by case. For example, you cannot create roles named both "Role1" and "role1".<br/> If you don't specify a name, CFN generates a unique physical ID and uses that ID for the role name.<br/> If you specify a name, you must specify the ``CAPABILITY_NAMED_IAM`` value to acknowledge your template's capabilities. For more information, see [Acknowledging Resources in Templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/Use
tagsarrayA list of tags that are attached to the role. For more information about tagging, see [Tagging IAM resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*.
regionstringAWS region.

Methods

Currently only SELECT is supported for this resource resource.

Example

SELECT
region,
arn,
assume_role_policy_document,
description,
managed_policy_arns,
max_session_duration,
path,
permissions_boundary,
policies,
role_id,
role_name,
tags
FROM awscc.iam.role
WHERE data__Identifier = '<RoleName>';

Permissions

To operate on the role resource, the following permissions are required:

Read

iam:GetRole,
iam:ListAttachedRolePolicies,
iam:ListRolePolicies,
iam:GetRolePolicy

Update

iam:UpdateRole,
iam:UpdateRoleDescription,
iam:UpdateAssumeRolePolicy,
iam:DetachRolePolicy,
iam:AttachRolePolicy,
iam:DeleteRolePermissionsBoundary,
iam:PutRolePermissionsBoundary,
iam:DeleteRolePolicy,
iam:PutRolePolicy,
iam:TagRole,
iam:UntagRole

Delete

iam:DeleteRole,
iam:DetachRolePolicy,
iam:DeleteRolePolicy,
iam:GetRole,
iam:ListAttachedRolePolicies,
iam:ListRolePolicies,
iam:TagRole,
iam:UntagRole