**This documentation is for Version 1 of the AWS CLI only.** We announced the upcoming end-of-support for the AWS CLI version 1. We recommend that you migrate to the AWS CLI version 2. For dates, additional details, and information on how to migrate, see the [announcement](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/). For documentation related to Version 2 of the AWS CLI, see the [Version 2 User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). # Authentication and access credentials for the AWS CLI You must establish how the AWS CLI authenticates with AWS when you develop with AWS services. To configure credentials for programmatic access for the AWS CLI, choose one of the following options. The options are in order of recommendation. **** | Authentication type | Purpose | Instructions | | --- | --- | --- | | IAM user short-term credentials | Use IAM user short-term credentials, which are more secure than long-term credentials. If your credentials are compromised, there is a limited time they can be used before they expire. | [Authenticating with short-term credentials for the AWS CLI](cli-authentication-short-term.md) | | IAM on an Amazon EC2 instance. | Use Amazon EC2 instance metadata to query for temporary credentials using the role assigned to the Amazon EC2 instance. | [Using Amazon EC2 instance metadata as credentials in the AWS CLI](cli-configure-metadata.md) | | Assume roles for permissions | Pair another credential method and assume a role for temporary access to AWS services your user might not have access to. | [Using an IAM role in the AWS CLI](cli-configure-role.md) | | IAM user long-term credentials | (Not recommended) Use long-term credentials, which have no expiration. | [Authenticating using IAM user credentials for the AWS CLI](cli-authentication-user.md) | | External storage of IAM | (Not recommended) Pair another credential method but store credential values in a location outside of the AWS CLI. This method is only as secure as the external location the credentials are stored. | [Sourcing credentials with an external process in the AWS CLI](cli-configure-sourcing-external.md) | ## Configuration and credential precedence Credentials and configuration settings are located in multiple places, such as the system or user environment variables, local AWS configuration files, or explicitly declared on the command line as a parameter. Certain locations take precedence over others. The AWS CLI credentials and configuration settings take precedence in the following order: 1. **[Command line options](cli-configure-options.md)** – Overrides settings in any other location, such as the `--region`, `--output`, and `--profile` parameters. 1. **[Environment variables](cli-configure-envvars.md)** – You can store values in your system's environment variables. 1. **[Assume role](cli-configure-role.md)** – Assume the permissions of an IAM role through configuration or the [https://docs.aws.amazon.com/cli/v1/reference/sts/assume-role.html](https://docs.aws.amazon.com/cli/v1/reference/sts/assume-role.html) command. 1. **[Assume role with web identity](cli-configure-role.md)** – Assume the permissions of an IAM role using web identity through configuration or the [https://docs.aws.amazon.com/cli/v1/reference/sts/assume-role-with-web-identity.html](https://docs.aws.amazon.com/cli/v1/reference/sts/assume-role-with-web-identity.html) command. 1. **[Credentials file](cli-configure-files.md)** – The `credentials` and `config` file are updated when you run the command `aws configure`. The `credentials` file is located at `~/.aws/credentials` on Linux or macOS, or at `C:\Users\USERNAME\.aws\credentials` on Windows. 1. **[Custom process](cli-configure-sourcing-external.md)** – Get your credentials from an external source. 1. **[Configuration file](cli-configure-files.md)** – The `credentials` and `config` file are updated when you run the command `aws configure`. The `config` file is located at `~/.aws/config` on Linux or macOS, or at `C:\Users\USERNAME\.aws\config` on Windows. 1. **[Container credentials](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)** – You can associate an IAM role with each of your Amazon Elastic Container Service (Amazon ECS) task definitions. Temporary credentials for that role are then available to that task's containers. For more information, see [IAM Roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) in the *Amazon Elastic Container Service Developer Guide*. 1. **[Amazon EC2 instance profile credentials](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)** – You can associate an IAM role with each of your Amazon Elastic Compute Cloud (Amazon EC2) instances. Temporary credentials for that role are then available to code running in the instance. The credentials are delivered through the Amazon EC2 metadata service. For more information, see [IAM Roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) in the *Amazon EC2 User Guide* and [Using Instance Profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) in the *IAM User Guide*. ## Additional topics in this section + [Authenticating with short-term credentials for the AWS CLI](cli-authentication-short-term.md) + [Using an IAM role in the AWS CLI](cli-configure-role.md) + [Authenticating using IAM user credentials for the AWS CLI](cli-authentication-user.md) + [Using Amazon EC2 instance metadata as credentials in the AWS CLI](cli-configure-metadata.md) + [Sourcing credentials with an external process in the AWS CLI](cli-configure-sourcing-external.md) # Authenticating with short-term credentials for the AWS CLI We recommend configuring your SDK or tool to use [IAM Identity Center authentication](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html) with extended session duration options. However, you can copy and use temporary credentials that are available in the AWS access portal. New credentials will need to be copied when these expire. You can use the temporary credentials in a profile or use them as values for system properties and environment variables. 1. [Sign in to the AWS access portal](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosignin.html). 1. Follow [these instructions](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html) to copy IAM role credentials from the AWS access portal. 1. For step 2 in the linked instructions, choose the AWS account and IAM role name that grants access for your development needs. This role typically has a name like **PowerUserAccess** or **Developer**. 1. For step 4, select the **Add a profile to your AWS credentials file** option and copy the contents. 1. Create or open the shared `credentials` file. This file is `~/.aws/credentials` on Linux and macOS systems, and `%USERPROFILE%\.aws\credentials` on Windows. For more information, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md). 1. Add the following text to the shared `credentials` file. Replace the sample values with the credentials you copied. ``` [default] aws_access_key_id = AKIAIOSFODNN7EXAMPLE aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token = IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` 1. Add your preferred default region and format to the shared `config` file. ``` [default] region=us-west-2 output=json [profile user1] region=us-east-1 output=text ``` When the SDK creates a service client, it will access these temporary credentials and use them for each request. The settings for the IAM role chosen in step 2a determine [how long the temporary credentials are valid](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html). The maximum duration is twelve hours. Repeat these steps each time your credentials expire. # Using an IAM role in the AWS CLI An [AWS Identity and Access Management (IAM) role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) is an authorization tool that lets a user gain additional (or different) permissions, or get permissions to perform actions in a different AWS account. **Topics** + [ ## Prerequisites ](#cli-role-prereqs) + [ ## Overview of using IAM roles ](#cli-role-overview) + [ ## Configuring and using a role ](#cli-role-prepare) + [ ## Using multi-factor authentication ](#cli-configure-role-mfa) + [ ## Cross-account roles and external ID ](#cli-configure-role-xaccount) + [ ## Specifying a role session name for easier auditing ](#cli-configure-role-session-name) + [ ## Assume role with web identity ](#cli-configure-role-oidc) + [ ## Clearing cached credentials ](#cli-configure-role-cache) ## Prerequisites To run the `iam` commands, you need to install and configure the AWS CLI. This includes setting up a configured profile, as assuming a role is paired with another credential method. For more information, see [Installing, updating, and uninstalling the AWS CLI](cli-chap-install.md). ## Overview of using IAM roles You can configure the AWS Command Line Interface (AWS CLI) to use an IAM role by defining a profile for the role in the `~/.aws/config` file. The following example shows a role profile named `marketingadmin`. If you run commands with `--profile marketingadmin` (or specify it with the [AWS\$1PROFILE environment variable](cli-configure-envvars.md)), the AWS CLI uses the credentials defined in a separate profile `user1` to assume the role with the Amazon Resource Name (ARN) `arn:aws:iam::123456789012:role/marketingadminrole`. You can run any operations that are allowed by the permissions assigned to that role. ``` [profile marketingadmin] role_arn = arn:aws:iam::123456789012:role/marketingadminrole source_profile = user1 ``` You can then specify a `source_profile` that points to a separate named profile that contains user credentials with permission to use the role. In the previous example, the `marketingadmin` profile uses the credentials in the `user1` profile. When you specify that an AWS CLI command is to use the profile `marketingadmin`, the AWS CLI automatically looks up the credentials for the linked `user1` profile and uses them to request temporary credentials for the specified IAM role. The CLI uses the [sts:AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) operation in the background to accomplish this. Those temporary credentials are then used to run the requested AWS CLI command. The specified role must have attached IAM permission policies that allow the requested AWS CLI command to run. To run a AWS CLI command from within an Amazon Elastic Compute Cloud (Amazon EC2) instance or an Amazon Elastic Container Service (Amazon ECS) container, you can use an IAM role attached to the instance profile or the container. If you specify no profile or set no environment variables, that role is used directly. This enables you to avoid storing long-lived access keys on your instances. You can also use those instance or container roles only to get credentials for another role. To do this, you use `credential_source` (instead of `source_profile`) to specify how to find the credentials. The `credential_source` attribute supports the following values: + `Environment` – Retrieves the source credentials from environment variables. + `Ec2InstanceMetadata` – Uses the IAM role attached to the Amazon EC2 instance profile. + `EcsContainer` – Uses the IAM role attached to the Amazon ECS container. The following example shows the same `marketingadminrole` role used by referencing an Amazon EC2 instance profile. ``` [profile marketingadmin] role_arn = arn:aws:iam::123456789012:role/marketingadminrole credential_source = Ec2InstanceMetadata ``` When you invoke a role, you have additional options that you can require, such as the use of multi-factor authentication and an External ID (used by third-party companies to access their clients' resources). You can also specify unique role session names that can be more easily audited in AWS CloudTrail logs. ## Configuring and using a role When you run commands using a profile that specifies an IAM role, the AWS CLI uses the source profile's credentials to call AWS Security Token Service (AWS STS) and request temporary credentials for the specified role. The user in the source profile must have permission to call `sts:assume-role` for the role in the specified profile. The role must have a trust relationship that allows the user in the source profile to use the role. The process of retrieving and then using temporary credentials for a role is often referred to as *assuming the role*. You can create a role in IAM with the permissions that you want users to assume by following the procedure under [Creating a Role to Delegate Permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) in the *AWS Identity and Access Management User Guide*. If the role and the source profile's user are in the same account, you can enter your own account ID when configuring the role's trust relationship. After creating the role, modify the trust relationship to allow the user to assume it. The following example shows a trust policy that you could attach to a role. This policy allows the role to be assumed by any user in the account 123456789012, ***if*** the administrator of that account explicitly grants the `sts:AssumeRole` permission to the user. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:root" }, "Action": "sts:AssumeRole" } ] } ``` ------ The trust policy doesn't actually grant permissions. The administrator of the account must delegate the permission to assume the role to individual users by attaching a policy with the appropriate permissions. The following example shows a policy that you can attach to a user that allows the user to assume only the `marketingadminrole` role. For more information about granting a user access to assume a role, see [Granting a User Permission to Switch Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html) in the *IAM User Guide*. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::123456789012:role/marketingadminrole" } ] } ``` ------ The user doesn't need to have additional permissions to run the AWS CLI commands using the role profile. Instead, the permissions to run the command come from those attached to the *role*. You attach permission policies to the role to specify which actions can be performed against which AWS resources. For more information about attaching permissions to a role (which works identically to a user), see [Changing Permissions for an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) in the *IAM User Guide*. Now that you have the role profile, role permissions, role trust relationship, and user permissions correctly configured, you can use the role at the command line by invoking the `--profile` option. For example, the following calls the Amazon S3 `ls` command using the permissions attached to the `marketingadmin` role as defined by the example at the beginning of this topic. ``` $ aws s3 ls --profile marketingadmin ``` To use the role for several calls, you can set the `AWS_PROFILE` environment variable for the current session from the command line. While that environment variable is defined, you don't have to specify the `--profile` option on each command. **Linux or macOS** ``` $ export AWS_PROFILE=marketingadmin ``` **Windows** ``` C:\> setx AWS_PROFILE marketingadmin ``` For more information about configuring users and roles, see [IAM Identities (users, user groups, and roles)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) and [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id-roles.html) in the *IAM User Guide*. ## Using multi-factor authentication For additional security, you can require that users provide a one-time key generated from a multi-factor authentication (MFA) device, a U2F device, or mobile app when they attempt to make a call using the role profile. First, you can choose to modify the trust relationship on the IAM role to require MFA. This prevents anyone from using the role without first authenticating by using MFA. For an example, see the `Condition` line in the following example. This policy allows the user named `anika` to assume the role the policy is attached to, but only if they authenticate by using MFA. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/anika" }, "Action": "sts:AssumeRole", "Condition": { "Bool": { "aws:multifactorAuthPresent": true } } } ] } ``` ------ Next, add a line to the role profile that specifies the ARN of the user's MFA device. The following sample `config` file entries show two role profiles that both use the access keys for the user `anika` to request temporary credentials for the role `cli-role`. The user `anika` has permissions to assume the role, granted by the role's trust policy. ``` [profile role-without-mfa] region = us-west-2 role_arn= arn:aws:iam::128716708097:role/cli-role source_profile=cli-user [profile role-with-mfa] region = us-west-2 role_arn= arn:aws:iam::128716708097:role/cli-role source_profile = cli-user mfa_serial = arn:aws:iam::128716708097:mfa/cli-user [profile cli-user] region = us-west-2 output = json ``` The `mfa_serial` setting can take an ARN, as shown, or the serial number of a hardware MFA token. The first profile, `role-without-mfa`, doesn't require MFA. However, because the previous example trust policy attached to the role requires MFA, any attempt to run a command with this profile fails. ``` $ aws iam list-users --profile role-without-mfa An error occurred (AccessDenied) when calling the AssumeRole operation: Access denied ``` The second profile entry, `role-with-mfa`, identifies an MFA device to use. When the user attempts to run a AWS CLI command with this profile, the AWS CLI prompts the user to enter the one-time password (OTP) that the MFA device provides. If the MFA authentication succeeds, the command performs the requested operation. The OTP is not displayed on the screen. ``` $ aws iam list-users --profile role-with-mfa Enter MFA code for arn:aws:iam::123456789012:mfa/cli-user: { "Users": [ { ... ``` ## Cross-account roles and external ID You can enable users to use roles that belong to different accounts by configuring the role as a cross-account role. During role creation, set the role type to **Another AWS account**, as described in [Creating a Role to Delegate Permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html). Optionally, select **Require MFA**. **Require MFA** configures the appropriate condition in the trust relationship, as described in [Using multi-factor authentication](#cli-configure-role-mfa). If you use an [external ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) to provide additional control over who can use a role across accounts, you must also add the `external_id` parameter to the role profile. You typically use this only when the other account is controlled by someone outside your company or organization. ``` [profile crossaccountrole] role_arn = arn:aws:iam::234567890123:role/SomeRole source_profile = default mfa_serial = arn:aws:iam::123456789012:mfa/saanvi external_id = 123456 ``` ## Specifying a role session name for easier auditing When many individuals share a role, auditing becomes more of a challenge. You want to associate each operation invoked with the individual who invoked the action. However, when the individual uses a role, the assumption of the role by the individual is a separate action from the invoking of an operation, and you must manually correlate the two. You can simplify this by specifying unique role session names when users assume a role. You do this by adding a `role_session_name` parameter to each named profile in the `config` file that specifies a role. The `role_session_name` value is passed to the `AssumeRole` operation and becomes part of the ARN for the role session. It is also included in the AWS CloudTrail logs for all logged operations. For example, you could create a role-based profile as follows. ``` [profile namedsessionrole] role_arn = arn:aws:iam::234567890123:role/SomeRole source_profile = default role_session_name = Session_Maria_Garcia ``` This results in the role session having the following ARN. ``` arn:aws:iam::234567890123:assumed-role/SomeRole/Session_Maria_Garcia ``` Also, all AWS CloudTrail logs include the role session name in the information captured for each operation. ## Assume role with web identity You can configure a profile to indicate that the AWS CLI should assume a role using [web identity federation and Open ID Connect (OIDC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html). When you specify this in a profile, the AWS CLI automatically makes the corresponding AWS STS `AssumeRoleWithWebIdentity` call for you. **Note** When you specify a profile that uses an IAM role, the AWS CLI makes the appropriate calls to retrieve temporary credentials. These credentials are stored in `~/.aws/cli/cache`. Subsequent AWS CLI commands that specify the same profile use the cached temporary credentials until they expire. At that point, the AWS CLI automatically refreshes the credentials. To retrieve and use temporary credentials using web identity federation, you can specify the following configuration values in a shared profile. [role\$1arn](#cli-configure-role) Specifies the ARN of the role to assume. web\$1identity\$1token\$1file Specifies the path to a file which contains an OAuth 2.0 access token or OpenID Connect ID token that is provided by the identity provider. The AWS CLI loads this file and passes its content as the `WebIdentityToken` argument of the `AssumeRoleWithWebIdentity` operation. [role\$1session\$1name](#cli-configure-role-session-name) Specifies an optional name applied to this assume-role session. The following is an example of the minimal amount of configuration needed to configure an assume role with web identity profile. ``` # In ~/.aws/config [profile web-identity] role_arn=arn:aws:iam:123456789012:role/RoleNameToAssume web_identity_token_file=/path/to/a/token ``` You can also provide this configuration by using [environment variables](cli-configure-envvars.md). AWS\$1ROLE\$1ARN The ARN of the role to assume. AWS\$1WEB\$1IDENTITY\$1TOKEN\$1FILE The path to the web identity token file. AWS\$1ROLE\$1SESSION\$1NAME The name applied to this assume-role session. **Note** These environment variables currently apply only to the assume role with web identity provider. They don't apply to the general assume role provider configuration. ## Clearing cached credentials When you use a role, the AWS CLI caches the temporary credentials locally until they expire. The next time you try to use them, the AWS CLI attempts to renew them on your behalf. If your role's temporary credentials are [revoked](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html), they are not renewed automatically, and attempts to use them fail. However, you can delete the cache to force the AWS CLI to retrieve new credentials. **Linux or macOS** ``` $ rm -r ~/.aws/cli/cache ``` **Windows** ``` C:\> del /s /q %UserProfile%\.aws\cli\cache ``` # Authenticating using IAM user credentials for the AWS CLI **Warning** To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). This section explains how to configure basic settings with an IAM user. These include your security credentials using the `config` and `credentials` files. **Contents** + [ ## Step 1: Create your IAM user ](#cli-authentication-user-create) + [ ## Step 2: Get your access keys ](#cli-authentication-user-get) + [ ## Step 3: Configure the AWS CLI ](#cli-authentication-user-configure.title) + [ ### Using `aws configure` ](#cli-authentication-user-configure-wizard) ## Step 1: Create your IAM user Create your IAM user by following the [Creating IAM users (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) procedure in the *IAM User Guide*. + For **Permission options**, choose **Attach policies directly** for how you want to assign permissions to this user. + Most "Getting Started" SDK tutorials use the Amazon S3 service as an example. To provide your application with full access to Amazon S3, select the `AmazonS3FullAccess` policy to attach to this user. ## Step 2: Get your access keys 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane of the IAM console, select **Users** and then select the **`User name`** of the user that you created previously. 1. On the user's page, select the **Security credentials** page. Then, under **Access keys**, select **Create access key**. 1. For **Create access key Step 1**, choose **Command Line Interface (CLI)**. 1. For **Create access key Step 2**, enter an optional tag and select **Next**. 1. For **Create access key Step 3**, select **Download .csv file** to save a `.csv` file with your IAM user's access key and secret access key. You need this information for later. 1. Select Done. ## Step 3: Configure the AWS CLI For general use, the AWS CLI needs the following pieces of information: + Access key ID + Secret access key + AWS Region + Output format The AWS CLI stores this information in a *profile* (a collection of settings) named `default` in the `credentials` file. By default, the information in this profile is used when you run an AWS CLI command that doesn't explicitly specify a profile to use. For more information on the `credentials` file, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md). To configure the AWS CLI, use one of the following procedures: **Topics** + [ ### Using `aws configure` ](#cli-authentication-user-configure-wizard) ### Using `aws configure` For general use, the `aws configure` command is the fastest way to set up your AWS CLI installation. This configure wizard prompts you for each piece of information you need to get started. Unless otherwise specified by using the `--profile` option, the AWS CLI stores this information in the `default` profile. The following example configures a `default` profile using sample values. Replace them with your own values as described in the following sections. ``` $ aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json ``` The following example configures a profile named `userprod` using sample values. Replace them with your own values as described in the following sections. ``` $ aws configure --profile userprod AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json ``` # Using Amazon EC2 instance metadata as credentials in the AWS CLI When you run the AWS CLI from within an Amazon Elastic Compute Cloud (Amazon EC2) instance, you can simplify providing credentials to your commands. Each Amazon EC2 instance contains metadata that the AWS CLI can directly query for temporary credentials. When an IAM role is attached to the instance, the AWS CLI automatically and securely retrieves the credentials from the instance metadata. To disable this service, use the [AWS\$1EC2\$1METADATA\$1DISABLED](cli-configure-envvars.md#envvars-list-AWS_EC2_METADATA_DISABLED) environment variable. **Topics** + [ ## Prerequisites ](#cli-configure-metadata-prereqs) + [ ## Configuring a profile for Amazon EC2 metadata ](#cli-configure-metadata-configure) ## Prerequisites To use Amazon EC2 credentials with the AWS CLI, you need to complete the following: + Install and configure the AWS CLI. For more information, see [Installing, updating, and uninstalling the AWS CLI](cli-chap-install.md) and [Authentication and access credentials for the AWS CLI](cli-chap-authentication.md). + You understand configuration files and named profiles. For more information, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md). + You've created an AWS Identity and Access Management (IAM) role that has access to the resources needed, and attached that role to the Amazon EC2 instance when you launch it. For more information, see [IAM policies for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-policies-for-amazon-ec2.html) in the *Amazon EC2 User Guide* and [Granting Applications That Run on Amazon EC2 Instances Access to AWS Resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/role-usecase-ec2app.html) in the *IAM User Guide*. ## Configuring a profile for Amazon EC2 metadata To specify that you want to use the credentials available in the hosting Amazon EC2 instance profile, use the following syntax in the named profile in your configuration file. See the following steps for more instructions. ``` [profile profilename] role_arn = arn:aws:iam::123456789012:role/rolename credential_source = Ec2InstanceMetadata region = region ``` 1. Create a profile in your configuration file. ``` [profile profilename] ``` 1. Add your IAM arn role that has access to the resources needed. ``` role_arn = arn:aws:iam::123456789012:role/rolename ``` 1. Specify `Ec2InstanceMetadata` as your credential source. ``` credential_source = Ec2InstanceMetadata ``` 1. Set your Region. ``` region = region ``` **Example** The following example assumes the *`marketingadminrole`* role and uses the `us-west-2` Region in an Amazon EC2 instance profile named `marketingadmin`. ``` [profile marketingadmin] role_arn = arn:aws:iam::123456789012:role/marketingadminrole credential_source = Ec2InstanceMetadata region = us-west-2 ``` # Sourcing credentials with an external process in the AWS CLI **Warning** This topic discusses sourcing credentials from an external process. This could be a security risk if the command to generate the credentials becomes accessible by non-approved processes or users. We recommend that you use the supported, secure alternatives provided by the AWS CLI and AWS to reduce the risk of compromising your credentials. Ensure that you secure the `config` file and any supporting files and tools to prevent disclosure. Ensure that your custom credential tool does not write any secret information to `StdErr` because the SDKs and AWS CLI can capture and log such information, potentially exposing it to unauthorized users. If you have a method to generate or look up credentials that isn't directly supported by the AWS CLI, you can configure the AWS CLI to use it by configuring the `credential_process` setting in the `config` file. For example, you might include an entry similar to the following in the `config` file. ``` [profile developer] credential_process = /opt/bin/awscreds-custom --username helen ``` **Syntax** To create this string in a way that is compatible with any operating system, follow these rules: + If the path or file name contains a space, surround the complete path and file name with double-quotation marks (" "). The path and file name can consist of only the characters: A-Z a-z 0-9 - \$1 . space + If a parameter name or a parameter value contains a space, surround that element with double-quotation marks (" "). Surround only the name or value, not the pair. + Do not include any environment variables in the strings. For example, you can't include `$HOME` or `%USERPROFILE%`. + Do not specify the home folder as `~`. You must specify the full path. **Example for Windows** ``` credential_process = "C:\Path\To\credentials.cmd" parameterWithoutSpaces "parameter with spaces" ``` **Example for Linux or macOS** ``` credential_process = "/Users/Dave/path/to/credentials.sh" parameterWithoutSpaces "parameter with spaces" ``` **Expected output from the Credentials program** The AWS CLI runs the command as specified in the profile and then reads data from `STDOUT`. The command you specify must generate JSON output on `STDOUT` that matches the following syntax. ``` { "Version": 1, "AccessKeyId": "an AWS access key", "SecretAccessKey": "your AWS secret access key", "SessionToken": "the AWS session token for temporary credentials", "Expiration": "ISO8601 timestamp when the credentials expire" } ``` **Note** As of this writing, the `Version` key must be set to `1`. This might increment over time as the structure evolves. The `Expiration` key is an [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatted timestamp. If the `Expiration` key is not present in the tool's output, the CLI assumes that the credentials are long-term credentials that do not refresh. Otherwise the credentials are considered temporary credentials and are refreshed automatically by rerunning the `credential_process` command before they expire. **Note** The AWS CLI does ***not*** cache external process credentials the way it does assume-role credentials. If caching is required, you must implement it in the external process. The external process can return a non-zero return code to indicate that an error occurred while retrieving the credentials.