graphql-hive / graphql-hive/console

Support Redis ACL authentication with username

Open
#8,140 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.