Implementation Plan: Global Read-Only Admin Role for All Realms

Issue: #39616 - Global Read-Only Admin Role for All Realms (Including Future Realms)

Summary

This proposal introduces a new global admin role global-view-admin that grants read-only access to all existing and future realms. The feature will be opt-in via a feature flag to allow community members to enable it based on their security and operational requirements.

Problem Statement

Currently, Keycloak does not provide a mechanism to grant users read-only administrative access to all realms (current and future) without manual intervention. Organizations need this for:

• Centralized Audit and Monitoring: Security/audit teams need consistent read-only access across all realms
• Operational Efficiency: Manual role assignment for each new realm is error-prone and doesn't scale
• Consistency: Ensures audit users always have up-to-date access without manual updates

Current Workaround: Manually assign view-* roles for each realm's realm-management client, repeated for every new realm.

Proposed Solution

1. New Global Role: global-view-admin

Add a new role to the master realm that automatically grants view-only permissions across all realms.

Role Capabilities:

• View realm configuration
• View users
• View clients
• View events
• View identity providers
• View authorization settings
• View groups
• NO management, creation, update, or deletion capabilities

Scope:

• Applies to all existing realms at the time of role assignment
• Automatically extends to newly created realms
• Only available in the master realm

2. Feature Flag Implementation

Feature will be disabled by default and can be enabled via:

--features=global-readonly-admin
# or
--feature-global-readonly-admin=enabled

When disabled:

• The global-view-admin role will not be created during master realm setup
• Existing deployments with the role will see it as inactive/non-functional
• No automatic role grants will occur on realm creation

Technical Design

Role Overview

Master Realm
├── admin (existing global role)
├── create-realm (existing global role)
└── global-view-admin (NEW)
    └── Composite roles (auto-assigned on realm creation):
        ├── {realm-name}-realm (client) → view-realm
        ├── {realm-name}-realm (client) → view-users
        ├── {realm-name}-realm (client) → view-clients
        ├── {realm-name}-realm (client) → view-events
        ├── {realm-name}-realm (client) → view-identity-providers
        ├── {realm-name}-realm (client) → view-authorization
        ├── {realm-name}-realm (client) → query-users
        ├── {realm-name}-realm (client) → query-clients
        ├── {realm-name}-realm (client) → query-groups
        └── (Automatically extends to new realms)

Key Components to Modify

1. Feature Flag Definition

File: common/src/main/java/org/keycloak/common/Profile.java

Add new feature flag:

GLOBAL_READONLY_ADMIN("Global Read-Only Admin Role", Type.DISABLED_BY_DEFAULT)

Rationale for DISABLED_BY_DEFAULT:

• Security-conscious approach for enterprise deployments
• Allows community to opt-in after evaluating security implications
• Prevents unexpected permission changes in existing deployments
• Aligns with Keycloak's cautious approach to new admin features

2. Admin Role Constants

File: server-spi-private/src/main/java/org/keycloak/models/AdminRoles.java

Add new constant:

public static final String GLOBAL_VIEW_ADMIN = "global-view-admin";

public static final String[] ALL_VIEW_REALM_ROLES = {
    VIEW_REALM, VIEW_USERS, VIEW_CLIENTS, VIEW_EVENTS,
    VIEW_IDENTITY_PROVIDERS, VIEW_AUTHORIZATION,
    QUERY_USERS, QUERY_CLIENTS, QUERY_GROUPS
};

3. Master Realm Role Creation

File: services/src/main/java/org/keycloak/services/managers/RealmManager.java
Method: createMasterAdminManagement()

Changes:

1. During Role creation, if global-readonly feature is enabled, create new global-readonly-admin role
2. Creating the global-readonly-admin role role shall add each ALL_VIEW_REALM_ROLES as composite role

4. Automatic Role Grant on Realm Creation/Import

File: services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java
Method: grantPermissionsToRealmCreator()

Changes:

1. Grant view roles to global-view-admin role for newly created realm. This ensures that global-view-admin users automatically get access to new realms.

5. Permission Checking Logic

File: services/src/main/java/org/keycloak/services/resources/admin/fgap/MgmtPermissions.java

Current logic already handles composite roles correctly, so no changes needed. The method checks:

return identity.hasOneClientRole(clientId, adminRoles);

This will automatically include users with global-view-admin since it contains the view roles as composites.

Verify: No changes needed to individual permission checks like:

• canViewRealmDefault() - Already checks for VIEW_REALM role
• canViewUsersDefault() - Already checks for VIEW_USERS role
• Query methods - Already check for query roles

6. Database Migration (if needed)

For existing Keycloak installations upgrading with the feature enabled:

1. Create migration Script to run if master realm exists and role doesn't exist

7. Internationalization (i18n)

Files to Update:

• themes/src/main/resources/theme/base/admin/messages/admin-messages_en.properties
• Additional language files as appropriate

8. Testing Requirements

Unit Tests

Test cases:

1. Verify role is created in master realm when feature is enabled
2. Verify role is NOT created when feature is disabled
3. User with role can view existing realm details
4. User with role automatically gets view access to newly created realms
5. User with role cannot create, update, or delete realm resources
6. User can view users across all realms
7. User can view clients across all realms
8. User cannot create users in any realm
9. User cannot update users in any realm
10. User can query/search users across realms
11. Verify role contains correct composite roles
12. Existing realm is upgraded and role is properly initialized

Integration Tests

Test scenarios:

1. Create realm with feature enabled → verify global-view-admin users get access
2. Create realm with feature disabled → verify no automatic grants occur
3. Toggle feature flag → verify behavior changes appropriately
4. Multi-realm scenario → user with global-view-admin can access all realms read-only

Manual Test Scenarios

1. Fresh Installation:

   • Enable feature flag
   • Start Keycloak
   • Verify global-view-admin role exists in master realm
   • Assign to user
   • Create new realm
   • Verify user can view but not modify

2. Upgrade Scenario:

   • Existing Keycloak with multiple realms
   • Enable feature flag
   • Restart
   • Run migration
   • Assign role to user
   • Verify user can view all existing realms
   • Create new realm
   • Verify automatic access

3. Feature Disabled:

   • Disable feature flag
   • Verify role is not created
   • Verify no automatic grants occur

Security Considerations

1. Privilege Escalation Prevention

• Role is strictly read-only - no manage, create, update, or delete capabilities
• Cannot be used as stepping stone to gain higher privileges
• Does not include impersonation capabilities

2. Audit Trail

• All view operations by global-view-admin users should be logged in admin audit events
• Consider adding specific event types for global admin actions

3. Opt-In Model

• Feature disabled by default requires explicit enablement
• Organizations can evaluate security implications before enabling
• No unexpected behavior in existing deployments

4. Composite Role Safety

• Uses existing composite role mechanism (well-tested)
• Automatic cleanup when realm is deleted (existing Keycloak behavior)
• No orphaned permissions

5. Fine-Grained Authorization (V2) Compatibility

• Verify compatibility with ADMIN_FINE_GRAINED_AUTHZ_V2 feature
• Ensure authorization policies respect global-view-admin limitations
• Consider adding specific policies for global view access

Migration Strategy

For New Installations

1. Admin enables feature flag via configuration
2. Keycloak creates global-view-admin role during master realm setup
3. Admin assigns role to appropriate users
4. Users immediately have view access to all realms

For Existing Installations

1. Admin enables feature flag and restarts Keycloak
2. Database migration creates global-view-admin role in master realm
3. Migration script grants view roles for all existing realms to the new role
4. Admin assigns role to appropriate users
5. Users immediately have view access to all existing realms
6. Future realm creations automatically extend access

Rollback Plan

If feature needs to be disabled:

1. Disable feature flag
2. Restart Keycloak
3. Role remains in database but becomes non-functional
4. No automatic grants occur for new realms
5. Existing composite role mappings remain but are not enforced
6. Optional: Manual cleanup of role and composite mappings via admin console

Open Questions

1. Should global-view-admin have access to master realm itself?

Options:

• A) Yes - can view master realm configuration (consistent behavior)
• B) No - master realm is restricted to full admins only (more secure)

Recommendation: Option A - consistency and transparency are valuable for audit use cases. Master realm view access doesn't expose sensitive credentials.

2. Should the role name be customizable?

Options:

• A) Fixed as global-view-admin (simpler, consistent)
• B) Configurable via properties (flexible, but more complex)

Recommendation: Option A - Keep it simple. Organizations can create additional custom roles if needed.

3. Should there be a separate permission for viewing audit events?

Options:

• A) Include view-events in global-view-admin (complete read access)
• B) Separate role for audit event access (more granular control)

Recommendation: Option A - audit teams need complete visibility. Organizations requiring separation can use fine-grained authz v2.

Feedback and Iteration

This plan is open for community feedback. Key areas for input:

1. Feature flag default state (disabled by default vs. preview)
2. Role naming convention
3. Scope of view permissions (should anything be excluded?)
4. Migration strategy for existing deployments
5. Documentation completeness