---
owner: gmikcon
status: active
last_reviewed: 2026-11-19
review_interval: 90d
confidence: high
source_of_truth: local-auth-setup
---

# Local gnexus-auth testing

How the local Gnexus Book instance is connected to the local gnexus-auth, which runs
the same code as production.

## Components

- gnexus-auth: `http://gnexus-auth.local` (nginx, MariaDB `gnexus_auth`).
- Gnexus Book backend: `http://127.0.0.1:3005`.
- Gnexus Book UI (Vite): `http://127.0.0.1:3006`.
- Gnexus Book MCP: `http://127.0.0.1:8001/mcp-protocol/`.

## Configuration

Runtime configuration lives in `server/.env` (`chmod 600`, gitignored). The systemd
units load it through `EnvironmentFile`; the local scripts source it before starting
the service. Do not commit it.

Required variables:

```text
GNEXUS_BOOK_STORAGE_BACKEND=db
GNEXUS_BOOK_DATABASE_URL=...
GNEXUS_BOOK_AUTH_CLIENT_ID=...
GNEXUS_BOOK_AUTH_CLIENT_SECRET=...
GNEXUS_BOOK_AUTH_BASE_URL=http://gnexus-auth.local
GNEXUS_BOOK_AUTH_REDIRECT_URI=http://127.0.0.1:3006/auth/callback
GNEXUS_BOOK_AUTH_WEBHOOK_SECRET=...
GNEXUS_BOOK_AUTH_COOKIE_SECURE=false
GNEXUS_BOOK_INTERNAL_KEY_SECRET=...
```

Store the same secrets in gnexus-creds for any shared or production deployment.

## Local OAuth client

- Slug: `gnexus-book-local` (owner-provided local client); access mode:
  `all_active_users`.
- Default role: `user`; the test user is explicitly assigned the `editor` client role.
- The client currently defines roles `editor`, `user`, `docs.write` and
  `inventory.write`, but no client permissions. Gnexus Book mirrors the roles snapshot
  and does not depend on client permissions for authorization yet.
- Redirect URIs: `http://127.0.0.1:3006/auth/callback` and
  `http://localhost:3006/auth/callback`.
- Local redirect URIs are enabled for this client.
- Webhook URL: `http://127.0.0.1:3005/webhooks/gnexus-auth`; insecure HTTP and private
  network access are explicitly enabled for local testing.

The earlier `gnexus-book` test client is disabled and its secrets are revoked. The
active local client is the owner-provided `gnexus-book-local`. Production must use an
owner-registered client, HTTPS redirect/webhook URLs, a narrower access mode and
properly defined permissions.

## Test user

A dedicated local user exists for end-to-end tests:

- Login: `gnexus-book-test@local.test`.
- Credentials: `~/.config/gnexus-book/local-auth-test-user.txt` (`chmod 600`, outside
  the repository).
- Role: `editor` on the `gnexus-book-local` client; client permissions are currently
  empty, so `/me` reports `roles: ["editor"]` and `permissions: []`.

No real user account is used for automated checks.

## Running locally

```bash
# Backend with database storage and SSO (loads server/.env)
./scripts/dev-server.sh

# MCP streamable HTTP (loads server/.env)
./scripts/dev-mcp.sh

# UI
cd ui && npm run dev
```

Open `http://127.0.0.1:3006/` and use **Sign in**. The browser goes through
gnexus-auth and returns to `/auth/callback`; Vite proxies `/auth` and `/webhooks` to
the backend.

## Verification

- `GET /health` reports `storage: db` and `checks.db.status: ok`.
- Before sign-in, `GET /me` returns `auth_enabled: true` and `user: null`.
- After sign-in, `GET /me` returns the test user with `roles: ["editor"]` and the
  client's current permissions (empty until permissions are defined).
- Protected routes return `401` without a session.
- `/mcp-keys` is available with a session.
- A gnexus-auth `webhook.test` delivery reaches
  `POST /webhooks/gnexus-auth` with `200 OK` and appears in `webhook_events`.
- `POST /auth/logout` clears the session and `/me` returns `user: null`.

## Production differences

- Register the client in production gnexus-auth and use HTTPS redirect and webhook
  URLs.
- Use `specific_users` or groups instead of `all_active_users`.
- Store client and webhook secrets in gnexus-creds; keep only runtime values in
  `.env`.
- Configure the webhook endpoint without insecure HTTP/private-network overrides.
