Implementation Plan: Global Read-Only Admin (Issue: #39616) #46340

cgurtshaw · 2026-02-13T23:13:47Z

cgurtshaw
Feb 13, 2026

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:

During Role creation, if global-readonly feature is enabled, create new global-readonly-admin role
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:

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:

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:

Verify role is created in master realm when feature is enabled
Verify role is NOT created when feature is disabled
User with role can view existing realm details
User with role automatically gets view access to newly created realms
User with role cannot create, update, or delete realm resources
User can view users across all realms
User can view clients across all realms
User cannot create users in any realm
User cannot update users in any realm
User can query/search users across realms
Verify role contains correct composite roles
Existing realm is upgraded and role is properly initialized

Integration Tests

Test scenarios:

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

Manual Test Scenarios

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
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
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

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

For Existing Installations

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

Rollback Plan

If feature needs to be disabled:

Disable feature flag
Restart Keycloak
Role remains in database but becomes non-functional
No automatic grants occur for new realms
Existing composite role mappings remain but are not enforced
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:

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

VinodAnandan · 2026-02-16T02:11:09Z

VinodAnandan
Feb 16, 2026

@cgurtshaw Thank you very much for the detailed implementation plan, it’s greatly appreciated. Would you be interested in contributing this feature to Keycloak by collaborating with the Keycloak OAuth SIG? We believe your proposal would be a valuable feature, and we would be happy to support you through the contribution process.

You can find more details about the Keycloak OAuth SIG here: https://github.com/keycloak/keycloak-oauth-sig

2 replies

cgurtshaw Feb 17, 2026
Author

Happy to contribute. I also have several other engineers in my org who would be interested in contributing back to Keycloak. Please let us know if there is anything else not defined in the CONTRIBUTING.md that we should follow.

Shall I move this discussion to https://github.com/keycloak/keycloak-community/tree/main/design?

VinodAnandan

Feb 17, 2026

@cgurtshaw That’s great to hear. One of the key focuses of the Special Interest Group (SIG) is to encourage and support external contributions from both individuals and organisations. We currently have members participating in their individual capacity from several different organisations ( https://github.com/keycloak/keycloak-oauth-sig/blob/main/members.adoc ).

As a SIG, we have contributed a number of significant features, including FAPI, DPoP, OID4VCI, CIBA, JARM, PAR, Passkeys, etc.. We are actively working to foster further community contributions and to help promote community-driven features through the maturity stages, from experimental, to preview, and ultimately to supproted.

I believe the design link you mentioned may be outdated and no longer in use.

The SIG meets every Wednesday from 12:00 PM to 1:00 PM GMT. You can find more information here:
https://www.keycloak.org/community

https://zoom-lfx.platform.linuxfoundation.org/meetings/keycloak?view=week

We warmly welcome everyone to join and participate in the discussions, and we would very much look forward to your participation in an upcoming meeting.

Navigation Menu

Repository navigation

Implementation Plan: Global Read-Only Admin (Issue: #39616) #46340

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Implementation Plan: Global Read-Only Admin (Issue: #39616) #46340

Uh oh!

cgurtshaw Feb 13, 2026

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

Summary

Problem Statement

Proposed Solution

1. New Global Role: global-view-admin

2. Feature Flag Implementation

Technical Design

Role Overview

Key Components to Modify

1. Feature Flag Definition

2. Admin Role Constants

3. Master Realm Role Creation

4. Automatic Role Grant on Realm Creation/Import

5. Permission Checking Logic

6. Database Migration (if needed)

7. Internationalization (i18n)

8. Testing Requirements

Unit Tests

Integration Tests

Manual Test Scenarios

Security Considerations

1. Privilege Escalation Prevention

2. Audit Trail

3. Opt-In Model

4. Composite Role Safety

5. Fine-Grained Authorization (V2) Compatibility

Migration Strategy

For New Installations

For Existing Installations

Rollback Plan

Open Questions

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

2. Should the role name be customizable?

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

Feedback and Iteration

Replies: 1 comment · 2 replies

Uh oh!

VinodAnandan Feb 16, 2026

Uh oh!

cgurtshaw Feb 17, 2026 Author

Uh oh!

cgurtshaw
Feb 13, 2026

1. New Global Role: `global-view-admin`

Replies: 1 comment 2 replies

VinodAnandan
Feb 16, 2026

cgurtshaw Feb 17, 2026
Author