**This documentation is for Version 1 of the Amazon CLI only.**

We announced the upcoming end-of-support for the Amazon CLI version 1. We recommend that you migrate to the Amazon CLI version 2. For dates, additional details, and information on how to migrate, see the [announcement](https://amazonaws-china.com/blogs/developer/cli-v1-maintenance-mode-announcement/). For documentation related to Version 2 of the Amazon CLI, see the [Version 2 User Guide](https://docs.amazonaws.cn/cli/latest/userguide/).

# Using IAM in the Amazon CLI
<a name="cli-services-iam"></a>


| An introduction to Amazon Identity and Access Management | 
| --- | 
|    | 

You can access the features of Amazon Identity and Access Management (IAM) using the Amazon Command Line Interface (Amazon CLI). To list the Amazon CLI commands for IAM, use the following command.

```
aws iam help
```

This topic shows examples of Amazon CLI commands that perform common tasks for IAM.

Before you run any commands, set your default credentials. For more information, see [Configuring settings for the Amazon CLI](cli-chap-configure.md).

For more information on the IAM service, see the [Amazon Identity and Access Management User Guide](https://docs.amazonaws.cn/IAM/latest/UserGuide/introduction.html).

**Topics**
+ [Creating IAM users and groups](#cli-services-iam-new-user-group)
+ [Attaching an IAM managed policy to a user](#cli-services-iam-policy)
+ [Setting an initial password for an IAM user](#cli-services-iam-set-pw)
+ [Creating an access key for an IAM user](#cli-services-iam-create-creds)

## Creating IAM users and groups
<a name="cli-services-iam-new-user-group"></a>

**To create a group and add a new user to it**

1. Use the [https://docs.amazonaws.cn/cli/v1/reference/iam/create-group.html](https://docs.amazonaws.cn/cli/v1/reference/iam/create-group.html) command to create the group.

   ```
   $ aws iam create-group --group-name {{MyIamGroup}}
   {
       "Group": {
           "GroupName": "MyIamGroup",
           "CreateDate": "2018-12-14T03:03:52.834Z",
           "GroupId": "AGPAJNUJ2W4IJVEXAMPLE",
           "Arn": "arn:aws-cn:iam::123456789012:group/{{MyIamGroup}}",
           "Path": "/"
       }
   }
   ```

1. Use the [https://docs.amazonaws.cn/cli/v1/reference/iam/create-user.html](https://docs.amazonaws.cn/cli/v1/reference/iam/create-user.html) command to create the user.

   ```
   $ aws iam create-user --user-name {{MyUser}}
   {
       "User": {
           "UserName": "{{MyUser}}",
           "Path": "/",
           "CreateDate": "2018-12-14T03:13:02.581Z",
           "UserId": "AIDAJY2PE5XUZ4EXAMPLE",
           "Arn": "arn:aws-cn:iam::123456789012:user/{{MyUser}}"
       }
   }
   ```

1. Use the [https://docs.amazonaws.cn/cli/v1/reference/iam/add-user-to-group.html](https://docs.amazonaws.cn/cli/v1/reference/iam/add-user-to-group.html) command to add the user to the group.

   ```
   $ aws iam add-user-to-group --user-name {{MyUser}} --group-name {{MyIamGroup}}
   ```

1. To verify that the `MyIamGroup` group contains the `MyUser`, use the [https://docs.amazonaws.cn/cli/v1/reference/iam/get-group.html](https://docs.amazonaws.cn/cli/v1/reference/iam/get-group.html) command.

   ```
   $ aws iam get-group --group-name {{MyIamGroup}}
   {
       "Group": {
           "GroupName": "{{MyIamGroup}}",
           "CreateDate": "2018-12-14T03:03:52Z",
           "GroupId": "AGPAJNUJ2W4IJVEXAMPLE",
           "Arn": "arn:aws-cn:iam::123456789012:group/{{MyIamGroup}}",
           "Path": "/"
       },
       "Users": [
           {
               "UserName": "{{MyUser}}",
               "Path": "/",
               "CreateDate": "2018-12-14T03:13:02Z",
               "UserId": "AIDAJY2PE5XUZ4EXAMPLE",
               "Arn": "arn:aws-cn:iam::123456789012:user/{{MyUser}}"
           }
       ],
       "IsTruncated": "false"
   }
   ```

## Attaching an IAM managed policy to a user
<a name="cli-services-iam-policy"></a>

The policy in this example provides the user with "Power User Access".

**To attach an IAM managed policy to a user**

1. Determine the Amazon Resource Name (ARN) of the policy to attach. The following command uses `list-policies` to find the ARN of the policy with the name `PowerUserAccess`. It then stores that ARN in an environment variable.

   ```
   $ export {{POLICYARN}}=$(aws iam list-policies --query 'Policies[?PolicyName==`PowerUserAccess`].{ARN:Arn}' --output text)       ~
   $ echo ${{POLICYARN}}
   arn:aws-cn:iam::aws:policy/PowerUserAccess
   ```

1. To attach the policy, use the [https://docs.amazonaws.cn/cli/v1/reference/iam/attach-user-policy.html](https://docs.amazonaws.cn/cli/v1/reference/iam/attach-user-policy.html)[https://docs.amazonaws.cn/cli/latest/reference/iam/attach-user-policy.html](https://docs.amazonaws.cn/cli/latest/reference/iam/attach-user-policy.html) command, and reference the environment variable that holds the policy ARN.

   ```
   $ aws iam attach-user-policy --user-name {{MyUser}} --policy-arn ${{POLICYARN}}
   ```

1. Verify that the policy is attached to the user by running the [https://docs.amazonaws.cn/cli/v1/reference/iam/list-attached-user-policies.html](https://docs.amazonaws.cn/cli/v1/reference/iam/list-attached-user-policies.html) command.

   ```
   $ aws iam list-attached-user-policies --user-name {{MyUser}}
   {
       "AttachedPolicies": [
           {
               "PolicyName": "PowerUserAccess",
               "PolicyArn": "arn:aws-cn:iam::aws:policy/PowerUserAccess"
           }
       ]
   }
   ```

For more information, see [Access Management Resources](https://docs.amazonaws.cn/IAM/latest/UserGuide/policies-additional-resources.html). This topic provides links to an overview of permissions and policies, and links to examples of policies for accessing Amazon S3, Amazon EC2, and other services.

## Setting an initial password for an IAM user
<a name="cli-services-iam-set-pw"></a>

The following command uses `[create-login-profile](https://docs.amazonaws.cn/cli/v1/reference/iam/create-login-profile.html)` to set an initial password on the specified user. When the user signs in for the first time, the user is required to change the password to something that only the user knows.

```
$ aws iam create-login-profile --user-name {{MyUser}} --password {{My!User1Login8P@ssword}} --password-reset-required
{
    "LoginProfile": {
        "UserName": "{{MyUser}}",
        "CreateDate": "2018-12-14T17:27:18Z",
        "PasswordResetRequired": true
    }
}
```

You can use the `update-login-profile` command to *change* the password for a user.

```
$ aws iam update-login-profile --user-name {{MyUser}} --password {{My!User1ADifferentP@ssword}}
```

## Creating an access key for an IAM user
<a name="cli-services-iam-create-creds"></a>

You can use the [https://docs.amazonaws.cn/cli/v1/reference/iam/create-access-key.html](https://docs.amazonaws.cn/cli/v1/reference/iam/create-access-key.html) command to create an access key for a user. An access key is a set of security credentials that consists of an access key ID and a secret key. 

A user can create only two access keys at one time. If you try to create a third set, the command returns a `LimitExceeded` error.

```
$ aws iam create-access-key --user-name {{MyUser}}
{
    "AccessKey": {
        "UserName": "{{MyUser}}",
        "AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
        "Status": "Active",
        "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "CreateDate": "2018-12-14T17:34:16Z"
    }
}
```

Use the [https://docs.amazonaws.cn/cli/v1/reference/iam/delete-access-key.html](https://docs.amazonaws.cn/cli/v1/reference/iam/delete-access-key.html) command to delete an access key for a user. Specify which access key to delete by using the access key ID.

```
$ aws iam delete-access-key --user-name {{MyUser}} --access-key-id AKIAIOSFODNN7EXAMPLE
```