Part of the MCP granular token work (#630327, **W2.3**). Depends on W2.1 (#630370, !257023) for the table and model, and on W2.2 (#631824) for the shared builder. Gated by the `granular_oauth_tokens` feature flag introduced in !257024. If this lands before !257024, introduce the flag here with the same name and `wip` type. ## Scope Backend service only. The admin and group UI and the `POST /applications` REST parameter that call it are W3. Revoking grants when the set changes is W3. ### What exists after !257023 `Authn::OauthApplication` has `has_many :oauth_application_granular_scopes` with autosave, `has_many :granular_scopes, through:`, and `#granular?`. `Authz::OauthApplicationGranularScope` belongs to organization, application and granular scope, with `populate_sharding_key :organization_id, source: :application`. Nothing writes the table. ### Consumer `Authz::OauthConsentGrants::CreateService` in !257024 copies each declared row into the user's grant with `GranularScope#build_copy`. Declared rows therefore need only a valid access level, namespace, permissions, and the application's `organization_id`. ### Application flavours Four flavours exist. They are told apart only by `owner` and `dynamic`. | Flavour | owner | dynamic | Created by | Managed by | |---|---|---|---|---| | Instance | nil | false | `app/controllers/admin/applications_controller.rb:79-84` sets `owner = nil`. Also `lib/api/applications.rb`, admin only. | instance admin | | Group-owned | Group | false | `app/controllers/groups/settings/applications_controller.rb:83-88` sets `owner = @group`. `authorize_admin_group!` at line 8. | group owner | | User-owned | User | false | `app/controllers/oauth/applications_controller.rb:104-109` sets `owner = current_user`. Gated by the `user_oauth_applications` setting. | that user | | Dynamic | nil | true | `app/controllers/oauth/dynamic_registrations_controller.rb:43-50`. Unauthenticated, `dynamic: true`, scopes forced to `mcp`. | nobody | `app/finders/applications_finder.rb:11` uses `owner_id: nil` for instance applications, so a nil owner alone does not identify one. Test `dynamic` first. ### Why the PAT check does not transfer PAT creation asks `Ability.allowed?(current_user, :read_boundary, resource)`. That means: may this user use this resource as a boundary. `read_boundary` is granted through role YAML to guest-or-higher members, to anyone on public projects and groups, and to admins. An application has an owner, not a user. The question has to be answered per flavour. ### Owner rule | Flavour | Allowed access levels | Check for `selected_memberships` namespaces | |---|---|---| | Dynamic | none, refuse | n/a | | Instance | `user`, `instance`, `all_memberships`, `selected_memberships` | Namespace must exist. The existing `organization_match` validation on `Authz::GranularScope` already rejects namespaces from another organization. | | Group-owned | `user`, `selected_memberships` | `namespace.traversal_ids.include?(owner.id)`, i.e. the group itself or any descendant group or project namespace. Refuse `instance`, `all_memberships` and `personal_projects`, because they reach outside the hierarchy. | | User-owned | same as PATs | `Ability.allowed?(owner, :read_boundary, resource)`. `personal_projects` uses `owner.namespace`. | `user` access must be allowed for every non-dynamic flavour. The MCP entry routes are declared at the user boundary at `lib/api/mcp/base.rb:209` and `:249` with `route_setting :authorization, permissions: :execute_mcp_tool, boundary_type: :user`. `execute_mcp_tool` is only assignable at `user`, per `config/authz/permission_groups/assignable_permissions/duo/mcp_tool/execute.yml`. Build the scopes with W2.2's shared builder and pass the flavour check as the pluggable boundary check. ### Actor authorisation Enforce this inside the service. W3's UI and API will both call it, so the controller checks cannot be relied on. - Instance: the actor must be an instance admin. - Group-owned: `Ability.allowed?(current_user, :admin_group, owner)`. - User-owned: `owner == current_user`. ### Escalation Run `Authz::Tokens::PrivilegeEscalationCheck.new(scopes, access_token)` when the actor's own token is granular. Mirror `create_granular_token` in `lib/api/helpers/personal_access_tokens_helpers.rb:136-147`. ### Semantics Replace the whole declared set in one transaction. One scope per namespace per application, enforced by W2.2's generalised uniqueness check. ### The `granular` scope on the application Doorkeeper 5.9 refreshes a token with the intersection of the old token's scopes and the application's configured scopes. !257024 makes `granular` a configurable scope again via `Gitlab::Auth.optional_scopes`. It hides and strips `granular` in the application form through `excluded_scopes` in `app/controllers/concerns/oauth_applications.rb`. Nothing adds it to any application. The local setup in !257024 creates the application with `scopes: 'api granular'` by hand. The service must append `granular` to `oauth_applications.scopes` when the set is non-empty. Recommendation: do not remove it when the set is cleared. Outstanding granular tokens would otherwise refresh into an empty scope set. ### `execute_mcp_tool` warning A declared set without `execute_mcp_tool` at the user boundary mints tokens that pass consent and then fail every MCP request. Recommendation: return a warning in the `ServiceResponse` payload rather than a hard validation. The same service will serve non-MCP OAuth applications. W3's UI and API surface the warning. Record the decision on this item. ### Audit Add the audit event type `oauth_application_granular_scopes_updated` in `config/audit_events/types/`. Use `feature_category: permissions`, matching the grant events in !257024. Scope it like the existing `oauth_application_updated` event. `additional_details` lists each scope's `access`, `namespace_id` and `permissions`. Use the same shape !257024 uses for grant audits. ### Verification Console proof end to end with !257024. 1. Declare a set on a group-owned application. 2. Run the browser authorisation flow. 3. Confirm the token resolves the grant and `permitted_for_boundary?` answers per the declared set. 4. Confirm a request outside the declared namespace is denied. #608638 "Prove a granular OAuth token end-to-end from the Rails console" can be extended with this. One MR, two at most. The first covers the service, owner rule, scopes column and audit event. The warning and console proof can ride along or be a small second MR. ## Acceptance criteria - [x] A declaring service exists and applies the owner rule per flavour. - [x] Dynamic applications are refused. - [x] Actor authorisation is enforced inside the service for instance, group-owned and user-owned applications. - [x] The escalation check is applied when the actor's token is granular. - [x] The declared set is replaced in one transaction, with one scope per namespace. - [x] `granular` is appended to `oauth_applications.scopes` when the set is non-empty. - [x] A warning is returned in the `ServiceResponse` payload when `execute_mcp_tool` at the user boundary is missing. The decision is recorded on this item. - [ ] The `oauth_application_granular_scopes_updated` audit event is emitted with `additional_details` per scope. - [x] The `granular_oauth_tokens` flag gates the service. - [x] Specs cover each flavour, dynamic refusal, organisation mismatch, duplicate namespace, forbidden actor and escalation. - [ ] The console proof is recorded.