Skip to content
Rack Gateway

What is Rack Gateway?

Rack Gateway is an open-source authentication and authorization proxy for self-hosted Convox racks. It adds enterprise-grade security controls to your infrastructure without changing how you use Convox.

The Problem

Section titled “The Problem”

When you self-host Convox racks without Convox Console, your rack has a primary API token that grants unrestricted access to everything. This token is typically stored in your Terraform state file.

While Convox does support creating individual user credentials with limited permissions, the primary token remains the main security concern:

  • Unrestricted primary access - Anyone with the Terraform state can do anything
  • No accountability for primary token usage - Can’t tell who used it
  • Limited audit trail - Actions from the primary token aren’t attributed to individuals
  • Compliance gaps - SOC 2 requires individual access controls with proper audit trails

The Solution

Section titled “The Solution”

Rack Gateway sits between your users and the Convox rack, providing:

Authentication

Google Workspace OAuth with domain restrictions. Users sign in with their corporate accounts.

Authorization

Role-based access control with four levels: viewer, ops, deployer, and admin.

Audit Logging

Every request recorded before it acts, with user attribution, env value redaction, and hourly S3 WORM anchors.

Multi-Factor Auth

TOTP, WebAuthn (security keys), and YubiKey support with step-up authentication.

How It Works

Section titled “How It Works”

Rack Gateway is a proxy for the Convox API:

  1. User runs a command: rack-gateway apps (or convox apps with RACK_URL pointing at the gateway)
  2. Gateway authenticates: Validates the user’s session or API token
  3. Gateway authorizes: Checks RBAC permissions for the requested action
  4. Gateway proxies: Forwards the request to the real Convox rack
  5. Gateway logs: Records the attempt before forwarding (refusing the request if it can’t), then the result

The real rack token never leaves the gateway. Users only have session tokens that the gateway validates.

Using the rack-gateway CLI

Section titled “Using the rack-gateway CLI”

Users interact with Rack Gateway through the rack-gateway CLI:

Terminal window
# Login (opens browser for OAuth)
rack-gateway login staging https://gateway.example.com


# Run Convox commands through the gateway
rack-gateway apps
rack-gateway deploy
rack-gateway logs -a myapp


# Set up a convenient alias
alias cg="rack-gateway"
cg apps
cg deploy

The CLI:

  • Handles OAuth authentication with the gateway
  • Manages session tokens securely
  • Supports multiple rack configurations
  • Runs the Convox commands itself, through the gateway (it doesn’t need the convox CLI)

Single-Tenant Design

Section titled “Single-Tenant Design”

This design provides:

  • Maximum security: No shared infrastructure between racks
  • Simple deployment: Deploy on the same rack it protects
  • Clear boundaries: Each environment is completely isolated
Production Environment
├── Convox Rack (port 5443)
└── Rack Gateway (port 8447) ──▶ proxies to Rack


Staging Environment
├── Convox Rack (port 5443)
└── Rack Gateway (port 8447) ──▶ proxies to Rack

Developers use the rack-gateway CLI to switch between gateways, or configure separate RACK_URL values for each environment.

Key Features

Section titled “Key Features”

Role-Based Access Control

Section titled “Role-Based Access Control”

Built-in roles provide granular control:

RoleCapabilities
ViewerRead-only: list apps, view logs, view builds, rack status
OpsViewer + restart apps, manage processes, view env
DeployerOps + create builds, promote releases, update env
AdminFull access including user management
CI/CDAutomation tokens only (not assignable to human users)

Audit Logging

Section titled “Audit Logging”

Every action is logged with:

  • User identification: Email address of the authenticated user, or the API token and its owner
  • Action details: Action name, resource and details
  • Outcome: Success, failure or denial, and the HTTP status
  • Timing: Timestamps and latency
  • Secret redaction: Env values are [REDACTED] unless an admin lists them as visible

Events are stored in Postgres in an append-only, hash-chained table, anchored hourly to S3 Object Lock (WORM) storage, and also written to stdout as JSON for CloudWatch or your SIEM.

Multi-Factor Authentication

Section titled “Multi-Factor Authentication”

Protect sensitive operations with MFA:

  • TOTP: Google Authenticator, Authy, 1Password
  • WebAuthn: YubiKey 5, Touch ID, Windows Hello
  • YubiKey OTP: Hardware token authentication
  • Trusted devices: Remember browsers for 30 days by default
  • Backup codes: 10 one-time recovery codes

Deploy Approvals

Section titled “Deploy Approvals”

Require manual approval for CI/CD deployments:

  • Create approval requests from CircleCI or GitHub Actions
  • Approve or reject in the web UI or with rack-gateway deploy-approval; Slack posts each request with a link
  • Track approval status in audit logs
  • Integrate with your existing CI/CD workflow

Built for Compliance

Section titled “Built for Compliance”

Rack Gateway was designed with SOC 2 compliance in mind:

  • Access Control (CC6.1): RBAC with granular permissions
  • Logical Access (CC6.2): OAuth authentication, MFA enforcement
  • Audit Logging (CC7.1): Complete audit trail with user attribution
  • Change Management (CC8.1): Deploy approvals for controlled releases

See SOC 2 Compliance for detailed mapping.

What’s Not Included

Section titled “What’s Not Included”

Rack Gateway focuses on authentication and authorization. It doesn’t provide:

  • Rack management: Use Terraform or Convox Console for rack lifecycle
  • Monitoring: Use Datadog, CloudWatch, or your preferred solution
  • Multiple OAuth providers: Currently Google Workspace only
  • Custom roles: Use the four built-in roles (plus CI/CD for tokens), or give an API token individual permissions

For more advanced features, consider Convox Console.

Next Steps

Section titled “Next Steps”