Skip to content

11.1.0: CakePHP 5.4, Keycloak/OIDC, security and review fixes - #110

Merged
steinkel merged 35 commits into
CakeDC:11.next-cake5.4from
arodu:feature/improvements
Nov 18, 2026
Merged

steinkel merged 35 commits into
CakeDC:11.next-cake5.4from
arodu:feature/improvements

Conversation

@arodu

@arodu arodu commented Nov 13, 2026

Copy link
Copy Markdown
Member

Summary

Release 11.1.0. No public API is removed; the changes are compatible for applications using the plugin as documented. See CHANGELOG.md for the full list.

  • Requires CakePHP ^5.4 and PHP >=8.2; cakephp/authentication ^3.3 is now a runtime dependency.
  • Adds Keycloak social login (rolesMap per provider alias), an OpenID Connect service and the LinkedInOpenIDConnect provider.
  • Hardens Rbac rule configs, OIDC id token/JWKS validation, Azure/LinkedIn/Keycloak email validation and the Keycloak role check.
  • Deprecates the LinkedIn, Instagram, Pinterest and Tumblr mappers (removed in 12.0); load the plugin with AuthPlugin.
  • Raises static analysis to PHPStan level 8 / Psalm level 2 and makes PHPCS warnings fail.

Upgrade notes

  • validated is only true for a JSON boolean true (email_verified / xms_edov). String and numeric claims no longer count as verified.
  • An allowed or bypassAuth array must be a valid rule config (a className implementing Rule); malformed arrays throw InvalidArgumentException instead of allowing every logged-in user.
  • BaseTestTrait stores the user at Auth.Authenticators.Session.sessionKey (Auth) and provider() must be static.
  • The resetOneTimePasswordAuthenticator default permission now allows users with integer ids to reset their own OTP.
  • TwoFactorProcessorInterface::getUrlByType() may return a string; callers must handle it.
  • Requests without a social provider param now return 404 instead of 500.

Security

  • Azure: the nOAuth pattern is fixed; only email_verified or xms_edov marks an email as validated.
  • Rbac: malformed allowed/bypassAuth rule configs throw instead of allowing any logged-in user.
  • OpenID Connect: validates the id token signature and iss/aud/azp/nonce; only loads jwks_uri below openid.baseUrl and rejects dot segments (raw or percent-encoded).
  • Keycloak: a partial mapFields no longer drops id, roles and validated; rolesMap works for any provider alias.
  • LinkedIn OIDC and Keycloak: only a boolean true validates the email.

Added

  • Keycloak mapper with realm role mapping (rolesMap, case-sensitive, first match wins).
  • OpenIDConnectService and the LinkedInOpenIDConnect provider with discovery/JWKS caching and key rotation.
  • OTPRule and array rule configs for Rbac.
  • String URLs for the 2FA verify URL.

Fixed

  • /auth/{provider} route matching on CakePHP 5.
  • ReCaptcha with a missing token no longer raises a TypeError.
  • SuperuserPolicy event role, TwoFactorMiddleware without an auth result, and ServiceFactory without a provider param.
  • openid provider settings reach OpenIDConnectService.
  • RuleRegistry JSON encoding errors and the Rbac match reason output.
  • BaseTestTrait test permissions and session storage.

Testing

  • Local (PHP 8.4): composer check (343 tests, 825 assertions, PHPCS on 130 files) and composer analyse (PHPStan level 8, Psalm) pass.
  • CI: PHP 8.2–8.5 × sqlite/mysql/pgsql with highest dependencies plus one lowest-dependencies job; PHPCS, Psalm and PHPStan.

Notes

  • The 11.1.0 changelog entry also records the 11.0.0 changes that were tagged without a changelog entry.

ajibarra and others added 30 commits October 30, 2026 12:37
require stevenmaguire/oauth2-keycloak

(cherry picked from commit 48501d6)
New Exceptions for error handling

(cherry picked from commit debf42e)
(cherry picked from commit 0700e22)
(cherry picked from commit a92a1c4)
(cherry picked from commit 3600ad2)
(cherry picked from commit 0ec3055)
(cherry picked from commit 504de17)
(cherry picked from commit f18f379)
…om map fields in Keycloak mapper

(cherry picked from commit 83d34d8)
(cherry picked from commit 291099c)
(cherry picked from commit 4c0a660)
(cherry picked from commit aee0010)
(cherry picked from commit 978370b)

# Conflicts:
#	config/auth.php
(cherry picked from commit d3f825e)
(cherry picked from commit ad6e98b)
(cherry picked from commit 891a7b7)
Partial cherry-pick of 5d4e5df (implements CachedRbac functionality): only OTPRule, the
className/options rule config branch in Rbac and its use in the default permissions are taken.
CachedRbac is not included.

(cherry picked from commit 5d4e5df)
…ependencies

- 2FA: encode the query params of string verify urls, U2FProcessor::getUrlByType()
  returns array|string|null like the interface.
- OIDC: validate the id token iss, aud and nonce claims, cache the discovery
  document and the key set with `openid.cache`.
- Rbac: fix the OTPRule signature, only treat arrays with a Rule `className` as
  rule config.
- Keycloak: drop the global social login listener and the runtime role config
  write, clean up the mapper and add tests.
- Docs, changelog and composer suggestions for the new providers.
- composer.json: require cakephp/authentication ^3.3 and CakePHP ^5.4, curate the
  dev dependencies for PHP 8.2 to 8.5 (lowest and highest), psalm 6 phar with a
  baseline, remove the stan-setup script.
- Tests: replace docblock PHPUnit metadata with attributes.
- Rbac: an `allowed` or `bypassAuth` rule config whose className is not a Rule
  throws instead of allowing every logged in user.
- OIDC: fetch the key set again when a token uses an unknown key id, fetch the
  discovery document once per instance, check response status, log decode
  errors and return a generic message, clear error without firebase/php-jwt.
  New tests verify RS256 tokens against a served key set.
- Keycloak: no default roles map, case-sensitive role names.
- LinkedIn OIDC: map `validated` from the `email_verified` claim.
- Routing: use the CakePHP 5 `{provider}` placeholder, `/:provider` never matched.
- SuperuserPolicy: read the role of entity identities in the
  `Auth.Authorization.checked` event.
- OneTimeTokenAuthenticator: only join token arrays that are a list of strings.
- Tests for OneTimeTokenAuthenticator, SuperuserPolicy events,
  OneTimePasswordAuthenticatorComponent configuration errors and plugin routes.
…ctions

- cs-check, psalm and phpstan fail the build (no more continue-on-error)
- add a PHP 8.2 lowest dependencies job, the prefer-lowest matrix entry was
  never set
- comment out the Codecov upload: uploads failed without a token since 2024
- replace the deprecated ::set-output cache steps with ramsey/composer-install
- actions/checkout v5, ubuntu-24.04 for both jobs, no coverage driver
- read-only token permissions, cancel superseded runs, skip pull_request runs
  for branches of this repository (already tested by push)
- only install the PHP extensions the tests use
`Plugin` and `AuthPlugin` held the same route code. `Plugin` now extends
`AuthPlugin` and is deprecated, CakePHP 5.3 expects the `AuthPlugin` name.
- testPermissions() declares its data provider with #[DataProvider('provider')],
  PHPUnit 12 ignores the docblock annotation.
- testPermissions() returns void, it failed with a missing array return value.
- Empty CSV lines are skipped, rows without the "Response Contains" column work,
  str_getcsv() gets an explicit escape (PHP 8.4 deprecation).
- The CSV path can be changed by overriding _permissionsCsvPath().
Deprecate legacy social mappers, fix Azure validated, Keycloak mapFields, OIDC config and checks, TwoFactorMiddleware and ServiceFactory errors, BaseTestTrait. PHPStan level 8, Psalm level 2 baseline, PHPCS warnings. Docs, changelog and copyright years.
@arodu
arodu requested a review from ajibarra November 13, 2026 22:18
@steinkel
steinkel merged commit 4ce9c3c into CakeDC:11.next-cake5.4 Nov 18, 2026
14 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.

6 participants