Skip to content

feat: stateless Bearer authenticators, issuer option and organizations (4.2.0) - #70

Merged
mainick merged 6 commits into
mainfrom
feature/bearer-authenticator
Nov 14, 2026
Merged

mainick merged 6 commits into
mainfrom
feature/bearer-authenticator

Conversation

@mainick

@mainick mainick commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Adds what an API needs to authenticate Keycloak access tokens through the Symfony security system, verifying them locally. Everything is opt-in, so it targets a minor release (4.2.0): with the configuration unchanged, behaviour is the same as 4.1.

Release notes (4.2.0)

Added

  • KeycloakBearerAuthenticator: stateless authenticator for Authorization: Bearer tokens, verified locally with verifyToken() (signature, expiration, issuer) without calling Keycloak on each request. Failures get a 401 JSON response.
  • KeycloakOptionalBearerAuthenticator: same verification, but an invalid token lets the request continue as anonymous (public routes).
  • bearer configuration node (disabled by default) with roles_source (all | authorized_party, see RolesSourceEnum), allowed_clients and client_roles (applied only with authorized_party).
  • keycloak.issuer option: when set, verifyToken() requires an exact iss match. Useful when the app reaches Keycloak on an internal URL that differs from the public issuer.
  • UserRepresentationDTO: authorizedParty, authorizedPartyRoles, organizations, issuer, expiresAt and raw claims (trailing, nullable, positional constructor of 4.1 still works).
  • OrganizationRepresentationDTO: reads the organization claim in every format Keycloak emits (list of aliases, single alias, map with id and attributes).
  • KeycloakResourceOwner::getAuthorizedParty() and getOrganizations().

Changed

  • verifyToken() logs the decoded token at debug level instead of info.
  • symfony/yaml added to require-dev (used by the new extension test).

Deprecated

  • TokenAuthListener: use the Bearer authenticator. It will be removed in 5.0.

Fixed

  • Nothing

Removed

  • Nothing

Compatibility

  • bearer is disabled by default: the authenticators are not registered.
  • roles_source defaults to all, so KeycloakResourceOwner::getRoles() keeps returning realm roles plus every client's roles; client_roles is ignored in that mode. getRoles($clientId) with an explicit client keeps its 4.1 meaning.
  • UserRepresentationDTO::$claims carries the raw token claims: avoid serializing the DTO into responses or logs as a whole.
  • TokenDecoderInterface is unchanged: the issuer check lives in KeycloakClient::verifyToken().
  • Breaking follow-ups are left to 5.0: nullable email/emailVerified (UserRepresentationDTO: email and emailVerified should be nullable #69) and the removal of TokenAuthListener.

Tests

  • composer test: 157 tests, all green.
  • composer lint: clean.
  • phpstan is not a gate in CI and already reports errors on main; no new errors in the touched files.

🤖 Generated with Claude Code

mainick and others added 6 commits November 14, 2026 18:14
…entationDTO

UserRepresentationDTO gets new trailing fields, all defaulting to null so
the 4.1 positional constructor keeps working:

- authorizedParty and authorizedPartyRoles, from `azp` and
  `resource_access[azp]`;
- organizations, read by the new OrganizationRepresentationDTO from the
  `organization` claim in every format Keycloak emits (list of aliases,
  single alias, map alias => {id, attributes});
- issuer, expiresAt and the raw claims.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The decoders only check that `iss` contains the realm name. The new
`keycloak.issuer` option, when set, makes verifyToken() require an exact
match. It is needed when the application reaches Keycloak on a different
URL (e.g. an internal Docker hostname) than the public one that issues
the tokens, so `base_url` cannot be used for the comparison.

Without the option the behaviour is unchanged, and TokenDecoderInterface
is untouched for custom decoders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
KeycloakBearerAuthenticator reads the `Authorization: Bearer` header and
verifies the access token locally with verifyToken(), without calling
Keycloak on each request; failures get a 401 JSON response.
KeycloakOptionalBearerAuthenticator lets the request continue as anonymous
instead, for public routes.

They are registered only when the new `bearer` option is enabled:

- `roles_source`: `all` (default, as KeycloakResourceOwner always did) or
  `authorized_party`, only the roles of the client that requested the token;
- `allowed_clients`: accepted `azp` values, empty means any;
- `client_roles`: extra roles granted according to `azp`.

KeycloakResourceOwner gains getAuthorizedParty() and getOrganizations().
symfony/yaml is added to require-dev to test the extension.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
verifyToken() logged every decoded claim at info level twice. With the
Bearer authenticator it runs on each API request, so the claims now go to
the debug level.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TokenAuthListener calls the userinfo endpoint on each request and works
outside the Symfony security system. It now triggers a deprecation and
will be removed in 5.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- client_roles apply only with roles_source `authorized_party`, so the
  default `all` keeps the 4.1 roles even when client_roles is configured;
- getRoles($client_id) always returns realm roles plus that client's roles,
  whatever the source;
- roles_source becomes RolesSourceEnum instead of string constants;
- malformed `roles` claims and an empty `azp` are ignored instead of
  raising warnings;
- the two authenticators share their arguments through a YAML anchor;
- README: client_roles scope, debug log level and raw claims in the DTO.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mainick
mainick merged commit b07f491 into main Nov 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant