Menu
AWS Identity and Access Management
User Guide

Modifying a Role

You can change or modify a role in the following ways:

  • To change who can assume a role, modify the role's trust policy.

    Note

    If the role is a service-linked role, the role's trust policy cannot be modified. Service-linked roles appear with (Service-linked role) in the Trusted entities column of the table.

  • To change the permissions allowed by the role, modify the role's permissions policy (or policies).

    Note

    If the role is a service-linked role, the role's permissions can be modified only from the service that depends on the role. Service-linked roles appear with (Service-linked role) in the Trusted entities column of the table. See the AWS documentation for your service to see whether it supports this feature.

  • To change the description of the role, modify the description text.

You can use the AWS Management Console, the AWS Command Line Tools, the Tools for Windows PowerShell, or the IAM API to make these changes.

Modifying a Role (Console)

You can use the AWS Management Console to modify a role.

To change which trusted principals can access the role (console)

  1. In the navigation pane of the IAM console, choose Roles.

  2. In the list of roles in your account, choose the name of the role that you want to modify.

  3. Choose the Trust relationships tab, and then choose Edit trust relationship.

  4. Edit the trust policy as needed. To add additional trusted principals, specify them in the Principal element. Remember that policies are written in the JSON format, and JSON arrays are surrounded by square brackets [ ] and separated by commas. As an example, the following policy snippet shows how to reference two AWS accounts in the Principal element:

    Copy
    "Principal": { "AWS": [ "arn:aws:iam::111122223333:root", "arn:aws:iam::444455556666:root" ] },

    Remember that adding an account to the trust policy of a role is only half of establishing the trust relationship. By default, no users in the trusted accounts can assume the role until the administrator for that account grants the users the permission to assume the role. To do that, the administrator adds the Amazon Resource Name (ARN) of the role to an Allow element for the sts:AssumeRole action. For more information, see the next procedure and the topic Granting a User Permissions to Switch Roles.

    If your role can be used by one or more trusted services rather than AWS accounts, then the policy might contain an element similar to the following:

    Copy
    "Principal": { "Service": [ "opsworks.amazonaws.com", "ec2.amazonaws.com" ] },
  5. When you are done editing, choose Update Trust Policy to save your changes.

    For more information about policy structure and syntax, see Overview of IAM Policies and the IAM Policy Elements Reference.

To allow users in a trusted external account to use the role (console)

For more information and detail about this procedure, see Granting a User Permissions to Switch Roles.

  1. Sign in to the trusted external AWS account.

  2. Decide whether to attach the permissions to a user or to a group. In the navigation pane of the IAM console, choose Users or Groups accordingly.

  3. Choose the name of the user or group to which you want to grant access, and then choose the Permissions tab.

  4. Do one of the following:

    • To edit a customer managed policy, choose the name of the policy and then choose Edit policy. You cannot edit an AWS managed policy. AWS managed policies appear with the AWS icon ( ). For more information about the difference between AWS managed policies and customer managed policies, see Managed Policies and Inline Policies.

    • To edit an inline policy, choose the arrow next to the name of the policy and choose Edit policy.

  5. In the policy editor, add a new Statement element that specifies the following:

    Copy
    { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::AWS account ID that contains the role:role/role name" }

    Replace the values in red with the actual values from the ARN of the role in the original account that users in this trusted external account can use.

    Remember that you can have only one Statement keyword. However, a statement can have several elements in an array, with elements separated by commas in their own curly braces { } and all of the elements surrounded by square brackets [ ].

  6. Follow the prompts on screen to finish editing the policy.

    For more information about editing customer managed policies in the AWS Management Console, see Editing Customer Managed Policies.

    For more information about editing inline policies in the AWS Management Console, see Working with Inline Policies (Console).

To change the permissions allowed by a role (console)

  1. In the navigation pane of the IAM console, choose Roles.

  2. Choose the name of the role to modify, and then choose the Permissions tab.

  3. Do one of the following:

    • To edit an existing customer managed policy, choose the name of the policy and then choose Edit policy.

      Note

      You cannot edit an AWS managed policy. AWS managed policy appear with the AWS icon ( ). For more information about the difference between AWS managed policies and customer managed policies, see Managed Policies and Inline Policies.

    • To attach an existing managed policy, choose Add permissions.

    • To edit an existing inline policy, choose the arrow next to the name of the policy and choose Edit Policy.

    • To embed a new inline policy, choose Add inline policy.

    For example policies that delegate permissions through roles, see Example Policies.

    For more information about permissions, see Overview of IAM Policies.

To change the description of a role (console)

  1. In the navigation pane of the IAM console, choose Roles.

  2. Choose the name of the role to modify.

  3. Next to Role description and on the far right, choose Edit.

  4. Type a new description in the box and choose Save.

Modifying a Role (AWS CLI, AWS Tools for Windows PowerShell, AWS API)

You can use the AWS Command Line Interface or IAM API to modify a role.

To change the trusted principals that can access the role (AWS CLI, AWS Tools for Windows PowerShell, AWS API)

  1. If you don't know the name of the role that you want to modify, use one of the following commands to list the roles in your account:

  2. (Optional) To view the current trust policy for a role, use one of the following commands:

  3. To modify the trusted principals that can access the role, create a text file with the updated trust policy. You can use any text editor to construct the policy.

    For example, the following policy snippet shows how to reference two AWS accounts in the Principal element:

    Copy
    "Principal": { "AWS": [ "arn:aws:iam::111122223333:root", "arn:aws:iam::444455556666:root" ] },

    Remember that adding an account to the trust policy of a role is only half of establishing the trust relationship. By default, no users in the trusted accounts can assume the role until the administrator for that account grants the users the permission to assume the role. To do this, the administrator must add the Amazon Resource Name (ARN) of the role to an Allow element for the sts:AssumeRole action. For more information, see the next procedure and the topic Granting a User Permissions to Switch Roles.

  4. To update the trust policy, use one of the following commands:

To allow users in a trusted external account to use the role (AWS CLI, AWS Tools for Windows PowerShellAWS API)

For more information and detail about this procedure, see Granting a User Permissions to Switch Roles.

  1. Begin by creating a policy that grants permissions to assume the role. For example, the following policy contains the minimum necessary permissions:

    Copy
    { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::AWS account ID that contains the role:role/role name" } }

    Create a JSON file that contains a policy similar to the preceding example. Replace the values in red with the actual values from the ARN of the role that users are allowed to assume. After you have created the policy, use one of the following commands to upload it to IAM:

    The output of this command contains the ARN of the policy. Make a note of this ARN because you will need to use it in a later step.

  2. Decide which user or group to attach the policy to. If you don't know the name of the user or group that you want to modify, use one of these commands to list the users or group in your account:

  3. Use one of the following commands to attach the policy that you created in a previous step to the user or group:

To change the permissions allowed by a role (AWS CLI, AWS Tools for Windows PowerShell, AWS API)

  1. (Optional) To view the current permissions associated with a role, use the following commands:

  2. The command to update permissions for the role differs depending on whether you are updating a managed policy or an inline policy.

    To update a managed policy, use one of the following commands to create a new version of the managed policy:

    To update an inline policy, use one of the following commands:

To change the description of a role (AWS CLI, AWS API)

  1. (Optional) To view the current description for a role, use the following commands:

  2. To update a role's description, use one of the following commands: