Required Authorization

The Required Authorization panel

Expanding an operation in the UI renders a panel between the summary row and the parameters — showing what a caller needs in order to use that endpoint.

┌─ Required Authorization ────────────────────────────┐
│  Scheme        jwt  (http · bearer · JWT)           │
│  Roles claim   realm_access.roles                   │
│  Required      [ admin ]  [ users:write ]           │
└─────────────────────────────────────────────────────┘

It is a Swagger UI plugin bundled with this module. Nothing to enable.

Where the data comes from

Two vendor extensions in the OpenAPI document, both emitted by rextension-openapi:

{
  "paths": {
    "/users/{id}": {
      "delete": {
        "security": [{"jwt": []}],
        "x-required-roles": {"jwt": ["admin"]}
      }
    }
  },
  "components": {
    "securitySchemes": {
      "jwt": {
        "type": "http", "scheme": "bearer", "bearerFormat": "JWT",
        "x-roles-claim": "realm_access.roles"
      }
    }
  }
}

Getting them into the document

Roles on the route:

func (r *DeleteUser) RequiredSchemes() []string { return []string{"jwt"} }

func (r *DeleteUser) RequiredRoles() map[string][]string {
	return map[string][]string{"jwt": {"admin"}}
}

The claim on the scheme:

security.NewBearerScheme("jwt", validator).
	SetBearerFormat("JWT").
	SetRolesClaim("realm_access.roles")

SetRolesClaim is documentation only — it tells a reader where in the token the roles live. Enforcement is the validator's business; see rextension-security → Roles and scopes.

Scopes

Scopes are a first-class OpenAPI concept, so they appear in the security requirement itself rather than as an extension:

func (r *DeleteUser) RequiredScopes() map[string][]string {
	return map[string][]string{"jwt": {"users.write"}}
}

"security": [{"jwt": ["users.write"]}]

Swagger UI renders these in its own authorization section.

What it is for

Reading a spec, "this endpoint is secured" is much less useful than "this endpoint needs admin in realm_access.roles". The panel closes the gap between the API document and the identity system, which is otherwise a conversation.

It is also a review surface: an operation whose panel says less than you expected is a route that is not enforcing what you thought. The security extension makes an unenforceable requirement a startup error, but a requirement nobody declared is invisible — except here.

Styling it

The panel carries its own classes, so a custom theme can restyle it:

.swagger-ui .required-roles-panel { border-left: 3px solid #f59e0b; }

When it does not appear

• The operation has no x-required-roles — the route does not implement RequiredRoles(), or the map key does not match a name in RequiredSchemes().
• The security extension is not registered, so no schemes are documented at all.
• The UI is pointed at a document generated by something other than rextension-openapi, which will not emit the extensions.