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 use a role, modify the role's trust policy.

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

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 (AWS Management Console)

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

To change which trusted principals can access the role

  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 by adding 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

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. If you see the Welcome to Managed Policies page, you chose an AWS managed policy. You cannot edit an AWS managed policy. 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 Edit Policy next to the name of the 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 Using the AWS Management Console.

To change the permissions allowed by a role

  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.

      Note

      If you see the Welcome to Managed Policies page, you chose an AWS managed policy. You cannot edit an AWS managed policy. 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 Attach Policy.

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

    • To embed a new inline policy, choose Create Role Policy.

    For example policies that delegate permissions through roles, see Examples of Policies for Delegating Access.

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

Modifying a Role (AWS Command Line Tools or the IAM 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

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

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 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 the following 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

  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: