Skip to main content

Secure Database Access with SSO, TLS, and Auditing

Give engineers SSO-backed access to relational, NoSQL, search, and in-memory databases with AlmaForge. Users sign in once through SSO, and each alma db connect call gets a short-lived X.509 certificate from the cluster CA. An agent inside the database's network dials out to the Proxy and brokers connections through a reverse tunnel, so the database server stays off the public internet. This brings databases into the same control plane as servers, applications, and Kubernetes:

  • Database activity tied to a real person. Connection events and supported protocol query or command events carry the user's SSO identity and selected database account. Auditors can follow activity back to a person even when database accounts are shared. See Audit events for protocol coverage.
  • SSO-backed client access. Users authenticate to AlmaForge with short-lived certificates. The agent authenticates to the upstream database using the method configured for that protocol. PostgreSQL and MySQL support the certificate-based setup described in their guides. Other protocols can require separate upstream credentials, so verify the database-specific authentication setup.
  • Native CLI, GUI clients, and CI all work. alma db connect launches psql, mysql, mariadb, mongosh, valkey-cli, or redis-cli with the right credentials. For DBeaver, pgAdmin, DataGrip, MongoDB Compass, or another compatible client, run alma proxy db to expose the database on 127.0.0.1:<port>. The local proxy handles the authenticated TLS connection to the cluster. CI jobs use a workload-identity certificate instead of a password.
  • Just-in-time elevation for production. Engineers request time-bounded access to env=prod databases through the CLI or web UI. Slack notifies reviewers, and PagerDuty can supply on-call context. Approval grants a role for a fixed window. The cert expires when the window ends. See Access Requests.
  • Self-hosted, no telemetry, runs in air-gapped networks. The access plane runs inside your boundary. The agent dials out to the Proxy through a reverse tunnel, so the database needs no public IP or inbound firewall ports on its network.

Architecture​

Database access uses three AlmaForge components plus the database itself.

almad is the server daemon. One binary exposes every server-side role. The roles used for database access are:

  • almad --auth-service runs the Auth Service. It issues short-lived certificates, stores cluster state, and is the source of truth for identities, roles, and registered databases. It stores the cluster's persistent state.
  • almad --proxy-service runs the Proxy Service, the public TLS endpoint at almaforge.example.com:443. It terminates user sessions (SSO redirects for browsers, mTLS for alma callers) and brokers database connections through reverse tunnels to agents. It holds no long-term state.
  • almad --database-service runs the Database Service on a host that can reach the database. It dials out to the Proxy, holds a reverse tunnel open, authenticates each inbound connection against the cluster CA, performs the role check, opens the upstream database connection, and emits the audit events supported by that protocol.

Roles compose freely. A small cluster can run --auth-service and --proxy-service in one almad process. Production deployments split roles across multiple instances. See How it works for deployment shapes and the full role catalog.

alma is the CLI for users and workloads. It authenticates interactively through SSO (alma login) or non-interactively through workload identity. Once authenticated, alma db connect launches the native database client with a short-lived certificate, and alma proxy db opens a localhost listener for native clients and IDEs.

Database access topology

A user runs alma login before connecting. From there, alma db connect <name> retrieves a short-lived client certificate from the Auth Service and hands it to the native client. The client connects to the Proxy on port 443 over TLS and presents the cert. The Proxy validates it, matches the database's labels against the user's roles, then dials the agent's reverse tunnel. The agent checks the requested --db-user and --db-name against the role's applicable databaseUsers and databaseNames rules, opens the upstream connection, forwards the session, and writes audit events. The session ends when the client disconnects.

Each registered database is a DatabaseTarget resource. The resource's spec.protocol selects which database protocol the agent speaks. The rest of the spec is the connection target and optional features (TLS overrides, dynamic labels, admin user for Automatic user provisioning). For a complete worked deployment, use the PostgreSQL guide.

Supported databases​

Start with the PostgreSQL guide for a complete certificate-based deployment. The catalog below identifies database families. Detailed setup coverage varies by protocol.

Self-hosted​

Managed and cloud-native​

  • AWS RDS and Aurora (PostgreSQL, MySQL, MariaDB)
  • AWS RDS Proxy (PostgreSQL, MySQL, MariaDB)
  • AWS Redshift and Redshift Serverless
  • AWS DynamoDB
  • AWS Keyspaces (Cassandra)
  • AWS ElastiCache and MemoryDB (Redis)
  • Azure Database for PostgreSQL and MySQL
  • Azure Cache for Redis
  • GCP Cloud SQL (PostgreSQL, MySQL)
  • MongoDB Atlas
  • Snowflake

The Database Service supports all the protocols listed above. The PostgreSQL guide provides a complete example of agent deployment, target registration, RBAC, and verification. Use that deployment structure for other engines with their own upstream authentication and permission settings. Certificate requirements and databaseNames enforcement depend on the protocol. Contact us for setup guidance for engines whose guides are not yet published.

References​

  • Cluster on Linux: the package install, the environment file, and the systemd unit that run almad on a host.
  • Cluster on Kubernetes: the same process in-cluster, applied from a kustomize overlay.
  • Declarative configuration: full schema for the DatabaseTarget resource.
  • Environment configuration: every ALMA_* environment variable the Database Service reads at startup, including ALMA_DATABASE_SERVICE, ALMA_MATCH_LABELS, and ALMA_LABELS.
  • RBAC reference: full schema for the Role resource, including databaseLabels, databaseServiceLabels, databaseUsers, databaseNames, and databaseRoles.
  • CLI reference: all alma db connect, alma get db, alma db logout, and alma proxy db flags.
  • Access Requests: on-demand role escalation for time-bounded production access.