graphql-hive / graphql-hive/console
Support Redis ACL authentication with username
- Dominant language
- TypeScript
- Stars
- 483
- Forks
- 145
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 65
Description
## 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`
```TypeScript
// 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(),
),
});
```
```TypeScript
// 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`
```TypeScript
// Current
redis: {
host: redis.REDIS_HOST,
port: redis.REDIS_PORT,
password: redis.REDIS_PASSWORD ?? '',
tlsEnabled: redis.REDIS_TLS_ENABLED === '1',
},
```
```TypeScript
// 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`
```TypeScript
// 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,
});
```
```TypeScript
// 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`
```env
# 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.
Contributor guide
Assessment
This issue has not been assessed yet.