Modifying a role (Amazon CLI) - Amazon Identity and Access Management
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Modifying a role (Amazon CLI)

You can use the Amazon Command Line Interface to modify a role. To change the set of tags on a role, see Managing tags on IAM roles (Amazon CLI or Amazon API).

Modifying a role trust policy (Amazon CLI)

To change who can assume a role, you must modify the role's trust policy. You cannot modify the trust policy for a service-linked role.

Notes
  • If a user is listed as the principal in a role's trust policy but cannot assume the role, check the user's permissions boundary. If a permissions boundary is set for the user, then it must allow the sts:AssumeRole action.

  • To allow users to assume the current role again within a role session, specify the role ARN or Amazon Web Services account ARN as a principal in the role trust policy. Amazon Web Services that provide compute resources such as Amazon EC2, Amazon ECS, Amazon EKS, and Lambda provide temporary credentials and automatically rotate these credentials. This ensures that you always have a valid set of credentials. For these services, it's not necessary to assume the current role again to obtain temporary credentials. However, if you intend to pass session tags or a session policy, you need to assume the current role again. To learn how to modify a role trust policy to add the principal role ARN or Amazon Web Services account ARN, see Modifying a role trust policy (console).

To modify a role trust policy (Amazon CLI)
  1. (Optional) 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 trust policy shows how to reference two Amazon Web Services accounts in the Principal element. This allows users within two separate Amazon Web Services accounts to assume this role.

    { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"AWS": [ "arn:aws:iam::111122223333:root", "arn:aws:iam::444455556666:root" ]}, "Action": "sts:AssumeRole" } }

    If you specify a principal in another account, adding an account to the trust policy of a role is only half of establishing the cross-account trust relationship. By default, no users in the trusted accounts can assume the role. The administrator for the newly trusted account must grant the users the permission to assume the role. To do that, the administrator must create or edit a policy that is attached to the user to allow the user access to the sts:AssumeRole action. For more information, see the following procedure or Granting a user permissions to switch roles.

  4. To use the file that you just created to update the trust policy, run the following command:

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

For more information and detail about this procedure, see Granting a user permissions to switch roles.

  1. Create a JSON file that contains a permissions 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-cn:iam::ACCOUNT-ID-THAT-CONTAINS-ROLE:role/ROLE-NAME" } }

    Replace the ARN in the statement with the ARN of the role that the user can assume.

  2. Run the following command to upload the JSON file that contains the trust policy to IAM:

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

  3. 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 the following commands to list the users or groups in your account:

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

Modifying a role permissions policy (Amazon CLI)

To change the permissions allowed by the role, modify the role's permissions policy (or policies). You cannot modify the permissions policy for a service-linked role in IAM. You might be able to modify the permissions policy within the service that depends on the role. To check whether a service supports this feature, see Amazon services that work with IAM and look for the services that have Yes in the Service-linked roles column. Choose a Yes with a link to view the service-linked role documentation for that service.

To change the permissions allowed by a role (Amazon CLI)
  1. (Optional) To view the current permissions associated with a role, run the following commands:

    1. aws iam list-role-policies to list inline policies

    2. aws iam list-attached-role-policies to list managed policies

  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:

Modifying a role description (Amazon CLI)

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

To change the description of a role (Amazon 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:

Modifying a role maximum session duration (Amazon CLI)

To specify the maximum session duration setting for roles that are assumed using the Amazon 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. This setting does not limit sessions assumed by Amazon services.

Note

Anyone who assumes the role from the Amazon 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.

To change the maximum session duration setting for roles that are assumed using the Amazon CLI (Amazon 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-session-duration 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 permissions boundary (Amazon CLI)

To change the maximum permissions allowed for a role, modify the role's permissions boundary.

To change the managed policy used to set the permissions boundary for a role (Amazon CLI)
  1. (Optional) To view the current permissions boundary for a role, run the following command:

  2. To use a different managed policy to update the permissions boundary for a role, run the following command:

    A role can have only one managed policy set as a permissions boundary. If you change the permissions boundary, you change the maximum permissions allowed for a role.