get-role

Retrieves information about the specified role, including the role’s path, GUID, ARN, and the role’s trust policy that grants permission to assume the role. For more information about roles, refer to Working with Roles.

Note

Policies returned by this API are URL-encoded compliant with RFC 3986. You can use a URL decoding method to convert the policy back to plain JSON text. For example, if you use Java, you can use the decode method of the java.net.URLDecoder utility class in the Java SDK. Other languages and SDKs provide similar functionality.

Refer to AWS API Documentation.

Refer to AWS help for descriptions of global parameters.

Synopsis

get-role
  --role-name <value>

Options

--role-name (string)

The name of the IAM role to get information about.

This parameter allows (through its regex pattern) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: _, +, =, ,, ., @, and -.

Refer to AWS help for descriptions of global parameters.

Examples

To get information about an IAM role

The following get-role command gets information about the role named Test-Role

aws iam get-role --role-name Test-Role

Output example:

{
  "Role": {
      "AssumeRolePolicyDocument": "<URL-encoded-JSON>",
      "RoleId": "AIDIODR4TAW7CSEXAMPLE",
      "CreateDate": "2013-04-18T05:01:58Z",
      "RoleName": "Test-Role",
      "Path": "/",
      "Arn": "arn:aws:iam::123456789012:role/Test-Role"
  }
}

The command displays the trust policy attached to the role. To list the permissions policies attached to a role, use the list-role-policies command.

For more information, refer to Creating a Role in the Using IAM guide.

Output

Role -> (structure)

A structure containing details about the IAM role.

Description -> (string)

A description of the role.

Path -> (string)

The path to the role. For more information about paths, refer to the AWS IAM Identifiers documentation.

RoleName -> (string)

The friendly name that identifies the role.

RoleId -> (string)

The stable and unique string identifying the role. For more information about IDs, refer to the AWS IAM Identifiers documentation.

Arn -> (string)

The Amazon Resource Name (ARN) specifying the role. For more information about ARNs and how to use them in policies, refer to the AWS IAM Identifiers documentation.

CreateDate -> (timestamp)

The date and time, in ISO 8601 date-time format, when the role was created.

AssumeRolePolicyDocument -> (string)

The policy that grants an entity permission to assume the role.

MaxSessionDuration -> (integer)

The maximum session duration (in seconds) for the specified role. Anyone who uses the AWS CLI, or API to assume the role can specify the duration using the optional DurationSeconds API parameter or duration-seconds CLI parameter.