Console
    Start free

    Secure access to your instances by using basic token-based authentication

    In addition to Identity and Access Management (IAM) authentication , you can use basic token-based authentication to secure access to your Memorystore for Valkey instances. As a lightweight solution, basic token-based authentication lets clients verify their identities within your applications by using their tokens.

    Basic token-based authentication has minimal resource requirements and a low resource overhead. In addition, if your current workloads on either Memorystore for Redis or your on-premises applications already use basic token-based authentication, then this feature facilitates a smooth transition when you migrate to Memorystore for Valkey.

    Benefits

    By using basic token-based authentication, you gain the following benefits:

    • Flexibility: for new and existing instances, enable authentication at any time. When you enable basic token-based authentication, your instances are secure. For all new connections, users must supply an authentication token to authenticate into your instances.
    • Zero-downtime rotation: rotate user tokens without causing downtime to your applications.
    • Compatibility: the default superuser maintains the same privileges that are granted to this user. Basic token-based authentication adds an extra layer of protection. This ensures backward compatibility when you migrate your workloads from Memorystore for Redis into Memorystore for Valkey.

    Authentication modes

    Basic token-based authentication supports two primary authentication modes:

    • Simple authentication: a straightforward method where a user sends an authentication token to authenticate themselves as the default user
    • Multi-user authentication: manage multiple users to authenticate access to your instances

    Best practices

    For security purposes, we recommend that you use the following best practices for basic token-based authentication:

    • Rotate user tokens: use a rotation policy for user tokens.

    • Use Secret Manager: don't hardcode a user's basic token-based authentication credentials in your application code. Instead, store them in Secret Manager and retrieve them at runtime.

      Secret Manager provides a centralized, encrypted vault for user credentials, which eliminates secret sprawl and reduces the operational overhead of managing credentials manually. It enforces access controls by using IAM and generates audit logs automatically. This ensures compliance and prevents credential exposure.

    • Combine basic token-based authentication with Transport Layer Security (TLS): when you use basic token-based authentication, we recommend that you enable in-transit encryption . This ensures that usernames and authentication tokens aren't sent in plain text over the network.

    Before you begin

    Before you begin to secure your instances by using basic token-based authentication, complete the prerequisites in this section.

    Verify client support for basic token-based authentication

    To confirm that your client applications can support basic token-based authentication, ensure that the applications can use the AUTH command.

    The default user authenticates to your client applications by using the following command:

    AUTH TOKEN

    For this command, TOKEN is the default user's authentication token.

    All other users authenticate by using the following command:

    AUTH USERNAME 
 TOKEN

    For this command, USERNAME and TOKEN are the user's username and authentication token.

    For more information about the AUTH command, see AUTH in the Valkey documentation.

    Use the Google Cloud console, Google Cloud CLI, and APIs

    To use the Google Cloud console, gcloud CLI, and APIs, do the following:

    1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project .

      Go to the project selector

    2. Make sure that billing is enabled for your project. Learn how to check if billing is enabled on a project .

    3. Install and initialize the Google Cloud CLI (gcloud CLI).

      Note:If you installed the gcloud CLI, then make sure you have the latest version by running gcloud components update . To access the Memorystore for Valkey gcloud CLI commands, you need at least gcloud CLI version 489.0.0 .

    4. Enable the Memorystore for Valkey API.
      Memorystore for Valkey API
    5. Enable the Network Connectivity API.
      Network Connectivity API
    6. Enable the Service Consumer Management API.
      Service Consumer Management API

    Assign roles

    To configure basic token-based authentication for your instances, you must have one of these IAM roles in your Google Cloud project:

    • roles/memorystore.admin (the Memorystore Admin role)
    • roles/owner (the Owner role)
    • roles/editor (the Editor role)

    Manage basic token-based authentication for instances

    Memorystore for Valkey supports the following actions to manage basic token-based authentication for instances:

    Create an instance with basic token-based authentication

    By creating an instance with basic token-based authentication, you have a lightweight and widely supported method to restrict a user's access to the instance.

    You can create the instance by using the gcloud CLI .

    To create an instance that has basic token-based authentication enabled, use the gcloud beta memorystore instances create command.

    gcloud beta memorystore instances create INSTANCE_ID 
\
--location= REGION 
\
--authorization-mode=token-auth

    Make the following replacements:

    • INSTANCE_ID : the ID of the instance that you want to create to use basic token-based authentication
    • REGION : the region where you want the instance to be located

    Enable basic token-based authentication for an instance

    By enabling basic token-based authentication for an instance, you have a lightweight and widely supported method to restrict a user's access to the instance.

    The default user can authenticate to the instance by using just their token. All other users authenticate by using a standard username and token. For more information, see Verify client support for basic token-based authentication .

    Enabling basic token-based authentication might cause downtime for applications that try to create new connections because Memorystore for Valkey requires authenticated requests. Although existing connections remain unaffected, to utilize basic token-based authentication for any subsequent connection attempts to the instance, you must update your applications. For more information, see Connect to an instance by using basic token-based authentication .

    You can enable basic token-based authentication for an instance by using the gcloud CLI .

    To enable basic token-based authentication, use the gcloud beta memorystore instances update command.

    gcloud beta memorystore instances update INSTANCE_ID 
\
--location= REGION 
\
--authorization-mode=token-auth

    Make the following replacements:

    • INSTANCE_ID : the ID of the instance for which you want to enable basic token-based authentication
    • REGION : the region where the instance is located

    Create a basic token-based authentication user for an instance

    By creating a basic token-based authentication user for an instance, you configure the instance to allow multi-user authentication. After the user logs in initially, this authentication mode acts as a secure and revocable credential for new connections. The user can continue to use the authentication token until either they delete it or the user is removed.

    You can create a basic token-based authentication user by using the gcloud CLI .

    To create the user, use the gcloud beta memorystore instances create-token-auth-user command.

    gcloud beta memorystore instances create-token-auth-user INSTANCE_ID 
\
--location= REGION 
\
--token-auth-user= USERNAME

    Make the following replacements:

    • INSTANCE_ID : the ID of the instance for which you want to create a basic token-based authentication user
    • REGION : the region where the instance is located
    • USERNAME : the username of the user

    List basic token-based authentication users for an instance

    You can retrieve a list of basic token-based authentication users for an instance by using the gcloud CLI .

    To list the users, use the gcloud beta memorystore instances token-auth-users list command.

    gcloud beta memorystore instances token-auth-users list \
--instance= INSTANCE_ID 
\
--location= REGION

    Make the following replacements:

    • INSTANCE_ID : the ID of the instance for which you want to retrieve a list of basic token-based authentication users
    • REGION : the region where the instance is located

    View information about a basic token-based authentication user

    You can view information about a basic token-based authentication user by using the gcloud CLI .

    To view information about the user, use the gcloud beta memorystore instances token-auth-users describe command.

    gcloud beta memorystore instances token-auth-users describe USERNAME 
\
--instance= INSTANCE_ID 
\
--location= REGION

    Make the following replacements:

    • USERNAME : the username of the basic token-based authentication user about which you want to view information
    • INSTANCE_ID : the ID of the instance to which the user can authenticate
    • REGION : the region where the instance is located

    Delete a basic token based authentication user from an instance

    By deleting a basic token-based authentication user from an instance, you revoke the user's access rights to the instance.

    You can delete a basic token-based authentication user from an instance by using the gcloud CLI .

    To delete the user, use the gcloud beta memorystore instances token-auth-users delete command.

    gcloud beta memorystore instances token-auth-users delete USERNAME 
\
--instance= INSTANCE_ID 
\
--location= REGION

    Make the following replacements:

    • USERNAME : the username of the basic token-based authentication user
    • INSTANCE_ID : the ID of the instance from which you want to delete the user
    • REGION : the region where the instance is located

    For the user that you're deleting, Memorystore for Valkey doesn't end existing connections. To end these connections, run the following command on all nodes in the instance:

    CLIENT KILL USER USERNAME

    Manage basic token-based authentication for users

    Memorystore for Valkey supports the following actions to manage basic token-based authentication for users:

    Create an authentication token for a user

    By creating an authentication token for a user, you can rotate the user's existing token without causing downtime to your applications.

    You can create an authentication token for a user by using the gcloud CLI .

    To create the user, use the gcloud beta memorystore instances token-auth-users create-auth-token command.

    gcloud beta memorystore instances token-auth-users create-auth-token USERNAME 
\
--instance= INSTANCE_ID 
\
--location= REGION

    Make the following replacements:

    • USERNAME : the username of the user for which you want to create an authentication token
    • INSTANCE_ID : the ID of the instance that the user can access by using the token
    • REGION : the region where the instance is located

    List authentication tokens for a user

    You can retrieve a list of authentication tokens for a user by using the gcloud CLI .

    To list the tokens, use the gcloud beta memorystore instances token-auth-users auth-tokens list command.

    gcloud beta memorystore instances token-auth-users auth-tokens list \
--token-auth-user= USERNAME 
\
--instance= INSTANCE_ID 
\
--location= REGION

    Make the following replacements:

    • USERNAME : the username of the user to which the authentication tokens belong
    • INSTANCE_ID : the ID of the instance that the user can access by using the authentication tokens
    • REGION : the region where the instance is located

    View information about an authentication token for a user

    You can view information about an authentication token for a user by using the gcloud CLI .

    To view the information, use the gcloud beta memorystore instances token-auth-users auth-tokens describe command.

    gcloud beta memorystore instances token-auth-users auth-tokens describe AUTH_TOKEN 
\
--instance= INSTANCE_ID 
\
--location= REGION 
\
--token-auth-user= USERNAME

    Make the following replacements:

    • AUTH_TOKEN : the name of the authentication token about which you want to view information
    • INSTANCE_ID : the ID of the instance that the user can access by using the token
    • REGION : the region where the instance is located
    • USERNAME : the username of the user to which the authentication token belongs

    Delete an authentication token from a user

    Deleting an authentication token from a user is a critical security action that invalidates the token.

    You can delete an authentication token from a user by using the gcloud CLI .

    To delete the token, use the gcloud beta memorystore instances token-auth-users auth-tokens delete command.

    gcloud beta memorystore instances token-auth-users auth-tokens delete AUTH_TOKEN 
\
--instance= INSTANCE_ID 
\
--location= REGION 
\
--token-auth-user= USERNAME

    Make the following replacements:

    • AUTH_TOKEN : the name of the authentication token that you want to delete from the user
    • INSTANCE_ID : the ID of the instance that you want to prevent the user from accessing by deleting the token
    • REGION : the region where the instance is located
    • USERNAME : the username of the user that has a token that you want to delete

    Connect to an instance by using basic token-based authentication

    You can use the following methods to connect to an instance by using basic token-based authentication:

    • Uniform Resource Identifier (URI) string: this single, formatted string is used for convenience because all necessary connection information (for example, the user's username and authentication token, and the instance's IP address and hostname) is contained in one string.
    • Flags: this method is better suited for individual command-line tool usage, scripting, or environments where the configuration is broken down into separate environment variables by using multiple, separate arguments.

    In the following sections, each connection method is explained.

    Use a URI string

    To connect from a Compute Engine VM or a supported environment by using a URI string, use the following command:

    valkey-cli -u
redis:// USERNAME 
: TOKEN 
@ IP_ADDRESS 
: PORT

    Make the following replacements:

    • USERNAME : the username of the user that's attempting to connect to the instance
    • TOKEN : the user's authentication token
    • IP_ADDRESS : the IP address of the instance
    • PORT : the port number that's reserved for the instance

    Use flags

    To connect from a Compute Engine VM or a supported environment by using flags, use the following command:

    valkey-cli --user USERNAME 
-a TOKEN 
-h IP_ADDRESS 
-p PORT

    Make the following replacements:

    • USERNAME : the username of the user that's attempting to connect to the instance
    • TOKEN : the user's authentication token
    • IP_ADDRESS : the IP address of the instance
    • PORT : the port number that's reserved for the instance

    Rotate a user's authentication token with zero downtime

    To rotate a user's authentication token without causing downtime to your applications, do the following:

    1. Create an additional authentication token for the user : Memorystore for Valkey generates a second, valid token. Both tokens are valid.
    2. Update your applications: update your applications to use the new token.
    3. Delete the authentication token for the user : Memorystore for Valkey removes the first token. The user can use only the second token to authenticate into your applications.

    Access logs for basic token-based authentication

    Memorystore for Valkey generates Admin Activity and Data Access audit logs for operations that are associated with authentication tokens and users. For more information about these audit logs, see Monitor access using audit logs .
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: