Add an IdP config option to control IdP admin role escalation - #52652

Adds a per-IdP allowAdminRoleMapping option to control administrative role escalation through identity-provider mappers.

Changes:

• Adds model, API, UI, and translation support.
• Enforces mapper restrictions during administration and broker login.
• Adds RBAC tests for escalation scenarios.

Suppressed comments (3)

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java:534

• AdminRoles.isAdminRole only recognizes a role whose own name is in ALL_ROLES; it does not recognize a custom composite containing, for example, realm-management.manage-users. With the flag disabled, a non-realm-admin can therefore create or update a mapper for that composite and receive the admin child transitively. Use the composite-aware AdminRoles.isAdminRoleOrComposite predicate here.

        RoleModel role = KeycloakModelUtils.getRoleFromString(session, realm, roleName);
        if (role == null || !AdminRoles.isAdminRole(role)) {
            return;

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java:524

• This early return lets a realm administrator create an admin-role mapper while the setting is disabled, but isAdminRoleGrantAllowed later rejects that mapper based only on the IdP flag. The API can therefore report a successful create/update for a mapper that never grants its configured role during broker login; either require the setting for realm-admin-created mappers too or persist an explicit trusted exemption that the runtime check honors.

        if (auth.hasOneAdminRole(AdminRoles.MANAGE_REALM)) {
            return;

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java:527

• IdentityProviderMapperRepresentation permits a null config and RepresentationToModel.removeEmptyString preserves it as null. Because every add/update mapper request now reaches this method, .get can throw a NullPointerException and return 500 for such a request; guard the null config before reading roleName.

        String roleName = mapperModel.getConfig().get(ConfigConstants.ROLE);

• Files reviewed: 11/11 changed files
• Comments generated: 3
• Review effort level: Lite (auto)

Suppressed comments (3)

server-spi-private/src/main/java/org/keycloak/broker/provider/AbstractIdentityProviderMapper.java:109

• This direct-role check misses composite roles that contain an admin role. Because user role checks resolve composites, a mapper for a custom composite containing a realm-management role can still grant admin privileges while this setting is disabled; use the composite-aware AdminRoles.isAdminRoleOrComposite predicate here and in the admin endpoint validation.

        if (role == null || !AdminRoles.isAdminRole(role)) {

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java:347

• This validation only inspects config.role. A user with manage-identity-providers can instead add a hardcoded or claim-to-group mapper that joins users to a group carrying a built-in admin role; DefaultPermissions.isAdminUser resolves group-inherited admin roles, so this still escalates while the setting is disabled. Extend the protection to admin-bearing target groups (including inherited/composite roles) and enforce it when the group mapper is applied.

        IdentityProviderMapperModel model = RepresentationToModel.toModel(mapper);
        validateMapperAdminRoleMapping(model);

services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java:293

• When a realm administrator creates an IdP without this key, this branch is skipped and isAllowAdminRoleMapping() defaults to true, so the new IdP is enabled by default through the REST API despite the new help text saying it is disabled by default. Track whether the key was supplied and persist false for omitted values while retaining explicit values.

            if (!auth.hasOneAdminRole(AdminRoles.MANAGE_REALM)) {
                if (identityProvider.getConfig().containsKey(IdentityProviderModel.ALLOW_ADMIN_ROLE_MAPPING)
                        && identityProvider.isAllowAdminRoleMapping()) {
                    throw ErrorResponse.error("Only users with '" + AdminRoles.MANAGE_REALM
                            + "' role can enable the '" + IdentityProviderModel.ALLOW_ADMIN_ROLE_MAPPING + "' setting.",
                            Response.Status.FORBIDDEN);
                }
                identityProvider.setAllowAdminRoleMapping(false);
            }

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Lite (auto)

Suppressed comments (3)

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java:529

• This validator only inspects the role property, so group mappers are always accepted. A manager can map users into a group (or child group) carrying an admin role and bypass the new switch; validate ConfigConstants.GROUP with AdminRoles.groupHasAdminRoles and enforce the same rule in the OIDC/SAML group mapper runtime paths.

        String roleName = mapperModel.getConfig().get(ConfigConstants.ROLE);
        if (roleName == null || roleName.trim().isEmpty()) {
            return;

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java:534

• A custom composite role containing realm-management.realm-admin is not itself recognized by isAdminRole, so it can be submitted while this switch is disabled and still confer its admin subroles. Use the composite-aware helper already provided by AdminRoles.

        RoleModel role = KeycloakModelUtils.getRoleFromString(session, realm, roleName);
        if (role == null || !AdminRoles.isAdminRole(role)) {
            return;

server-spi-private/src/main/java/org/keycloak/broker/provider/AbstractIdentityProviderMapper.java:110

• The runtime guard also treats a composite containing admin roles as non-admin, so pre-existing/imported mappers can still grant such a composite while the switch is disabled. Use the composite-aware check here as well.

    protected static boolean isAdminRoleGrantAllowed(KeycloakSession session, RealmModel realm, RoleModel role, IdentityProviderMapperModel mapperModel) {
        if (role == null || !AdminRoles.isAdminRole(role)) {
            return true;

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Balanced

Suppressed comments (1)

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java:410

• The mapper fetched using the path ID is discarded, while validation uses the path IdP and persistence uses the body-controlled ID and alias. This permits updating a mapper belonging to a disabled IdP through an enabled IdP's URL; verify ownership and make the path ID/alias authoritative before validation.

        IdentityProviderMapperModel model = session.identityProviders().getMapperById(id);
        if (model == null) throw new NotFoundException("Model not found");
        model = RepresentationToModel.toModel(rep);
        validateMapperAdminRoleMapping(model);

• Files reviewed: 13/13 changed files
• Comments generated: 5
• Review effort level: Balanced

• Files reviewed: 13/13 changed files
• Comments generated: 2
• Review effort level: Balanced