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.

  • To specify the maximum session duration setting for roles that are assumed using the AWS CLI or API, modify the maximum session duration setting's value. This setting can have a value from 1 hour to 12 hours. If you do not specify a value, the default maximum of 1 hour is applied.

    Note

    Anyone who assumes the role from the AWS CLI or API can use the duration-seconds CLI parameter or the DurationSeconds API parameter to request a longer session. The MaxSessionDuration setting determines the maximum duration of the role session 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.

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:

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

    "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 IAM Policies and the IAM JSON 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, choose Edit policy, and then choose the JSON tab. 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:

    { "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 and inline policies in the AWS Management Console, see Editing IAM Policies.

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

To change the maximum session duration setting for roles that are assumed using the AWS CLI or API (console)

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

  2. Choose the name of the role to modify.

  3. Next to Maximum CLI/API session duration choose a value. Or choose Custom duration and type a value (in seconds).

  4. Choose Save.

    Your changes don't take effect until the next time someone assumes this role. To learn how to revoke existing sessions for this role, see Revoking IAM Role Temporary Security Credentials.

Modifying a Role (AWS CLI)

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

To change the trusted principals that can access the role (AWS CLI)

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

  2. (Optional) To view the current trust policy for a role, run the following command:

  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:

    "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, run the following command:

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

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:

    { "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, run the following command 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 intended user or group, use one of these commands to list the users or groups 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)

  1. (Optional) To view the current permissions associated with a role, run 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, run the following command to create a new version of the managed policy:

    To update an inline policy, run the following command:

To change the description of a role (AWS CLI)

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

  2. To update a role's description, run the following command with the description parameter:

To change the maximum session duration setting for roles that are assumed using the AWS CLI (AWS CLI)

  1. (Optional) To view the current maximum session duration setting for a role, run the following command:

  2. To update a role's maximum session duration setting, run the following command with the max-sessionduration CLI parameter or the MaxSessionDuration API parameter:

    Your changes don't take effect until the next time someone assumes this role. To learn how to revoke existing sessions for this role, see Revoking IAM Role Temporary Security Credentials.

Modifying a Role (AWS API)

You can use the AWS API to modify a role.

To change the trusted principals that can access the role (AWS API)

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

  2. (Optional) To view the current trust policy for a role, call the following operation:

  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:

    "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, call the following operation:

To allow users in a trusted external account to use the role (AWS 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:

    { "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, call the following operation to upload it to IAM:

    The output of this operation 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 intended user or group, call one of these operations to list the users or groups in your account:

  3. Call one of the following operations 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 API)

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

  2. The operation 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, call the following operation to create a new version of the managed policy:

    To update an inline policy, call the following operation:

To change the description of a role (AWS API)

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

  2. To update a role's description, call the following operation with the description parameter:

To change the maximum session duration setting for roles that are assumed using the API (AWS API)

  1. (Optional) To view the current maximum session duration setting for a role, call the following operation:

  2. To update a role's maximum session duration setting, call the following operation with the max-sessionduration CLI parameter or the MaxSessionDuration API parameter:

    Your changes don't take effect until the next time someone assumes this role. To learn how to revoke existing sessions for this role, see Revoking IAM Role Temporary Security Credentials.