## Overview Second step of &22743. Now that `instance_ssh_certificates` exists (#611272), teach the internal `/authorized_certs` endpoint to resolve instance-level CAs so gitlab-sshd can authenticate a certificate signed by a CA that isn't tied to any namespace. Mirrors the group-level equivalent, #421538. ## Current behaviour `ee/lib/ee/api/internal/base.rb` delegates entirely to `Groups::SshCertificates::FindService` and always answers with a namespace: ```ruby get '/authorized_certs', feature_category: :source_code_management, urgency: :high do response = ::Groups::SshCertificates::FindService.new(params[:key], params[:user_identifier]).execute render_api_error!(response.message, response.reason) if response.error? group, user = response.payload.values_at(:group, :user) { success: true, namespace: group.full_path, username: user.username } end ``` Instance-level CAs grant instance-wide access, so there is no namespace to return. ## Proposal ### 1. `InstanceSshCertificates::FindService` New service taking `ca_fingerprint` and `user_identifier`: - Look up the CA via `InstanceSshCertificate.for_fingerprint`. Not found → `:not_found`. - Return `:not_found` unless `InstanceSshCertificate.available?` (the `.com` + beta flag guard from #611272). - Resolve `user_identifier` (cert `KeyId`) with `User.find_by_login`. Not found → `:not_found`. - No membership check — trust is instance-wide by definition. - **No Enterprise User check.** That is a GitLab.com concept and this feature is not offered on `.com`. Deliberate divergence from `Groups::SshCertificates::FindService`, which requires `enterprise_user_of_group?`. - **No licensed-feature check.** The epic specifies all tiers, unlike group-level which gates on `:ssh_certificates`. - Return `ServiceResponse.success(payload: { user: user })` — no group. Worth settling during implementation: whether a blocked, banned, or deactivated user should be rejected here or left to `/allowed`. Group-level leans on membership lookup, which implicitly filters some of these; instance-level has no such filter, so the behaviour needs to be explicit rather than inherited. ### 2. Response shape The response carries an `instance` boolean identifying the scope of the match. Instance-level match: ```json { "success": true, "username": "alice", "instance": true } ``` Group-level match: ```json { "success": true, "username": "alice", "namespace": "acme", "instance": false } ``` `instance: false` is sent explicitly on the group path so that gitlab-sshd can assert the two fields agree, and reject a group-scoped response that arrives with a blank namespace rather than treating it as instance-wide access. A Rails bug producing an empty `full_path` therefore fails closed instead of granting instance-wide trust. The field is additive, so an older gitlab-sshd that ignores it continues to work against a newer Rails. ### 3. Endpoint changes Group resolution runs first and is unchanged; instance resolution is the fallback: ```ruby get '/authorized_certs', ... do group_response = ::Groups::SshCertificates::FindService.new(params[:key], params[:user_identifier]).execute if group_response.success? group, user = group_response.payload.values_at(:group, :user) return { success: true, namespace: group.full_path, username: user.username, instance: false } end instance_response = ::InstanceSshCertificates::FindService.new(params[:key], params[:user_identifier]).execute render_api_error!(group_response.message, group_response.reason) if instance_response.error? { success: true, username: instance_response.payload[:user].username, instance: true } end ``` On a double miss the group error is returned, so the response does not reveal whether an instance CA exists for that fingerprint. Confirm in review that this doesn't mask a genuinely useful instance-level message. ### 4. Precedence Three layers now exist: 1. **File-based** (`sshd.trusted_user_ca_keys`) — resolved inside gitlab-sshd, never reaches Rails. 2. **Group-level DB** — namespace-scoped. 3. **Instance-level DB** — no namespace. Rails only sees 2 and 3, and group wins. A fingerprint registered both as a group CA and an instance CA resolves as group-scoped, the more restrictive outcome. #611272 makes instance fingerprints unique within their own table but cannot prevent this cross-table overlap, so it is resolved here by ordering. ### 5. Validation Expired certificates, host certificates, and malformed `KeyId` values are rejected by gitlab-sshd before it calls Rails, as with file-based CAs. No new validation here — but the specs should assert the endpoint is not the enforcement point, so a later refactor doesn't silently assume otherwise. ## Acceptance criteria - [ ] `InstanceSshCertificates::FindService` resolves a user from a CA fingerprint plus `KeyId`. - [ ] Service returns `:not_found` when the feature is unavailable (`.com` or flag off). - [ ] No Enterprise User check and no licensed-feature check applied. - [ ] Instance match returns `username` and `instance: true`, with no `namespace`. - [ ] Group match returns `namespace`, `username`, and `instance: false`. - [ ] Group-level resolution is otherwise unchanged; existing specs pass untouched. - [ ] A fingerprint matching both a group CA and an instance CA resolves as group-scoped. - [ ] Unknown fingerprint and unknown `KeyId` both yield `:not_found`. - [ ] Endpoint remains `urgency: :high` and adds no N+1; fingerprint lookup is index-backed. - [ ] Request specs cover instance match, group match, both, and neither. - [ ] Precedence documented in the blueprint or endpoint comment. ## Out of scope - gitlab-sshd consumption of the `instance` field — next issue. - Auth-time audit events — separate issue, though this is the code path they will hook into. - Admin API and UI for managing the CAs. ## Links - Epic: gitlab-org&22743 - Depends on: #611272 - Group-level equivalent: #421538 - `ee/lib/ee/api/internal/base.rb` - `ee/app/services/groups/ssh_certificates/find_service.rb`