feat: add Keycloak role-based user filtering

[olekristoffer]

Contribution Guidelines

• I've read the contribution guidelines and wholeheartedly agree them

What does this PR include?

Short Description

This PR adds optional role-based filtering for Keycloak-backed identity provider users.

Administrators can restrict Keycloak login and synchronization/import to users with a configured realm role or client role. Role membership is checked through the Keycloak Admin REST API, including direct role assignments and roles inherited through groups.

It supports both keycloak client spesific roles, and realm roles. Users can be assigned the role either via group membership or directly.

The keycloak service account needs to be assigned "view-users", "query-users" and "view-realm"

The change applies the filter to:

• SSO login
• Keycloak REST/mailpassword login
• Periodic Keycloak sync/import

It also adds the matching admin UI fields, OpenAPI schema entries, and English UI labels.

For periodic sync tasks the crontask log is updated with information on the filter.

Affected Containers

• php-fpm-mailcow
• nginx-mailcow

Did you run tests?

Yes.

What did you test?

• Ran PHP syntax lint for the changed PHP files.
• Tested local Keycloak role-filter behavior with Keycloak 26.6.1.
• Tested full user sync with:
  • realm roles
  • client roles
  • direct user role assignments
  • group-inherited role assignments
• Tested Keycloak login on a live system and verified that login is denied unless the user has the required role.
• Tested that disabling the role filter preserves the previous behavior.
• Tested configuring the role filter type and role name from the admin UI.

What were the final results? (Expected, got)

Expected:

• Users without the required role are excluded when the role filter is enabled.
• Users with the required role can log in and are included in sync/import.
• Existing behavior is unchanged when the role filter is disabled.

Got:

• PHP syntax lint passed.
• Realm-role filtering imported only users with the required realm role, including group-inherited roles.
• Client-role filtering imported only users with the required client role, including group-inherited roles.
• Disabled filtering imported all tested Keycloak users as before.
• Live Keycloak login required the configured role before access was approved.
• Periodic sync and user import worked with the role filter enabled.