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

Authenticating with the Redis OSS AUTH command

Redis OSS authentication tokens or passwords enable Redis OSS to require a password before allowing clients to run commands, thereby improving data security. Redis OSS AUTH is available for self-designed clusters only.

Overview of AUTH in ElastiCache (Redis OSS)

When you use the Redis OSS AUTH with your ElastiCache (Redis OSS) cluster, there are some refinements.

In particular, be aware of these AUTH token or password constraints when using the AUTH with ElastiCache (Redis OSS):

To set up a strong token, we recommend that you follow a strict password policy, such as requiring the following:

Applying authentication to an ElastiCache (Redis OSS) cluster

You can require that users enter a token (password) on a token-protected Redis OSS server. To do this, include the parameter --auth-token (API: AuthToken) with the correct token when you create your replication group or cluster. Also include it in all subsequent commands to the replication group or cluster.

The following Amazon CLI operation creates a replication group with encryption in transit (TLS) enabled and the AUTH token This-is-a-sample-token. Replace the subnet group sng-test with a subnet group that exists.

For Linux, OS X, or Unix:

aws elasticache create-replication-group \
    --replication-group-id authtestgroup \
    --replication-group-description authtest \
    --engine redis \ 
    --cache-node-type cache.m4.large \
    --num-node-groups 1 \
    --replicas-per-node-group 2 \    
    --transit-encryption-enabled \
    --auth-token This-is-a-sample-token \
    --cache-subnet-group sng-test

For Windows:

aws elasticache create-replication-group ^
    --replication-group-id authtestgroup ^
    --replication-group-description authtest ^
    --engine redis ^ 
    --cache-node-type cache.m4.large ^
    --num-node-groups 1 ^
    --replicas-per-node-group 2 ^    
    --transit-encryption-enabled ^
    --auth-token This-is-a-sample-token ^
    --cache-subnet-group sng-test

Modifying the AUTH token on an existing ElastiCache (Redis OSS) cluster

To make it easier to update your authentication, you can modify the AUTH token used on an ElastiCache (Redis OSS) cluster. You can make this modification if the engine version is 5.0.6 or higher and if ElastiCache (Redis OSS) has encryption in transit enabled.

Modifying the auth token supports two strategies: ROTATE and SET. The ROTATE strategy adds an additional AUTH token to the server while retaining the previous token. The SET strategy updates the server to support just a single AUTH token. Make these modification calls with the --apply-immediately parameter to apply changes immediately.

Rotating the AUTH token

To update a Redis OSS server with a new AUTH token, call the ModifyReplicationGroup API with the --auth-token parameter as the new AUTH token and the --auth-token-update-strategy with the value ROTATE. After the ROTATE modification is complete, the cluster will support the previous AUTH token in addition to the one specified in the auth-token parameter. If no AUTH token was configured on the replication group before the AUTH token rotation, the cluster supports the AUTH token specified in the --auth-token parameter in addition to supporting connecting without authentication. See Setting the AUTH token to update the AUTH token to be required using update strategy SET.

If this modification is performed on a server that already supports two AUTH tokens, the oldest AUTH token will also be removed during this operation. This allows a server to support up to two most recent AUTH tokens at a given time.

At this point, you can proceed by updating the client to use the latest AUTH token. After the clients are updated, you can use the SET strategy for AUTH token rotation (explained in the following section) to exclusively start using the new token.

The following Amazon CLI operation modifies a replication group to rotate the AUTH token This-is-the-rotated-token.

For Linux, macOS, or Unix:

aws elasticache modify-replication-group \
--replication-group-id authtestgroup \
--auth-token This-is-the-rotated-token \
--auth-token-update-strategy ROTATE \
--apply-immediately

For Windows:

aws elasticache modify-replication-group ^
--replication-group-id authtestgroup ^
--auth-token This-is-the-rotated-token ^
--auth-token-update-strategy ROTATE ^
--apply-immediately

Setting the AUTH token

To update a Redis OSS server to support a single required AUTH token, call the ModifyReplicationGroup API operation with the --auth-token parameter with same value as the last AUTH token and the --auth-token-update-strategy parameter with the value SET. The SET strategy can only be used with a cluster that has 2 AUTH tokens or 1 optional AUTH token from using a ROTATE strategy before. After the modification is complete, the Redis OSS server supports only the AUTH token specified in the auth-token parameter.

The following Amazon CLI operation modifies a replication group to set the AUTH token to This-is-the-set-token.

For Linux, macOS, or Unix:

aws elasticache modify-replication-group \
--replication-group-id authtestgroup \
--auth-token This-is-the-set-token \
--auth-token-update-strategy SET \
--apply-immediately

For Windows:

aws elasticache modify-replication-group ^
--replication-group-id authtestgroup ^
--auth-token This-is-the-set-token ^
--auth-token-update-strategy SET ^
--apply-immediately

Enabling authentication on an existing ElastiCache (Redis OSS) cluster

To enable authentication on an existing Redis OSS server, call the ModifyReplicationGroup API operation. Call ModifyReplicationGroup with the --auth-token parameter as the new token and the --auth-token-update-strategy with the value ROTATE.

After the ROTATE modification is complete, the cluster supports the AUTH token specified in the --auth-token parameter in addition to supporting connecting without authentication. Once all client applications are updated to authenticate to Redis OSS with the AUTH token, use the SET strategy to mark the AUTH token as required. Enabling authentication is only supported on Redis OSS servers with encryption in transit (TLS) enabled.

Migrating from RBAC to Redis OSS AUTH

If you are authenticating users with Redis OSS Role-Based Access Control (RBAC) as described in Role-Based Access Control (RBAC), and you want to migrate to Redis OSS AUTH, use the following procedures. You can migrate using either console or CLI.

To migrate from RBAC to Redis OSS AUTH using the Amazon CLI

Use one of the following commands to configure a new optional AUTH token for your Redis OSS replication group. Note that an optional Auth token will allow unauthenticated access to the replication group until the Auth token is marked as required, using the update strategy SET in the following step.

For Linux, OS X, or Unix:

aws elasticache modify-replication-group \
    --replication-group-id test \
    --remove-user-groups \
    --auth-token This-is-a-sample-token \
    --auth-token-update-strategy ROTATE \ 
    --apply-immediately 

For Windows:

aws elasticache modify-replication-group ^
    --replication-group-id test ^
    --remove-user-groups ^
    --auth-token This-is-a-sample-token ^
    --auth-token-update-strategy ROTATE ^ 
    --apply-immediately 

After executing the above command, you can update your Redis OSS applications to authenticate to the ElastiCache replication group using the newly configured optional AUTH token. To complete the Auth token rotation, use the the update strategy SET in the subsequent command below. This will mark to the optional AUTH token as required. When the Auth token update completes, the replication group status will show as ACTIVE and all Redis OSS connections to this replication group will require authentication.

For Linux, OS X, or Unix:

aws elasticache modify-replication-group \
			--replication-group-id test \
			--auth-token This-is-a-sample-token \
			--auth-token-update-strategy SET \ 
			--apply-immediately 

For Windows:

aws elasticache modify-replication-group ^
			--replication-group-id test ^
			--remove-user-groups ^
			--auth-token This-is-a-sample-token ^
			--auth-token-update-strategy SET ^ 
			--apply-immediately

For more information, see Authenticating with the Redis OSS AUTH command.