The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
docs for sso
dduxa1f16b17d85c
diff --git a/docs/pages/learn/_meta.json b/docs/pages/learn/_meta.jsonindex 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.mdxnew file mode 100644index 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.mdxindex 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 Pointsdiff --git a/docs/pages/server/docker-compose.mdx b/docs/pages/server/docker-compose.mdxindex 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 Pointsdiff --git a/docs/pages/server/haloy.mdx b/docs/pages/server/haloy.mdxindex 9eb28aad..b80b12d2 100644--- a/docs/pages/server/haloy.mdx+++ b/docs/pages/server/haloy.mdx@@ -84,6 +84,20 @@ targets:- name: JWT_SECRETfrom: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 macexport CLICKHOUSE_PASSWORD=your-clickhouse-passwordexport POSTGRES_PASSWORD=your-postgres-passwordexport 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 Commandsdiff --git a/docs/pages/server/local-setup.mdx b/docs/pages/server/local-setup.mdxindex 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:```bashdiff --git a/docs/pages/server/minimal.mdx b/docs/pages/server/minimal.mdxindex 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 Pointsdiff --git a/docs/pages/server/sqlite.mdx b/docs/pages/server/sqlite.mdxindex 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`. |+## PersistenceThe image declares `VOLUME ["/data"]`. Mount a host folder or a named volume there to keep everything across restarts: