<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=69721933&issueIid=163) </details> <!--IssueSummary end--> ## Summary Instructions for setting up the BFF (backend-for-frontend) per-user auth flow locally. This replaces the old shared-credential SigNoz iframe login with a per-user, GitLab-brokered OIDC exchange. Two repos make up this feature. The `gitlab` side is split into a stack of 4 MRs (database → settings/config → backend → frontend), each targeting the previous one: | Repo | Branch | MR | |---|---|---| | `gitlab_o11y` (SigNoz fork) | `feat/gitlab-bff-session-exchange` | [!141](https://gitlab.com/gitlab-org/embody-team/experimental-observability/gitlab_o11y/-/merge_requests/141) | | `gitlab` (GitLab Rails) | `db-o11y-oauth-application-id` → `master` | [!249286](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249286) | | `gitlab` (GitLab Rails) | `o11y-bff-settings` → `db-o11y-oauth-application-id` | [!249287](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249287) | | `gitlab` (GitLab Rails) | `o11y-bff-broker` → `o11y-bff-settings` | [!249291](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249291) | | `gitlab` (GitLab Rails) | `o11y-bff-frontend` → `o11y-bff-broker` | [!249292](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249292) | For local testing of the full flow, check out `o11y-bff-frontend` (the tip of the stack) — it includes all 4 layers. ## Prerequisites - A working GitLab Development Kit (GDK) checkout with the `gitlab` repo inside it. - A local checkout of `gitlab_o11y` (can live outside the GDK). - Docker (for `docker compose up`, unless running the compiled SigNoz binary directly). ## Setup Instructions ### 1. Check out both branches ```sh # in your gitlab_o11y checkout git fetch origin feat/gitlab-bff-session-exchange git checkout feat/gitlab-bff-session-exchange # in your GDK's gitlab/ checkout git fetch origin o11y-bff-frontend git checkout o11y-bff-frontend ``` `o11y-bff-frontend` is the tip of the 4-MR stack (`db-o11y-oauth-application-id` → `o11y-bff-settings` → `o11y-bff-broker` → `o11y-bff-frontend`), so checking it out gets you the database column, settings/mTLS config, backend session broker, and frontend wiring all at once. ### 2. Run GitLab Rails migrations The stack adds a new `ApplicationSetting.o11y_oauth_application_id` column (migrations `20260723092700`–`20260723092702`, from !249286). **Run migrations immediately after checking out the branch, before starting GDK services**, so the column exists before Rails boots: ```sh cd <path-to-gdk>/gitlab bundle exec rails db:migrate ``` GitLab uses a decomposed multi-database setup. If you ever need to target a database individually (e.g. checking status or rolling back), use: ```sh bundle exec rails db:migrate:status:main # or :ci / :sec ``` **If this branch is significantly behind your local `master`**, you may hit `PG::CheckViolation` errors from migrations that validate constraints against existing local data. This is expected when a GDK's dev database has old seed data that predates a newer migration's constraint — see Troubleshooting below. ### 3. Create a GitLab OAuth application In your GDK admin area (Admin → Applications), create a new application: - **Redirect URI:** `http://localhost:3301/api/v1/complete/gitlab` (adjust the port if your local SigNoz instance runs elsewhere) - **Scopes:** `openid profile email` Note the application's numeric **database** ID — not the "Application ID" (client_id) shown on the page. **Where to find it:** - After creating the application, look at the URL of its edit/show page: `https://<your-gdk>/admin/applications/<ID>/edit`. The `<ID>` in that URL is the value to use (e.g. `.../admin/applications/6/edit` → the database ID is `6`). - Or, more robustly, fetch it directly via Rails console/runner: ```sh bundle exec rails runner "puts Authn::OauthApplication.find_by(name: '<your app name>').id" ``` Right after creating the application, before moving on, copy all three values you'll need from that one page — **database ID** (for step 4), **Application ID**, and **Secret** (both for step 5) — since the Secret won't be retrievable later without renewing it (see step 5). ### 4. Point GitLab at the shared OAuth application ```sh cd <path-to-gdk>/gitlab bundle exec rails runner "ApplicationSetting.current.update!(o11y_oauth_application_id: <YOUR_APP_ID>)" ``` `<YOUR_APP_ID>` is the OAuth application's **numeric database ID** from step 3 — not the "Application ID" (client_id) string. These are two different values and it's easy to grab the wrong one. There's no admin UI for this yet — it's set directly via the Rails console/runner. ### 5. Configure the SigNoz side In `gitlab_o11y`'s `deploy/docker/.env`, set: ``` GITLAB_OIDC_ISSUER=<your GDK's base URL, e.g. http://localhost:3000> GITLAB_OIDC_CLIENT_ID=<the OAuth application's Application ID> GITLAB_OIDC_CLIENT_SECRET=<the OAuth application's Secret> ``` `GITLAB_OIDC_CLIENT_ID` and `GITLAB_OIDC_CLIENT_SECRET` come from the **same GitLab OAuth application** you created in step 3 — not separate values. - **`GITLAB_OIDC_CLIENT_ID`** = the **"Application ID"** field shown on the application's page in Admin → Applications (this is Doorkeeper's `uid`). This is different from the numeric database `id` used for `o11y_oauth_application_id` in step 4 — same page, two different fields, easy to mix up. - **`GITLAB_OIDC_CLIENT_SECRET`** = the **"Secret"** field, shown **only once**, immediately after the application is created. GitLab hashes secrets at rest, so if you navigate away without copying it, it's gone — you'll need to click "Renew" on the application's page to generate a new one (this keeps the same application record/`id`, so `o11y_oauth_application_id` does not need to change if you do this). These are consumed by the `create-user` compose service to seed the `gitlab_auth` auth-domain row on boot. For a plain-HTTP local GDK (no TLS), also set **both** of the following (both are required — see `pkg/types/authtypes/gitlab.go`): ``` SIGNOZ_ALLOW_INSECURE_GITLAB_ISSUER=1 SIGNOZ_ENV=development ``` This is a local-dev-only escape hatch that permits an `http://` issuer for smoke-testing against a plaintext GDK instance. Never set these in a real deployment — see #145 for the plan to gate this more strictly. ### 6. Enable the feature flag ```sh cd <path-to-gdk>/gitlab bundle exec rails runner "Feature.enable(:observability_per_user_bff_auth, Group.find_by(path: '<your-test-group>'))" ``` ### 7. Start everything ```sh # SigNoz cd gitlab_o11y/deploy/docker docker compose up # GDK (separate terminal) cd <path-to-gdk> gdk start ``` ### 8. Verify Visit your test group's `/-/observability` page in the GDK. You should be signed into the embedded SigNoz iframe automatically as your GitLab user, with no separate SigNoz login prompt. ## Troubleshooting - **`git commit`/`git push` fails with `Could not find rails-7.2.3.1... in locally installed gems`** — this means the wrong Ruby is active for git hooks. If using `mise`/`asdf`, run `mise exec -- <command>` or `eval "$(mise env)"` first. - **Migrations fail with `PG::CheckViolation` on tables you didn't touch** — pre-existing local dev-data debt from a stale GDK, unrelated to this feature. Ask in the team channel if you hit this. - **iframe shows a SigNoz login prompt instead of auto-signing-in** — double check the feature flag is enabled for your test group and that `ApplicationSetting.o11y_oauth_application_id` is set correctly. ## References - [!141](https://gitlab.com/gitlab-org/embody-team/experimental-observability/gitlab_o11y/-/merge_requests/141) — `gitlab_o11y` MR - [!249286](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249286) — `gitlab` MR 1/4: database column - [!249287](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249287) — `gitlab` MR 2/4: settings/mTLS config - [!249291](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249291) — `gitlab` MR 3/4: backend session broker - [!249292](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249292) — `gitlab` MR 4/4: frontend wiring - #101 — Replace shared-credential iframe auth with per-user OIDC flow - #145 — harden the BFF endpoint (tracks scoping `SIGNOZ_ALLOW_INSECURE_GITLAB_ISSUER` more strictly)