Skip to content

The only tool you need to know what is happening and how to fix it.

docs for sso

dduxa1f16b17d85c
diff --git a/docs/pages/learn/_meta.json b/docs/pages/learn/_meta.json
index 692da3d5..7b40e7cd 100644
--- a/docs/pages/learn/_meta.json
+++ b/docs/pages/learn/_meta.json
@@ -9,6 +9,7 @@
"metrics": "Metrics",
"logs": "Logs",
"alerts": "Alerts",
+ "sso": "SSO",
"embedded-mode": "Embedded Mode",
"otel-agent": "OTel Agent",
"build-tags": "Build Tags",
diff --git a/docs/pages/learn/sso.mdx b/docs/pages/learn/sso.mdx
new file mode 100644
index 00000000..de2afea3
--- /dev/null
+++ b/docs/pages/learn/sso.mdx
@@ -0,0 +1,123 @@
+# Single Sign-On (SSO)
+
+Traceway supports signing in with **Google** and **GitHub** in addition to email + password. SSO is optional — if you don't configure a provider, only its `Continue with …` button is hidden, the rest of the dashboard works exactly the same.
+
+When at least one provider is configured, the buttons appear on the login and register pages, the backend exposes `GET /api/auth/providers`, and `GET /api/auth/start/{provider}` kicks off the OAuth flow.
+
+## How it works
+
+```
+Browser ──► /api/auth/start/github
+ └─► redirect to GitHub
+ └─► user approves
+ └─► GitHub redirects to /api/auth/callback/github
+ └─► backend issues a JWT, redirects to
+ /auth/callback#token=<jwt>&needsSetup=<bool>
+ └─► frontend stores the token,
+ navigates to / (or /finish-setup
+ for brand-new users)
+```
+
+Sign-in matching, in order:
+
+1. **Existing OAuth user** — looked up by `(provider, provider_user_id)`. Logs in.
+2. **Existing email user** — same email already registered with a password. The OAuth identity is linked to that account; future logins via either method work.
+3. **New user** — created on the fly. On a brand-new self-hosted instance the user lands at `/finish-setup` to create the organization and first project.
+
+In **self-hosted mode** (`CLOUD_MODE` unset or not `true`), once any organization exists, OAuth signups for unknown emails are blocked with `invite_required` — they have to be invited to the org first, just like password signups. In cloud mode (`CLOUD_MODE=true`), OAuth signups always create an account and prompt the user through `/finish-setup`.
+
+## Environment variables
+
+Set these on the backend container/process. Both pairs are independent — you can configure one provider, both, or neither.
+
+| Variable | Required when | Description |
+| ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `APP_BASE_URL` | Either provider configured | Public URL of your Traceway instance, e.g. `https://traceway.example.com`. Used to build the OAuth callback URL the providers redirect back to. |
+| `GOOGLE_CLIENT_ID` | Enabling Google | OAuth client ID from Google Cloud Console |
+| `GOOGLE_CLIENT_SECRET` | Enabling Google | OAuth client secret from Google Cloud Console |
+| `GITHUB_CLIENT_ID` | Enabling GitHub | OAuth App client ID from GitHub |
+| `GITHUB_CLIENT_SECRET` | Enabling GitHub | OAuth App client secret from GitHub |
+| `OAUTH_SESSION_SECRET` | Optional | Cookie-store signing secret used during the OAuth round-trip. Falls back to `JWT_SECRET` when unset. Set explicitly to rotate cookie-signing independently from JWTs. |
+
+The cookie used during the round-trip is automatically marked `Secure` when `APP_BASE_URL` starts with `https://`, and `SameSite=Lax` either way.
+
+## Setting up GitHub
+
+GitHub calls these OAuth Apps (not GitHub Apps — that's a different page).
+
+1. Sign in to GitHub. Open **Settings → Developer settings → OAuth Apps → New OAuth App**, or for an organization-owned app, your org's **Settings → Developer settings → OAuth Apps → New OAuth App**.
+2. Fill the form:
+ - **Application name** — whatever shows on the consent screen, e.g. `Traceway`.
+ - **Homepage URL** — your `APP_BASE_URL`, e.g. `https://traceway.example.com`.
+ - **Authorization callback URL** — `https://traceway.example.com/api/auth/callback/github`. Must match exactly, no trailing slash.
+3. Click **Register application**.
+4. On the app page, click **Generate a new client secret**. Copy the **Client ID** and the secret immediately — GitHub only shows the secret once.
+5. Set the env vars on the backend:
+
+ ```
+ APP_BASE_URL=https://traceway.example.com
+ GITHUB_CLIENT_ID=Ov23li...
+ GITHUB_CLIENT_SECRET=...
+ ```
+
+6. Restart the backend so `InitOAuth()` picks up the new variables.
+
+For local development, register a second OAuth App with `http://localhost:5173/api/auth/callback/github` (the Vite dev server proxies `/api` to the backend on `:8082`).
+
+The SDK requests the `user:email` scope, so the user's primary email needs to be verified on GitHub — if it isn't, the callback redirects back to `/login?error=oauth_no_email`.
+
+## Setting up Google
+
+1. In the [Google Cloud Console](https://console.cloud.google.com/), pick or create a project.
+2. Open **APIs & Services → OAuth consent screen**:
+ - **User type** — choose **External** unless you're a Workspace organization that wants the app limited to your domain (then **Internal**).
+ - Fill in app name, support email, and developer contact email.
+ - Add your domain under **Authorized domains** (e.g. `example.com`).
+3. **Create Credentials → OAuth client ID**:
+ - **Application type** — **Web application**.
+ - **Authorized JavaScript origins** — `${yourappurl}` (and `http://localhost:5173` for dev).
+ - **Authorized redirect URIs** — `${yourappurl}/api/auth/callback/google` (and `http://localhost:5173/api/auth/callback/google` for dev). Must match exactly.
+4. Copy the **Client ID** and **Client secret** from the dialog.
+5. Set the env vars on the backend:
+
+ ```
+ APP_BASE_URL=https://traceway.example.com
+ GOOGLE_CLIENT_ID=...apps.googleusercontent.com
+ GOOGLE_CLIENT_SECRET=...
+ ```
+
+6. Restart the backend.
+
+## Verifying
+
+After restart:
+
+```bash
+curl https://traceway.example.com/api/auth/providers
+# {"providers":["google","github"]}
+```
+
+If the array is empty, the backend didn't see your env vars. Common causes:
+
+- The container was started before the secrets were set — recreate, don't just restart.
+- The variables were set in a different shell than the one that launched `go run` / `docker run`.
+- For embedded backend usage (`cmd.Run(opts...)`), the option-mode config path doesn't read OS env vars — set them at the call site or use the no-options form.
+
+Once `/api/auth/providers` reports the providers, the buttons appear automatically on the login and register pages.
+
+## Error codes
+
+The OAuth callback redirects back to `/login?error=<code>` when something goes wrong. The frontend translates these into user-facing messages:
+
+| Code | Meaning |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `oauth_failed` | Provider rejected the request, the state token expired, or the callback exchange failed. |
+| `oauth_no_email` | Provider returned no email (e.g. GitHub account with no verified primary email). |
+| `invite_required` | Self-hosted mode, an organization already exists, and the email isn't on any membership. Ask an admin to send an invitation. |
+
+## Security notes
+
+- The callback hands the JWT back via the URL fragment (`#token=…`), so it never reaches the backend logs or a TLS-terminating proxy as a query string.
+- The transient cookie used by gothic during the round-trip is `HttpOnly`, `SameSite=Lax`, and 10-minute lifetime. It only carries the OAuth state and PKCE verifier — never a long-lived session.
+- `OAUTH_SESSION_SECRET` rotates the cookie signing key. Rotating it invalidates any in-flight OAuth round-trips but does not affect issued JWTs (those are signed with `JWT_SECRET`).
+- An OAuth-only user has an empty password hash. Password login for them always fails — `CheckPassword` short-circuits on empty hashes.
diff --git a/docs/pages/server/all-in-one.mdx b/docs/pages/server/all-in-one.mdx
index 3462ba84..c111c1d2 100644
--- a/docs/pages/server/all-in-one.mdx
+++ b/docs/pages/server/all-in-one.mdx
@@ -39,7 +39,21 @@ All environment variables have working defaults, no configuration required. Over
| `POSTGRES_SSLMODE` | `disable` | PostgreSQL SSL mode |
| `JWT_SECRET` | *(built-in default)* | JWT signing secret (min 32 chars) |
| `GIN_MODE` | `release` | Gin framework mode |
-| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions and email links. |
+| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, and OAuth callback URLs. |
+
+## SSO (optional)
+
+Adds **Continue with Google** / **Continue with GitHub** buttons to the login and register pages. See the [SSO guide](/learn/sso) for the full provider setup walkthrough.
+
+When configuring providers, set the callback URL on the provider side to `<APP_BASE_URL>/api/auth/callback/{google|github}`.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOOGLE_CLIENT_ID` | *(unset)* | Google OAuth client ID. Setting both Google variables enables the Google button. |
+| `GOOGLE_CLIENT_SECRET` | *(unset)* | Google OAuth client secret. |
+| `GITHUB_CLIENT_ID` | *(unset)* | GitHub OAuth App client ID. Setting both GitHub variables enables the GitHub button. |
+| `GITHUB_CLIENT_SECRET` | *(unset)* | GitHub OAuth App client secret. |
+| `OAUTH_SESSION_SECRET` | *(falls back to `JWT_SECRET`)* | Cookie signing secret for the OAuth round-trip. Override to rotate independently of `JWT_SECRET`. |
## Access Points
diff --git a/docs/pages/server/docker-compose.mdx b/docs/pages/server/docker-compose.mdx
index 8f2a705e..0fc72e9d 100644
--- a/docs/pages/server/docker-compose.mdx
+++ b/docs/pages/server/docker-compose.mdx
@@ -32,7 +32,21 @@ The `docker-compose.yml` in the repository root is ready to use out of the box.
| `POSTGRES_PASSWORD` | `traceway` | PostgreSQL password |
| `POSTGRES_SSLMODE` | `disable` | PostgreSQL SSL mode |
| `JWT_SECRET` | `change-this-to-a-secure-secret-at-least-32-chars` | JWT signing secret (min 32 chars) |
-| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions and email links. |
+| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, and OAuth callback URLs. |
+
+## SSO (optional)
+
+Adds **Continue with Google** / **Continue with GitHub** buttons to the login and register pages. See the [SSO guide](/learn/sso) for the full provider setup walkthrough.
+
+When configuring providers, set the callback URL on the provider side to `<APP_BASE_URL>/api/auth/callback/{google|github}`.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOOGLE_CLIENT_ID` | *(unset)* | Google OAuth client ID. Setting both Google variables enables the Google button. |
+| `GOOGLE_CLIENT_SECRET` | *(unset)* | Google OAuth client secret. |
+| `GITHUB_CLIENT_ID` | *(unset)* | GitHub OAuth App client ID. Setting both GitHub variables enables the GitHub button. |
+| `GITHUB_CLIENT_SECRET` | *(unset)* | GitHub OAuth App client secret. |
+| `OAUTH_SESSION_SECRET` | *(falls back to `JWT_SECRET`)* | Cookie signing secret for the OAuth round-trip. Override to rotate independently of `JWT_SECRET`. |
## Access Points
diff --git a/docs/pages/server/haloy.mdx b/docs/pages/server/haloy.mdx
index 9eb28aad..b80b12d2 100644
--- a/docs/pages/server/haloy.mdx
+++ b/docs/pages/server/haloy.mdx
@@ -84,6 +84,20 @@ targets:
- name: JWT_SECRET
from:
env: JWT_SECRET
+ # Optional: SSO providers. Omit a pair to disable that button.
+ # See /learn/sso for the full setup walkthrough.
+ - name: GOOGLE_CLIENT_ID
+ from:
+ env: GOOGLE_CLIENT_ID
+ - name: GOOGLE_CLIENT_SECRET
+ from:
+ env: GOOGLE_CLIENT_SECRET
+ - name: GITHUB_CLIENT_ID
+ from:
+ env: GITHUB_CLIENT_ID
+ - name: GITHUB_CLIENT_SECRET
+ from:
+ env: GITHUB_CLIENT_SECRET
```
Sensitive values use `from: env:` to read from environment variables on your machine at deploy time rather than being stored in the YAML file. Set them before deploying:
@@ -92,6 +106,12 @@ Sensitive values use `from: env:` to read from environment variables on your mac
export CLICKHOUSE_PASSWORD=your-clickhouse-password
export POSTGRES_PASSWORD=your-postgres-password
export JWT_SECRET=your-jwt-secret-at-least-32-chars
+
+# Optional, only when enabling SSO
+export GOOGLE_CLIENT_ID=...
+export GOOGLE_CLIENT_SECRET=...
+export GITHUB_CLIENT_ID=...
+export GITHUB_CLIENT_SECRET=...
```
## Deployment
@@ -156,6 +176,13 @@ Point your SDK's connection string at your Traceway domain:
| `POSTGRES_PASSWORD` | *(from env)* | PostgreSQL password |
| `POSTGRES_SSLMODE` | `disable` | PostgreSQL SSL mode |
| `JWT_SECRET` | *(from env)* | JWT signing secret (min 32 chars) |
+| `GOOGLE_CLIENT_ID` | *(unset)* | Optional. Google OAuth client ID. Setting both Google variables enables the **Continue with Google** button. See the [SSO guide](/learn/sso). |
+| `GOOGLE_CLIENT_SECRET` | *(unset)* | Optional. Google OAuth client secret. |
+| `GITHUB_CLIENT_ID` | *(unset)* | Optional. GitHub OAuth App client ID. Setting both GitHub variables enables the **Continue with GitHub** button. |
+| `GITHUB_CLIENT_SECRET` | *(unset)* | Optional. GitHub OAuth App client secret. |
+| `OAUTH_SESSION_SECRET` | *(falls back to `JWT_SECRET`)* | Optional. Cookie signing secret for the OAuth round-trip. |
+
+When configuring providers, set the callback URL on the provider side to `https://traceway.yourdomain.com/api/auth/callback/{google|github}`.
## Useful Commands
diff --git a/docs/pages/server/local-setup.mdx b/docs/pages/server/local-setup.mdx
index e2fd655c..981f9deb 100644
--- a/docs/pages/server/local-setup.mdx
+++ b/docs/pages/server/local-setup.mdx
@@ -73,7 +73,14 @@ POSTGRES_SSLMODE=disable
| `POSTGRES_USERNAME` | PostgreSQL username |
| `POSTGRES_PASSWORD` | PostgreSQL password |
| `POSTGRES_SSLMODE` | PostgreSQL SSL mode (`disable`, `require`, etc.) |
-| `APP_BASE_URL` | Public URL of your Traceway instance. Used for SDK connection instructions and email links. Not needed for local development. |
+| `APP_BASE_URL` | Public URL of your Traceway instance. Used for SDK connection instructions, email links, and OAuth callback URLs. For local dev set this to `http://localhost:5173` so OAuth callbacks land on the Vite dev server (which proxies `/api` back to the Go backend). |
+| `GOOGLE_CLIENT_ID` | Optional. Google OAuth client ID. Setting both Google variables enables the **Continue with Google** button. See the [SSO guide](/learn/sso). |
+| `GOOGLE_CLIENT_SECRET` | Optional. Google OAuth client secret. |
+| `GITHUB_CLIENT_ID` | Optional. GitHub OAuth App client ID. Setting both GitHub variables enables the **Continue with GitHub** button. See the [SSO guide](/learn/sso). |
+| `GITHUB_CLIENT_SECRET` | Optional. GitHub OAuth App client secret. |
+| `OAUTH_SESSION_SECRET` | Optional. Cookie signing secret for the OAuth round-trip. Falls back to `JWT_SECRET` when unset. |
+
+For local OAuth testing, register the provider's callback URL as `http://localhost:5173/api/auth/callback/github` (or `.../google`).
3. Run the backend:
```bash
diff --git a/docs/pages/server/minimal.mdx b/docs/pages/server/minimal.mdx
index 768a4bf4..758d33cc 100644
--- a/docs/pages/server/minimal.mdx
+++ b/docs/pages/server/minimal.mdx
@@ -46,7 +46,21 @@ After starting, open `http://localhost/register` to create your first account.
| `POSTGRES_PASSWORD` | PostgreSQL password | `password` |
| `POSTGRES_SSLMODE` | PostgreSQL SSL mode | `disable` |
| `JWT_SECRET` | JWT signing secret (min 32 chars) | `your-secret-here` |
-| `APP_BASE_URL` | Public URL of your instance. Used for SDK setup instructions and email links. | `https://traceway.example.com` |
+| `APP_BASE_URL` | Public URL of your instance. Used for SDK setup instructions, email links, and OAuth callback URLs. | `https://traceway.example.com` |
+
+## SSO (optional)
+
+Adds **Continue with Google** / **Continue with GitHub** buttons to the login and register pages. See the [SSO guide](/learn/sso) for the full provider setup walkthrough.
+
+When configuring providers, set the callback URL on the provider side to `<APP_BASE_URL>/api/auth/callback/{google|github}`.
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GOOGLE_CLIENT_ID` | Google OAuth client ID. Setting both Google variables enables the Google button. | `...apps.googleusercontent.com` |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret. | `GOCSPX-...` |
+| `GITHUB_CLIENT_ID` | GitHub OAuth App client ID. Setting both GitHub variables enables the GitHub button. | `Ov23li...` |
+| `GITHUB_CLIENT_SECRET` | GitHub OAuth App client secret. | `(40-char hex)` |
+| `OAUTH_SESSION_SECRET` | Cookie signing secret for the OAuth round-trip. Falls back to `JWT_SECRET` when unset. | `(32+ random bytes)` |
## Access Points
diff --git a/docs/pages/server/sqlite.mdx b/docs/pages/server/sqlite.mdx
index 5eb2b5d9..e57c3d2d 100644
--- a/docs/pages/server/sqlite.mdx
+++ b/docs/pages/server/sqlite.mdx
@@ -51,7 +51,7 @@ If `STORAGE_TYPE` is unset (or set to `local`), blobs are written to `/data/stor
| Variable | Default | Description |
|----------|---------|-------------|
| `JWT_SECRET` | *(required)* | JWT signing secret, minimum 32 characters |
-| `APP_BASE_URL` | *(unset)* | Public URL of your instance. Used for SDK setup snippets and password-reset emails |
+| `APP_BASE_URL` | *(unset)* | Public URL of your instance. Used for SDK setup snippets, password-reset emails, and OAuth callback URLs |
| `SQLITE_PATH` | `/data/traceway.db` | Main SQLite file. Telemetry DB is derived as `<path>_telemetry.db` |
| `STORAGE_TYPE` | `local` | Blob storage backend. `local` or `s3` |
| `STORAGE_PATH` | `/data/storage` | Folder for local blob storage. Ignored when `STORAGE_TYPE=s3` |
@@ -63,6 +63,20 @@ If `STORAGE_TYPE` is unset (or set to `local`), blobs are written to `/data/stor
| `PORTS` | `80,8082` | Comma-separated list of HTTP ports the server should listen on |
| `GIN_MODE` | `release` | Gin runtime mode |
+## SSO (optional)
+
+Adds **Continue with Google** / **Continue with GitHub** buttons to the login and register pages. See the [SSO guide](/learn/sso) for the full provider setup walkthrough.
+
+When configuring providers, set the callback URL on the provider side to `<APP_BASE_URL>/api/auth/callback/{google|github}`.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOOGLE_CLIENT_ID` | *(unset)* | Google OAuth client ID. Setting both Google variables enables the Google button. |
+| `GOOGLE_CLIENT_SECRET` | *(unset)* | Google OAuth client secret. |
+| `GITHUB_CLIENT_ID` | *(unset)* | GitHub OAuth App client ID. Setting both GitHub variables enables the GitHub button. |
+| `GITHUB_CLIENT_SECRET` | *(unset)* | GitHub OAuth App client secret. |
+| `OAUTH_SESSION_SECRET` | *(falls back to `JWT_SECRET`)* | Cookie signing secret for the OAuth round-trip. Override to rotate independently of `JWT_SECRET`. |
+
## Persistence
The image declares `VOLUME ["/data"]`. Mount a host folder or a named volume there to keep everything across restarts: