## Overview `/authorized_certs` returns an `instance` boolean identifying the scope of a certificate match (gitlab-org/gitlab#611274). gitlab-sshd needs to read it and grant instance-wide access when it is true. Part of gitlab-org&22743. ## Current behaviour `handleUserCertificate` in `internal/sshd/server_config.go` has two branches. **File-based CAs** already grant instance-wide access, by omitting `certPermNamespace` from the permission extensions: ```go if s.isLocallyTrustedCA(cert.SignatureKey) { if err := validateKeyID(cert.KeyId); err != nil { ... } // No namespace key = instance-wide access (no namespace restriction) return buildCertPermissions(cert, map[string]string{ certPermUsername: cert.KeyId, }), nil } ``` **API-resolved CAs** always set a namespace: ```go return buildCertPermissions(cert, map[string]string{ certPermUsername: res.Username, certPermNamespace: res.Namespace, }), nil ``` Instance-level DB-backed CAs resolve through this second path, so it needs to produce the no-namespace form when the response says the match was instance-scoped. ## Proposal ### 1. Read the `instance` field Add it to the response struct in `internal/gitlabnet/authorizedcerts/client.go`: ```go type Response struct { Username string `json:"username"` Namespace string `json:"namespace"` Instance bool `json:"instance"` } ``` ### 2. Branch on scope, validate, and reject inconsistent responses ```go if !res.Instance && res.Namespace == "" { log.FromContext(ctx).WarnContext(ctx, "certificate rejected: group-scoped response has no namespace") return nil, fmt.Errorf("handleUserCertificate: group-scoped response missing namespace") } if res.Instance { if err := validateKeyID(cert.KeyId); err != nil { log.FromContext(ctx).WarnContext(ctx, "instance-level certificate rejected: invalid KeyId", log.ErrorMessage(err.Error())) return nil, fmt.Errorf("handleUserCertificate: %w", err) } } extensions := map[string]string{certPermUsername: res.Username} if !res.Instance { extensions[certPermNamespace] = res.Namespace } return buildCertPermissions(cert, extensions), nil ``` Two guards, for two different failure modes. **The namespace consistency check.** Without it, a Rails-side bug yielding an empty `full_path` on a group match would silently grant instance-wide access, since a blank namespace extension is indistinguishable from an absent one. Rejecting the mismatch makes that fail closed. **The `KeyId` check on instance results.** The file-based branch already calls `validateKeyID` before trusting `cert.KeyId` as a username. Instance-level DB CAs give the same instance-wide trust and resolve `KeyId` to a username the same way, so they need the same check. It has to run **after** the response identifies the match as instance-scoped, not before the API call. Group-level resolution accepts an email address as the identifier — `User.find_by_login` matches username or email, and minting certificates with `-I <email>` is a documented group-level workflow. `validateKeyID`'s pattern rejects `@`, so hoisting the check above the branch would break existing group-level users. Validating after the fact still closes the gap: Rails has looked up a user, but gitlab-sshd has not yet granted any permissions, so a malformed `KeyId` never reaches an authenticated session. ### 3. Confirm the env var gate is set on Dedicated The API branch is gated before the request is made: ```go // Fall back to group-level certificate check via Rails API if os.Getenv("FF_GITLAB_SHELL_SSH_CERTIFICATES") != "1" { return nil, fmt.Errorf("handleUserCertificate: feature is disabled") } ``` Instance-level CAs resolve through this path and inherit the gate. Confirm the Dedicated deployment sets it to `1`; if it does not, the feature cannot activate there regardless of the Rails work. Worth answering early, since it affects whether the epic's approach works at all. Update the comment and error message, which refer only to group-level and become misleading once instance CAs flow through here. ### 4. Pin file-based precedence `isLocallyTrustedCA` is checked first and returns early, so file-based CAs never reach the API. Add a regression test — this is a hard requirement of the epic and is currently only implied by statement ordering. ### 5. Logging The file-based branch logs `"...locally trusted CA (instance-level)"`; the API branch logs `"...trusted key (group-level)"`. Distinguish the API branch on `res.Instance` so instance-level resolutions are not reported as group-level. The context is already enriched with `signing_ca_fingerprint`, `certificate_identity`, `certificate_username`, and source address — most of what the auth-time audit event issue needs. ## Note for the security review `validateKeyID` is applied to file-based and instance-level certificates, both of which grant instance-wide trust and resolve `KeyId` directly to a username. It is deliberately not applied to group-level responses, because group-level accepts an email address as the identifier and the validation pattern rejects `@`. Confirm this split is correct and that group-level's membership lookup is sufficient validation on its own. ## Acceptance criteria - [ ] `Response` includes `Instance`. - [ ] `instance: true` grants instance-wide access, with no namespace extension set. - [ ] `instance: false` sets the namespace extension as today. - [ ] A response with `instance: false` and a blank namespace is rejected. - [ ] `validateKeyID` is applied to `instance: true` responses. - [ ] A group-level certificate using an email address as `KeyId` still authenticates. - [ ] Regression test: a locally trusted CA never triggers an API call. - [ ] Group-level certificates keep their namespace restriction; existing tests pass unchanged. - [ ] `FF_GITLAB_SHELL_SSH_CERTIFICATES` behaviour on Dedicated confirmed and documented. - [ ] Gate comment and error message no longer refer only to group-level. - [ ] Log message distinguishes instance-level from group-level API resolution. ## Out of scope - Cert validation (expiry, host certs, `KeyId` format) — handled by `CheckCert` and `validateKeyID`, unchanged here. - Auth-time audit events. ## Links - Epic: gitlab-org&22743 - Depends on: gitlab-org/gitlab#611274 - File-based implementation: gitlab-org/gitlab-shell#841, !1396 - `internal/sshd/server_config.go`, `internal/gitlabnet/authorizedcerts/client.go`