Support Redis ACL authentication with username

[vjammi]

Summary

Enable Redis Access Control List (ACL) authentication support across Hive services by allowing a Redis username to be configured in addition to the existing password.

For self-hosted deployments using Redis ACLs, this is currently one of the internal customizations we maintain. Upstream support would allow self-hosted users relying on Redis ACLs to deploy official Hive release images without maintaining custom patches or internal forks.

Background

Starting with Redis 6.0, Access Control Lists (ACLs) provide fine-grained authorization and authentication beyond the traditional password-only model.

ACL-enabled Redis deployments typically require both a username and password during authentication.

Currently, Hive supports configuring a Redis password but does not expose a way to provide a Redis username.

Impacted Services

The following services appear to require updates to support REDIS_USERNAME:

Services that need optional REDIS_USERNAME added to environment variable and username passed to the Redis client configuration.

• packages/services/api/src/modules/shared/providers/redis.ts
• packages/services/server/src/environment.ts
• packages/services/schema/src/environment.ts
• packages/services/tokens/src/environment.ts
• packages/services/usage/src/environment.ts

Services with direct new Redis(...) client constructor that also need username wired

• packages/services/schema/src/index.ts
• packages/services/tokens/src/index.ts
• packages/services/usage/src/index.ts

Service templates that should include REDIS_USERNAME

• packages/services/server/.env.template
• packages/services/schema/.env.template
• packages/services/tokens/.env.template
• packages/services/usage/.env.template

Motivation

Many enterprise Redis deployments standardize on ACL-based authentication and disable use of the default user. Supporting REDIS_USERNAME would improve compatibility with these environments while requiring only minimal changes to the existing Redis configuration model.

Proposed Changes

Hive currently uses the ioredis client library, which already supports Redis ACL authentication through the standard username and password connection options.

Because ACL support already exists in ioredis, this enhancement primarily involves:

• Adding REDIS_USERNAME to the environment models.
• Propagating username into the Redis client configuration and constructor
• Preserving existing password-only behavior for backward compatibility.

1. Add REDIS_USERNAME Environment Variable within environment.ts

// Current
const RedisModel = zod.object({
  REDIS_HOST: zod.string(),
  REDIS_PORT: NumberFromString,
  REDIS_PASSWORD: emptyString(zod.string().optional()),
  REDIS_TLS_ENABLED: emptyString(
    zod.union([zod.literal('1'), zod.literal('0')]).optional(),
  ),
});

// Proposed 
const RedisModel = zod.object({
  REDIS_HOST: zod.string(),
  REDIS_PORT: NumberFromString,
  REDIS_USERNAME: emptyString(zod.string().optional()),                                              // Optional
  REDIS_PASSWORD: emptyString(zod.string().optional()),
  REDIS_TLS_ENABLED: emptyString(zod.union([zod.literal('1'), zod.literal('0')]).optional()),
});

2. Pass username to Redis Client Configuration within environment.ts

// Current
redis: {
  host: redis.REDIS_HOST,
  port: redis.REDIS_PORT,
  password: redis.REDIS_PASSWORD ?? '',
  tlsEnabled: redis.REDIS_TLS_ENABLED === '1',
},

// Proposed
redis: {
    host: redis.REDIS_HOST,
    port: redis.REDIS_PORT,
    username: redis.REDIS_USERNAME ?? '',                                                                          // Defaults to empty
    password: redis.REDIS_PASSWORD ?? '',
    tlsEnabled: redis.REDIS_TLS_ENABLED === '1',
  },

3. Pass username in the Redis Client Constructor within index.ts

// Current 
  const redis = new Redis({
    host: env.redis.host,
    port: env.redis.port,
    password: env.redis.password,
    maxRetriesPerRequest: 20,
    db: 0,
    enableReadyCheck: false,
    tls: env.redis.tlsEnabled ? {} : undefined,
  });

// Proposed
  const redis = new Redis({
    host: env.redis.host,
    port: env.redis.port,
    username: env.redis.username,
    password: env.redis.password,
    maxRetriesPerRequest: 20,
    db: 0,
    enableReadyCheck: false,
    tls: env.redis.tlsEnabled ? {} : undefined,
  });

4. Add REDIS_USERNAME to .env.template

# Empty string value to preserve existing password-only deployments.
REDIS_USERNAME=""

Backward Compatibility

This change is fully backward compatible:

• Existing deployments that use password-only authentication continue to work unchanged.
• REDIS_USERNAME is optional.
• ACL-enabled Redis deployments can provide both username and password.

[OSUMed]

Hi! I'd be interested in working on this issue if it's still available. I'm a first-time contributor to GraphQL Hive and would be happy to put together a PR.

I was able to reproduce the issue locally and trace the missing REDIS_USERNAME configuration path through the Redis setup. I'm working on the implementation now and will open a PR once I've validated the affected paths.