How to create and configure AWS credentials for Amazon Keyspaces - Amazon Keyspaces (for Apache Cassandra)
Required credentials for AWS authenticationAdding an IAM user for programmatic accessCreating new access keysHow to manage access keysUsing temporary credentials to connect to Amazon Keyspaces

How to create and configure AWS credentials for Amazon Keyspaces

To access Amazon Keyspaces programmatically with the AWS CLI, the AWS SDK, or with Cassandra client drivers and the SigV4 plugin, you need an IAM user or role with access keys. When you use AWS programmatically, you provide your AWS access keys so that AWS can verify your identity in programmatic calls. Your access keys consist of an access key ID (for example, AKIAIOSFODNN7EXAMPLE) and a secret access key (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). This topic walks you through the required steps in this process.

Security best practises recommend that you create IAM users with limited permissions and instead associate IAM roles with the permissions needed to perform specific tasks. IAM users can then temporarily assume IAM roles to perform the required tasks. For example, IAM users in your account using the Amazon Keyspaces console can switch to a role to temporarily use the permissions of the role in the console. The users give up their original permissions and take on the permissions assigned to the role. When the users exit the role, their original permissions are restored. The credentials the users use to assume the role are temporary. On the contrary, IAM users have long-term credentials, which presents a security risk if instead of assuming roles they have permissions directly assigned to them. To help mitigate this risk, we recommend that you provide these users with only the permissions they require to perform the task and that you remove these users when they are no longer needed. For more information about roles, see Common scenarios for roles: Users, applications, and services in the IAM User Guide.

Credentials required by the AWS CLI, the AWS SDK, or the Amazon Keyspaces SigV4 plugin for Cassandra client drivers

The following credentials are required to authenticate the IAM user or role:

AWS_ACCESS_KEY_ID

Specifies an AWS access key associated with an IAM user or role.

The access key aws_access_key_id is required to connect to Amazon Keyspaces programmatically.

AWS_SECRET_ACCESS_KEY

Specifies the secret key associated with the access key. This is essentially the "password" for the access key.

The aws_secret_access_key is required to connect to Amazon Keyspaces programmatically.

AWS_SESSION_TOKEN – Optional

Specifies the session token value that is required if you are using temporary security credentials that you retrieved directly from AWS Security Token Service operations. For more information, see Using temporary credentials to connect to Amazon Keyspaces using an IAM role and the SigV4 plugin.

If you are connecting with an IAM user, the aws_session_token is not required.

Creating an IAM user for programmatic access to Amazon Keyspaces in your AWS account

To obtain credentials for programmatic access to Amazon Keyspaces with the AWS CLI, the AWS SDK, or the SigV4 plugin, you need to first create an IAM user or role. The process of creating a IAM user and configuring that IAM user to have programmatic access to Amazon Keyspaces is shown in the following steps:

  1. Create the user in the AWS Management Console, the AWS CLI, Tools for Windows PowerShell, or using an AWS API operation. If you create the user in the AWS Management Console, then the credentials are created automatically.

  2. If you create the user programmatically, then you must create an access key (access key ID and a secret access key) for that user in an additional step.

  3. Give the user permissions to access Amazon Keyspaces.

For information about the permissions that you need in order to create a user, see Permissions required to access IAM resources.

Creating IAM users (console)

You can use the AWS Management Console to create IAM users.

To create an IAM user with programmatic access (console)

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Users and then choose Add users.

  3. Type the user name for the new user. This is the sign-in name for AWS.

    Note

    User names can be a combination of up to 64 letters, digits, and these characters: plus (+), equal (=), comma (,), period (.), at sign (@), underscore (_), and hyphen (-). Names must be unique within an account. They are not distinguished by case. For example, you cannot create two users named TESTUSER and testuser.

  4. Select Access key - Programmatic access to create an access key for the new user. You can view or download the access key when you get to the Final page.

    Choose Next: Permissions.

  5. On the Set permissions page, choose Attach existing policies directly to assign permissions to the new user.

    This option displays the list of AWS managed and customer managed policies available in your account. You can enter keyspaces into the search field to display only the policies that are related to Amazon Keyspaces.

    For Amazon Keyspaces, the available managed policies are AmazonKeyspacesFullAccess and AmazonKeyspacesReadOnlyAccess. For more information about each policy, see AWS managed policies for Amazon Keyspaces.

    For testing purposes and to follow the connection tutorials, select the AmazonKeyspacesReadOnlyAccess policy for the new IAM user. Note: As a best practice, we recommend that you follow the principle of least privilege and create custom policies that limit access to specific resources and only allow the required actions. For more information about IAM policies and to view example policies for Amazon Keyspaces, see Amazon Keyspaces identity-based policies. After you have created custom permission policies, attach your policies to roles and then let users assume the appropriate roles temporarily.

    Choose Next: Tags.

  6. On the Add tags (optional) page you can add tags for the user, or choose Next: Review.

  7. On the Review page you can see all of the choices you made up to this point. When you're ready to proceed, choose Create user.

  8. To view the user's access keys (access key IDs and secret access keys), choose Show next to the password and access key. To save the access keys, choose Download .csv and then save the file to a safe location.

    Important

    This is your only opportunity to view or download the secret access keys, and you need this information before they can use the SigV4 plugin. Save the user's new access key ID and secret access key in a safe and secure place. You will not have access to the secret keys again after this step.

Creating IAM users (AWS CLI)

You can use the AWS CLI to create an IAM user.

To create an IAM user with programmatic access (AWS CLI)

  1. Create a user with the following AWS CLI code.

  2. Give the user programmatic access. This requires access keys, that can be generated in the following ways.

    • AWS CLI: aws iam create-access-key

    • Tools for Windows PowerShell: New-IAMAccessKey

    • IAM API: CreateAccessKey

      Important

      This is your only opportunity to view or download the secret access keys, and you need this information before they can use the SigV4 plugin. Save the user's new access key ID and secret access key in a safe and secure place. You will not have access to the secret keys again after this step.

  3. Attach the AmazonKeyspacesReadOnlyAccess policy to the user that defines the user's permissions. Note: As a best practice, we recommend that you manage user permissions by adding the user to a group and attaching a policy to the group instead of attaching directly to a user.

Creating new access keys for an IAM user

If you already have an IAM user, you can create new access keys at any time. For more information about key management, for example how to rotate access keys, see Managing access keys for IAM users.

To create access keys for an IAM user (console)

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Users.

  3. Choose the name of the user whose access keys you want to create.

  4. On the Summary page of the user, choose the Security credentials tab.

  5. In the Access keys section, choose Create access key.

    To view the new access key pair, choose Show. Your credentials will look something like this:

    • Access key ID: AKIAIOSFODNN7EXAMPLE

    • Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

    Note

    You will not have access to the secret access key again after this dialog box closes.

  6. To download the key pair, choose Download .csv file. Store the keys in a secure location.

  7. After you download the .csv file, choose Close.

When you create an access key, the key pair is active by default, and you can use the pair right away.

How to manage access keys for IAM users

As a best practice, we recommend that you don't embed access keys directly into code. The AWS SDKs and the AWS Command Line Tools enable you to put access keys in known locations so that you do not have to keep them in code. Put access keys in one of the following locations:

  • Environment variables – On a multitenant system, choose user environment variables, not system environment variables.

  • CLI credentials file – The credentials and config file are updated when you run the command aws configure. The credentials file is located at ~/.aws/credentials on Linux, macOS, or Unix, or at C:\Users\USERNAME\.aws\credentials on Windows. This file can contain the credential details for the default profile and any named profiles.

  • CLI configuration file – The credentials and config file are updated when you run the command aws configure. The config file is located at ~/.aws/config on Linux, macOS, or Unix, or at C:\Users\USERNAME\.aws\config on Windows. This file contains the configuration settings for the default profile and any named profiles.

Storing access keys as environment variables is a pre-requisite for the Step-by-step tutorial to connect to Amazon Keyspaces using the 4.x DataStax Java driver for Apache Cassandra and the SigV4 authentication plugin. The client searches for credentials using the default credentials provider chain, and access keys stored as environment variables take precedent over all other locations, for example configuration files. For more information, see Configuration settings and precedence.

The following examples show how you can configure environment variables for the default user.

Linux, macOS, or Unix
$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ export AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of security token>

Setting the environment variable changes the value used until the end of your shell session, or until you set the variable to a different value. You can make the variables persistent across future sessions by setting them in your shell's startup script.

Windows Command Prompt
C:\> setx AWS_ACCESS_KEY_ID AKIAIOSFODNN7EXAMPLE
C:\> setx AWS_SECRET_ACCESS_KEY wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
C:\> setx AWS_SESSION_TOKEN AQoDYXdzEJr...<remainder of security token>

Using set to set an environment variable changes the value used until the end of the current command prompt session, or until you set the variable to a different value. Using setx to set an environment variable changes the value used in both the current command prompt session and all command prompt sessions that you create after running the command. It does not affect other command shells that are already running at the time you run the command.

PowerShell
PS C:\> $Env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
PS C:\> $Env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
PS C:\> $Env:AWS_SESSION_TOKEN="AQoDYXdzEJr...<remainder of security token>"

If you set an environment variable at the PowerShell prompt as shown in the previous examples, it saves the value for only the duration of the current session. To make the environment variable setting persistent across all PowerShell and Command Prompt sessions, store it by using the System application in Control Panel. Alternatively, you can set the variable for all future PowerShell sessions by adding it to your PowerShell profile. See the PowerShell documentation for more information about storing environment variables or persisting them across sessions.

Using temporary credentials to connect to Amazon Keyspaces using an IAM role and the SigV4 plugin

For enhanced security, you can use temporary credentials to authenticate with the SigV4 plugin. In many scenarios, you don't need long-term access keys that never expire (as you have with an IAM user). Instead, you can create an IAM role and generate temporary security credentials. Temporary security credentials consist of an access key ID and a secret access key, but they also include a security token that indicates when the credentials expire. To learn more about how to use IAM roles instead of long-term access keys, see Switching to an IAM role (AWS API).

To get started with temporary credentials, you first need to create an IAM role.

Create an IAM role that grants read-only access to Amazon Keyspaces

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, then Create role.

  3. On the Create role page, under Select type of trusted entity, choose AWS service. Under Choose a use case, choose Amazon EC2, then choose Next.

  4. On the Add permissions page, under Permissions policies, choose Amazon Keyspaces Read Only Access from the policy list, then choose Next.

  5. On the Name, review, and create page, enter a name for the role, and review the Select trusted entities and Add permissions sections. You can also add optional tags for the role on this page. When you are done, select Create role. Remember this name because you’ll need it when you launch your Amazon EC2 instance.

To use temporary security credentials in code, you programmatically call an AWS Security Token Service API like AssumeRole and extract the resulting credentials and session token from your IAM role that you created in the previous step. You then use those values as credentials for subsequent calls to AWS. The following example shows pseudocode for how to use temporary security credentials:

assumeRoleResult = AssumeRole(role-arn);
tempCredentials = new SessionAWSCredentials(
   assumeRoleResult.AccessKeyId, 
   assumeRoleResult.SecretAccessKey, 
   assumeRoleResult.SessionToken);
cassandraRequest = CreateAmazoncassandraClient(tempCredentials);

For an example that implements temporary credentials using the Python driver to access Amazon Keyspaces, see Connect to Amazon Keyspaces using the DataStax Python driver for Apache Cassandra and the SigV4 authentication plugin.

For details about how to call AssumeRole, GetFederationToken, and other API operations, see the AWS Security Token Service API Reference. For information on getting the temporary security credentials and session token from the result, see the documentation for the SDK that you're working with. You can find the documentation for all the AWS SDKs on the main AWS documentation page, in the SDKs and Toolkits section.