## Summary

Adds the OAS-native OAuth 2.0 `scopeCheck` sub-block on the new `oauth2`
security scheme and the gateway middleware that enforces it. Required
scopes live in the **OAS root `security:` array** — standard OpenAPI
Security Requirement Objects, OR-of-AND across entries. The `scopeCheck`
block on the Tyk extension carries only the token-side knobs: which JWT
claims to read scopes from, how to split string-form values, and which
scope-source mode is active. Validation, scope merging across claims,
and the RFC 6750 §3 `Bearer SP 1#auth-param` failure challenge all live
here.

The scheme is name-agnostic — operators can name the OAS
`securitySchemes` entry anything (`oauth2`, `prctOauth`, `corpOAuth`,
…); enforcement uses whatever name the document declares.

## Story

- JIRA: https://tyktech.atlassian.net/browse/TT-17173

## Stacked on

This PR is stacked on TT-17172 — #8198. Review/merge
that first; once it merges this can be retargeted to `master`.

## Companion PRs

These three ship together — please block until all three are green:

- `tyk`: this PR
- `tyk-analytics`: TykTechnologies/tyk-analytics#5629
- `tyk-analytics-ui`: TykTechnologies/tyk-analytics-ui#4370

## Behaviour

### Apidef (`apidef/oas/`)

- `OAuth2ScopeCheck`: `Enabled`, `ClaimNames []string`, `Separator
string`, `ScopeSource string`. There is no `Scopes` field — scope policy
lives in OAS root `security:`.
- `ScopeSource` constants: `operation`, `global`, `union` (default).
- Map-probe disambiguator (`asOAuth2Scheme` + `mapHasOAuth2SubBlock`)
tells the OAS-native `OAuth2` scheme apart from legacy `*OAuth` /
`*ExternalOAuth` schemes after JSON round-trip — recognised by presence
of an oauth2 sub-block key.
- `SecurityRequirementScopes [][]map[string][]string` sibling field on
`apidef.APIDefinition` preserves per-scheme scope arrays across the
extract/fill round-trip (omitempty; forward-compatible).
- `extractSecurityTo` single-alternative branch: populates
`SecurityRequirements` with every scheme in the requirement (including
empty-scope ones like `jwtAuth: []`) so multi-scheme single-AND security
policies (JWT + OAuth2 in one entry) survive round-trip without silently
dropping the JWT scheme.
- Validator rejects an unknown `scopeSource` at API load with a clear
error.
- Strict + non-strict OAS schemas declare `X-Tyk-OAuth2-ScopeCheck` with
the four token-side fields.

### Gateway (`gateway/mw_oauth2.go`)

- `OAuth2Middleware` enforces scope check when `oauth2.enabled` and
`scopeCheck.enabled` are both true.
- `rootSecurityAlternatives(security, schemeName, scopeCheck)` reads
root `security:` and returns the OR-of-AND list of alternatives drawn
from entries that reference the configured scheme. Declared order is
preserved end-to-end so the operator sees their authored form on the
failure challenge.
- Token's scope set is the **merged union** across every claim in
`ClaimNames` (default `["scope", "scp"]`). Each claim value is parsed by
`Separator` (default single space), JSON array form, or comma-separated
form per RFC 6749 §3.3.
- On insufficient scope: 403, RFC 6750 §3 `WWW-Authenticate: Bearer
error="insufficient_scope" …` challenge citing the **first** declared
alternative only (intentionally — listing every alternative would leak
that the API has a service-account path and a user path), JSON body with
`error` / `error_description` / `scope`, and an `OAuth2ScopeCheckFailed`
audit event carrying the cited alternative + full alternative list.
- An entry that lists the scheme with an empty scope list (`security: -
oauth2: []`) is treated as "auth required, no specific scope" —
vacuously satisfied, short-circuits the OR to pass.

### Wire-protocol constants

- `OAuth2ErrInsufficientScope` = `"insufficient_scope"` (RFC 6750 §3.1)
- `OAuth2ErrInvalidToken` = `"invalid_token"` (RFC 6750 §3.1)

## Test plan

- [x] `go test ./apidef/oas/ ./gateway/ ./internal/oauth2common/` — unit
tests cover: nil/empty/operation-suppression, single-AND, OR-across,
OR-of-AND, sort+dedup, vacuous-satisfaction, multi-scheme
single-alternative round-trip preservation, name-agnostic enforcement
(`TestOAuth2Middleware_NameAgnostic`), RFC 6750 §3 challenge header form
- [x] Python e2e — runs in the dashboard companion PR
- [ ] Postman collection via newman
- [ ] Manual smoke

## Risk

Failure-challenge form cites only the first declared alternative —
deliberate, regression-tested. The strict-schema deltas across four
schema files must stay in sync. The map-probe disambiguator's sub-block
key list (`oauth2SubBlockKeys`) needs an entry added whenever a new
OAuth2 sub-block is introduced, otherwise the typed view is silently
dropped on JSON round-trip.

🤖 Generated with [Claude Code](https://claude.com/claude-code)




<!---TykTechnologies/jira-linter starts here-->

### Ticket Details

<details>
<summary>
<a href="https://tyktech.atlassian.net/browse/TT-17173" title="TT-17173"
target="_blank">TT-17173</a>
</summary>

|         |    |
|---------|----|
| Status  | Merge |
| Summary | OAuth2 scope check — global / API level |

Generated at: 2026-05-26 15:20:57

</details>

<!---TykTechnologies/jira-linter ends here-->

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>