[Batch 5] Add tier annotations to auth and access API endpoints

Vlad Wolanykrequested to merge
631956-api-tier-auth-access into master

What does this MR do and why?

Adds route_setting :tier to 47 auth and access REST API routes. This is the fifth MR in a series that annotates Premium and Ultimate endpoints.

This is documentation only. The setting becomes x-gitlab-tier in doc/api/openapi/openapi_v3.yaml, so API users can see which subscription tier an endpoint needs. Nothing reads it at runtime. There is no behavior or permission change. Free endpoints get no annotation.

Earlier MRs in the series:

What changed

  • 47 routes in 8 files: 30 Premium, 17 Ultimate.
  • Each route gets a plain route_setting :tier, :<tier> above its route_setting :authorization.
  • There are 43 added lines for 47 routes. provider_identity.rb serves SAML and SCIM from the same 4 definitions, and both are Premium.
  • Grape route settings do not cascade, so each route sets its own.
  • OpenAPI: +47 x-gitlab-tier lines (30 premium, 17 ultimate). Nothing else changed.
How each tier was chosen

Code is the source of truth. Docs are a cross-check.

The rule comes from !259422 (merged). Annotate the lowest tier at which the endpoint does something useful. If an endpoint is gated lower than the feature that makes it take effect, use that feature's tier.

A tracer recorded licensed-feature checks during the request specs (8 spec files, all passing). 43 of 47 routes match the docs tier. The 4 that differ are the documented credentials inventory routes (see note 1).

Routes Tier Basis
Member roles (6), admin member roles (3) Ultimate custom_roles (tracer)
Group credentials inventory, ee/lib/api/manage/groups.rb (8) Ultimate See reviewer note 1
SAML group links (4) Premium saml_group_sync (tracer)
SSH certificates (3), group audit events (2), LDAP sync (1) Premium ssh_certificates, audit_events, ldap_group_sync (tracer)
LDAP group links (5) Premium Rule: links only sync with ldap_group_sync
SAML and SCIM identities (8), SAML users (1), provisioned users (1) Premium Rule: need group SAML/SCIM (group_saml)
Enterprise users (5) Premium Rule: enterprise users only exist through domain_verification

Reviewer notes

  1. Group credentials inventory (8 routes) is annotated Ultimate, and the API has no license check. Please look at this one first.
  2. Some routes have no license check but are Premium by the rule. They only do something with a paid feature. All match the docs.
  3. Some routes reported extra feature checks from spec setup. These are not the tier gate.
Note 1: credentials inventory
  • The API (ee/lib/api/manage/groups.rb) has no license check. It only checks for GitLab.com and admin_group.
  • The UI requires credentials_inventory, which is Ultimate.
  • doc/administration/credentials_inventory.md says Ultimate.
  • Only the API docs section in doc/api/groups.md says Premium. That looks stale.
  • A throwaway request spec confirmed the missing license check at runtime.
  • The same spec confirmed there is no cross-boundary access. A subgroup Owner is denied on the parent group, and subgroup calls return only subgroup data.
  • The missing check is reported to group::authentication in a separate issue: .
  • This MR does not change behavior.
Note 2: routes with no license check of their own

These routes are Premium per the rule:

  • LDAP group links: can_manage_ldap is admin or an instance setting. Links only sync with ldap_group_sync.
  • SAML/SCIM identities and SAML/provisioned users: need group SAML.
  • Enterprise users: only exist through domain verification.
Note 3: incidental feature checks

Some routes reported feature checks that come from spec setup. For example, custom_roles shows up on LDAP and SAML link creation because of a custom role param. These are not the tier gate.

How to set up and validate locally

  1. Run bin/rake gitlab:openapi:v3:generate. The diff should only add x-gitlab-tier lines.
  2. This MR adds 47 lines. On its own, grep -c x-gitlab-tier doc/api/openapi/openapi_v3.yaml gives 50 (was 3). It will be higher if earlier MRs merged first.
  3. Run RuboCop on the changed files. It is clean.

Related to #631956 (closed)

Merge request reports