Merge pull request #21 from mutablelogic/djt/0420/apikey

Add API key database objects

Author: djthorpe

.github/workflows/docker.yaml

@@ -32,11 +32,11 @@ jobs:
           sudo apt -y install build-essential git
           git config --global advice.detachedHead false
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Login
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -58,7 +58,7 @@ jobs:
       packages: write
     steps:
       - name: Login
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

README.md

@@ -0,0 +1,142 @@
+# go-auth
+
+`go-auth` is a hosted authentication, authorization, TLS certificate, and LDAP management application.
+It combines three subsystems in one server process:
+
+- Auth management for local users, sessions, identity providers, and bearer tokens.
+- Certificate management for storing and working with TLS certificate material.
+- LDAP management for projecting users and groups into an LDAP directory.
+
+It requires a PostgreSQL database for storage and can be configured
+with environment variables and CLI flags.
+
+## Quick Start
+
+Run the container:
+
+```bash
+export PG_URL='postgres://user@host.docker.internal/database?sslmode=prefer'
+docker run --rm  --name go-auth \
+  -e PG_URL -e PG_PASSWORD \
+  -e ADDR=0.0.0.0:8084 \
+  -p 8084:8084 \
+  ghcr.io/mutablelogic/go-auth:latest
+```
+
+Notes:
+
+- `PG_URL` is required. The service will not start without a PostgreSQL connection.
+- The image entrypoint is `authmanager` and the default command is `run`, so you only need to pass environment variables unless you want to add extra CLI flags.
+
+## Auth Parameters
+
+These parameters configure the authentication manager and identity provider integration.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `AUTH_SCHEMA` | env | Database schema used for auth tables. |
+| `AUTH_SESSION_TTL` | env | Session lifetime. Defaults to 15 minutes when unset. |
+| `AUTH_REFRESH_TTL` | env | Refresh token lifetime. Defaults to 7 days when unset. |
+| `GOOGLE_CLIENT_ID` | env | Enables the Google provider when set. |
+| `GOOGLE_CLIENT_SECRET` | env | Google OAuth client secret. |
+| `--auth.enabled` / `--no-auth` | cli | Enable or disable authentication on management endpoints. Default is enabled. |
+| `--auth.signer=file:///path/to/key.pem?kid=main` | cli | Add a private key PEM file used to sign issued tokens. Repeat to add multiple signers. |
+| `--local.enabled` / `--no-local.enabled` | cli | Enable or disable the built-in local browser-flow identity provider. Default is disabled. |
+
+Examples:
+
+```bash
+docker run --rm \
+  -p 8084:80 \
+  -e AUTHMANAGER_ADDR=:80 \
+  -e PG_URL='postgres://user:password@host.docker.internal/authdb?sslmode=disable' \
+  -e AUTH_SCHEMA='auth' \
+  -e AUTH_SESSION_TTL='30m' \
+  -e AUTH_REFRESH_TTL='168h' \
+  -e GOOGLE_CLIENT_ID='your-google-client-id' \
+  -e GOOGLE_CLIENT_SECRET='your-google-client-secret' \
+  "$IMAGE"
+```
+
+## Cert Parameters
+
+These parameters configure the certificate manager.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `CERT_ENABLED` | env | Enable or disable the certificate manager. Default is `true`. |
+| `CERT_PASSPHRASE` | env | Passphrase used for encrypting private keys. Can be supplied multiple times in CLI usage; in Docker this is typically provided once per environment variable name supported by your runtime. |
+| `CERT_SCHEMA` | env | Database schema used for certificate tables. |
+
+Example:
+
+```bash
+docker run --rm \
+  -p 8084:80 \
+  -e AUTHMANAGER_ADDR=:80 \
+  -e PG_URL='postgres://user:password@host.docker.internal/authdb?sslmode=disable' \
+  -e CERT_ENABLED='true' \
+  -e CERT_SCHEMA='cert' \
+  -e CERT_PASSPHRASE='change-me' \
+  "$IMAGE"
+```
+
+## LDAP Parameters
+
+These parameters configure the LDAP manager. The LDAP manager is only started when `LDAP_URL` is set.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `LDAP_URL` | env | LDAP server URL to connect to or manage. When unset, the LDAP manager is disabled. |
+| `LDAP_BASEDN` | env | Base DN for LDAP entries. Default is `dc=example,dc=org`. |
+| `LDAP_USER` | env | Bind user DN used by the LDAP manager. Default is `cn=admin,dc=example,dc=org`. |
+| `LDAP_PASS` | env | Bind password for the LDAP manager. |
+| `LDAP_USER_DN` | env | Relative DN for the user subtree, for example `ou=users`. |
+| `LDAP_GROUP_DN` | env | Relative DN for the group subtree, for example `ou=groups`. |
+
+Example:
+
+```bash
+docker run --rm \
+  -p 8084:80 \
+  -e AUTHMANAGER_ADDR=:80 \
+  -e PG_URL='postgres://user:password@host.docker.internal/authdb?sslmode=disable' \
+  -e LDAP_URL='ldap://ldap.example.org:389' \
+  -e LDAP_BASEDN='dc=example,dc=org' \
+  -e LDAP_USER='cn=admin,dc=example,dc=org' \
+  -e LDAP_PASS='change-me' \
+  -e LDAP_USER_DN='ou=users' \
+  -e LDAP_GROUP_DN='ou=groups' \
+  "$IMAGE"
+```
+
+## Common Container Parameters
+
+These are not subsystem-specific, but they are usually required in Docker deployments:
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `PG_URL` | env | PostgreSQL connection URL. Required for startup. |
+| `PG_PASSWORD` | env | PostgreSQL password override. |
+| `AUTHMANAGER_ADDR` | env | HTTP listen address. Set this to `:80` or `:443` in containers. |
+| `ADDR` | env | Alternate generic listen-address environment variable. |
+| `--http.prefix` | cli | HTTP API path prefix. Default is `/api`. |
+| `--http.timeout` | cli | HTTP server read/write timeout. Default is `15m`. |
+| `--http.origin` | cli | Cross-origin protection origin configuration. |
+| `--tls.name` | cli | TLS server name. |
+| `--tls.cert` | cli | TLS certificate file inside the container. |
+| `--tls.key` | cli | TLS private key file inside the container. |
+| `--ui` / `--no-ui` | cli | Enable or disable the embedded UI. Default is enabled. |
+| `--openapi` / `--no-openapi` | cli | Enable or disable the OpenAPI endpoints. Default is enabled. |
+
+If you mount certificate files into the container, a TLS-enabled run looks like this:
+
+```bash
+docker run --rm \
+  -p 8443:443 \
+  -e AUTHMANAGER_ADDR=:443 \
+  -e PG_URL='postgres://user:password@host.docker.internal/authdb?sslmode=disable' \
+  -v "$PWD/certs:/certs:ro" \
+  "$IMAGE" \
+  run --tls.cert=/certs/tls.crt --tls.key=/certs/tls.key
+```

auth/httphandler/AUTHN.md

@@ -6,7 +6,7 @@ Registers the public auth, OIDC, and protected-resource endpoints exposed by the
 
 Auth is the server's local authentication layer. It starts browser sign-in, exchanges provider credentials for locally signed tokens, publishes discovery metadata, and returns the authenticated user's client-facing claims.
 
-### `GET /auth/config`
+### `GET /config`
 
 Returns a `PublicClientConfigurations` object keyed by provider name. Each value is a `PublicClientConfiguration` containing only client-safe fields such as `issuer` and `client_id`.
 

auth/httphandler/authorize.go

@@ -76,7 +76,7 @@ func authorize(ctx context.Context, manager *manager.Manager, w http.ResponseWri
 	}
 
 	// Get the identity provider for the request
-	identity_provider, err := authorizationProvider(manager, req.Provider)
+	identity_provider, err := authorizationProvider(ctx, manager, req.Provider)
 	if err != nil {
 		return authorizeError(w, r, req, err)
 	}
@@ -99,8 +99,8 @@ func authorize(ctx context.Context, manager *manager.Manager, w http.ResponseWri
 	return nil
 }
 
-func authorizationProvider(manager *manager.Manager, key string) (provider.Provider, error) {
-	config, err := manager.AuthConfig()
+func authorizationProvider(ctx context.Context, manager *manager.Manager, key string) (provider.Provider, error) {
+	config, err := manager.AuthConfig(ctx)
 	if err != nil {
 		return nil, err
 	} else if len(config) == 0 {

auth/httphandler/config.go

@@ -37,15 +37,15 @@ func ConfigHandler(manager *manager.Manager, doc *opts.MarkdownDoc) (string, *js
 		"Auth",
 	).Get(
 		func(w http.ResponseWriter, r *http.Request) {
-			config, err := manager.AuthConfig()
+			config, err := manager.AuthConfig(r.Context())
 			if err != nil {
 				_ = httpresponse.Error(w, autherr.HTTPError(err))
 				return
 			}
 			_ = httpresponse.JSON(w, http.StatusOK, httprequest.Indent(r), config)
 		},
 		"Get public auth configuration",
-		opts.WithDescription(doc.Section(3, "GET /auth/config").Body),
+		opts.WithDescription(doc.Section(3, "GET /config").Body),
 		opts.WithJSONResponse(http.StatusOK, jsonschema.MustFor[schema.PublicClientConfigurations]()),
 		opts.WithErrorResponse(http.StatusNotFound, "No upstream providers are configured."),
 	)

auth/manager/oidc.go

@@ -36,8 +36,8 @@ import (
 
 // AuthConfig returns the shareable upstream provider configuration exposed by
 // /auth/config. The client secret remains server-side.
-func (m *Manager) AuthConfig() (_ schema.PublicClientConfigurations, err error) {
-	ctx, endSpan := otel.StartSpan(m.tracer, context.Background(), "manager.AuthConfig")
+func (m *Manager) AuthConfig(ctx context.Context) (_ schema.PublicClientConfigurations, err error) {
+	ctx, endSpan := otel.StartSpan(m.tracer, ctx, "manager.AuthConfig")
 	defer func() { endSpan(err) }()
 
 	config := make(schema.PublicClientConfigurations)

auth/schema/objects.sql

@@ -41,24 +41,22 @@ CREATE TABLE IF NOT EXISTS ${"schema"}.session (
     "revoked_at"    TIMESTAMPTZ NULL
 );
 
--- auth.session.refresh_columns
-DO $$ BEGIN
-    ALTER TABLE ${"schema"}.session ADD COLUMN IF NOT EXISTS refresh_expires_at TIMESTAMPTZ;
-    ALTER TABLE ${"schema"}.session ADD COLUMN IF NOT EXISTS refresh_counter BIGINT;
-    UPDATE ${"schema"}.session
-    SET refresh_expires_at = COALESCE(refresh_expires_at, expires_at)
-    WHERE refresh_expires_at IS NULL;
-    UPDATE ${"schema"}.session
-    SET refresh_counter = COALESCE(refresh_counter, 0)
-    WHERE refresh_counter IS NULL;
-    ALTER TABLE ${"schema"}.session ALTER COLUMN refresh_expires_at SET NOT NULL;
-    ALTER TABLE ${"schema"}.session ALTER COLUMN refresh_counter SET NOT NULL;
-    ALTER TABLE ${"schema"}.session ALTER COLUMN refresh_counter SET DEFAULT 0;
-END $$;
-
 -- auth.session.user_index
 CREATE INDEX IF NOT EXISTS session_user_idx ON ${"schema"}.session ("user");
 
+-- auth.apikey
+CREATE TABLE IF NOT EXISTS ${"schema"}.apikey (
+    "hash"        BYTEA       NOT NULL PRIMARY KEY,
+    "user"        UUID        NOT NULL REFERENCES ${"schema"}."user" (id) ON DELETE CASCADE,
+    "name"        TEXT        NOT NULL DEFAULT '',
+    "created_at"  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    "modified_at" TIMESTAMPTZ NOT NULL DEFAULT now(),
+    "expires_at"  TIMESTAMPTZ NULL
+);
+
+-- auth.apikey.user_index
+CREATE INDEX IF NOT EXISTS apikey_user_idx ON ${"schema"}.apikey ("user");
+
 -- auth.group
 CREATE TABLE IF NOT EXISTS ${"schema"}.group (
     "id"          TEXT    NOT NULL PRIMARY KEY CONSTRAINT groups_name_identifier CHECK (id ~ '^([a-zA-Z][a-zA-Z0-9_-]{0,63}|\$[a-zA-Z][a-zA-Z0-9_]*\$)$'),
@@ -139,6 +137,15 @@ DO $$ BEGIN
     EXECUTE FUNCTION ${"schema"}.notify_table();
 END $$;
 
+-- auth.notify.apikey.trigger
+DO $$ BEGIN
+    DROP TRIGGER IF EXISTS apikey_table_changes_notify ON ${"schema"}.apikey;
+    CREATE TRIGGER apikey_table_changes_notify
+    AFTER INSERT OR UPDATE OR DELETE ON ${"schema"}.apikey
+    FOR EACH STATEMENT
+    EXECUTE FUNCTION ${"schema"}.notify_table();
+END $$;
+
 -- auth.notify.group.trigger
 DO $$ BEGIN
     DROP TRIGGER IF EXISTS group_table_changes_notify ON ${"schema"}."group";

cert/manager/opt.go

@@ -84,9 +84,6 @@ func WithSchema(name string) Opt {
 // WithTracer sets the OpenTelemetry tracer used for manager spans.
 func WithTracer(tracer trace.Tracer) Opt {
 	return func(o *opt) error {
-		if tracer == nil {
-			return fmt.Errorf("tracer is required")
-		}
 		o.tracer = tracer
 		return nil
 	}