Component: vertx-web / OAuth2AuthHandler
Affected: Vert.x 5.x (confirmed on 5.1.6)
Regression: Behavior differs from 4.x
Description
In Vert.x 5, OAuth2AuthHandler falls back to the current route's "scopes" metadata when no scopes are explicitly configured.
This can cause scopes to be enforced even though the application never configured scope validation on the handler.
This is especially problematic with vertx-web-openapi-router, which can automatically add scope metadata based on the OpenAPI security definition.
For applications that use OAuth2AuthHandler only for authentication and implement authorization separately (e.g. roles/permissions), this can result in unexpected 403 responses.
In Vert.x 4.x, scope validation was only performed when scopes were explicitly configured.
Example
OAuth2AuthHandler.create(vertx, provider);
If the matched route contains:
metadata["scopes"] = ["some-scope"]
the handler will validate some-scope against the token, even though the application never configured this scope.
Current workaround
Using:
.withScope("openid")
prevents the route-metadata fallback because the handler now has an explicit scope.
However, this is not an ideal solution. openid is a standardized OIDC scope with a specific semantic meaning related to requesting an ID token. It is being used here only as a magic non-empty value to suppress an internal fallback mechanism.
This is misleading for consumers and can make it appear that the application actually requires the openid scope, even when the handler is only being used for authentication.
Suggested fix
Provide an explicit way to disable scope validation, for example:
.withoutScopeValidation()
or define an explicitly empty scope list as:
.withScopes(Collections.emptyList())
meaning "do not perform scope validation".
This would allow OAuth2AuthHandler to be used purely for authentication without implicitly enforcing scopes from route metadata.
Contribution
No response
Component: vertx-web / OAuth2AuthHandler
Affected: Vert.x 5.x (confirmed on 5.1.6)
Regression: Behavior differs from 4.x
Description
In Vert.x 5, OAuth2AuthHandler falls back to the current route's "scopes" metadata when no scopes are explicitly configured.
This can cause scopes to be enforced even though the application never configured scope validation on the handler.
This is especially problematic with vertx-web-openapi-router, which can automatically add scope metadata based on the OpenAPI security definition.
For applications that use OAuth2AuthHandler only for authentication and implement authorization separately (e.g. roles/permissions), this can result in unexpected 403 responses.
In Vert.x 4.x, scope validation was only performed when scopes were explicitly configured.
Example
OAuth2AuthHandler.create(vertx, provider);If the matched route contains:
metadata["scopes"] = ["some-scope"]the handler will validate some-scope against the token, even though the application never configured this scope.
Current workaround
Using:
.withScope("openid")prevents the route-metadata fallback because the handler now has an explicit scope.
However, this is not an ideal solution. openid is a standardized OIDC scope with a specific semantic meaning related to requesting an ID token. It is being used here only as a magic non-empty value to suppress an internal fallback mechanism.
This is misleading for consumers and can make it appear that the application actually requires the openid scope, even when the handler is only being used for authentication.
Suggested fix
Provide an explicit way to disable scope validation, for example:
.withoutScopeValidation()or define an explicitly empty scope list as:
.withScopes(Collections.emptyList())meaning "do not perform scope validation".
This would allow OAuth2AuthHandler to be used purely for authentication without implicitly enforcing scopes from route metadata.
Contribution
No response