Authenticate using long-term credentials - Amazon SDKs and Tools
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).

Authenticate using long-term credentials

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 Amazon IAM Identity Center.

If you use an IAM user to run your code, then the SDK or tool in your development environment authenticates by using long-term IAM user credentials in the shared Amazon credentials file. Review the Security best practices in IAM topic and transition to IAM Identity Center or other temporary credentials as soon as possible.

Important warnings and guidance for credentials

Warnings for credentials
  • Do NOT use your account's root credentials to access Amazon resources. These credentials provide unrestricted account access and are difficult to revoke.

  • Do NOT put literal access keys or credential information in your application files. If you do, you create a risk of accidentally exposing your credentials if, for example, you upload the project to a public repository.

  • Do NOT include files that contain credentials in your project area.

  • Be aware that any credentials stored in the shared Amazon credentials file are stored in plaintext.

Additional guidance for securely managing credentials

For a general discussion of how to securely manage Amazon credentials, see Best practices for managing Amazon access keys in the Amazon Web Services General Reference. In addition to that discussion, consider the following:

  • Use IAM roles for tasks for Amazon Elastic Container Service (Amazon ECS) tasks.

  • Use IAM roles for applications that are running on Amazon EC2 instances.

Prerequisites: Create an Amazon account

To use an IAM user to access Amazon services, you need an Amazon account and Amazon credentials.

  1. Create an account.

    To create an Amazon account, see Getting started: Are you a first-time Amazon user? in the Amazon Account Management Reference Guide.

  2. Create an administrative user.

    Avoid using your root user account (the initial account you create) to access the management console and services. Instead, create an administrative user account, as explained in Create an administrative user in the IAM User Guide.

    After you create the administrative user account and record the login details, be sure to sign out of your root user account and sign back in using the administrative account.

Neither of these accounts are appropriate for doing development on Amazon or for running applications on Amazon. As a best practice, you need to create users, permission sets, or service roles that are appropriate for these tasks. For more information, see Apply least-privilege permissions in the IAM User Guide.

Step 1: Create your IAM user

  • Create your IAM user by following the Creating IAM users (console) procedure in the IAM User Guide. When creating your IAM user:

    • We recommend you select Provide user access to the Amazon Web Services Management Console. This allows you to view Amazon Web Services related to the code that you are running in a visual environment, such as checking Amazon CloudTrail diagnostic logs or uploading files to Amazon Simple Storage Service, which is helpful when debugging your code.

    • For Set permissions - Permission options, select 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.

    • You can ignore the optional steps of that procedure regarding setting permission boundaries or tags.

Step 2: Get your access keys

  1. In the navigation pane of the IAM console, select Users and then select the User name of the user that you created previously.

  2. On the user's page, select the Security credentials page. Then, under Access keys, select Create access key.

  3. For Create access key Step 1, choose either Command Line Interface (CLI) or Local code. Both options generate the same type of key to use with both the Amazon CLI and the SDKs.

  4. For Create access key Step 2, enter an optional tag and select Next.

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

    Warning

    Use appropriate security measures to keep these credentials safe.

  6. Select Done.

Step 3: Update the shared credentials file

  1. Create or open the shared Amazon credentials file. This file is ~/.aws/credentials on Linux and macOS systems, and %USERPROFILE%\.aws\credentials on Windows. For more information, see Location of Credentials Files.

  2. Add the following text to the shared credentials file. Replace the example ID value and example key value with the values in the .csv file that you downloaded earlier.

    [default] aws_access_key_id = AKIAIOSFODNN7EXAMPLE aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  3. Save the file.

The shared credentials file is the most common way to store credentials. These can also be set as environment variables, see Amazon access keys for environment variable names. This is a way to get you started, but we recommend you transition to IAM Identity Center or other temporary credentials as soon as possible. After you transition away from using long-term credentials, remember to delete these credentials from the shared credentials file.