The modern landscape of cloud-native infrastructure demands a robust approach to identity management and system visibility. As organizations transition toward microservices architectures and Kubernetes-orchestrated environments, the complexity of managing individual user credentials for every disparate tool becomes unsustainable. This architectural challenge necessitates the implementation of Single Sign-On (SSO) mechanisms and centralized observability. The integration of Keycloak, an open-source identity provider, with Grafana, a premier visualization platform, represents a pinnacle of secure and scalable infrastructure management. This integration allows for the centralized enforcement of authentication and authorization policies via standard protocols such as OpenID Connect (OIDC), OAuth 2.0, and SAML, while simultaneously enabling the visualization of identity provider metrics through advanced dashboarding.
The Architectural Role of Keycloak in Identity Management
Keycloak serves as a foundational component in the identity and access management (IAM) ecosystem. It is an open-source identity provider designed to manage users, facilitate authentication, and handle complex authorization logic. The primary utility of Keycloak lies in its ability to act as a centralized hub that federates users from various upstream sources.
The capacity for user federation is one of Keyron's most critical features for enterprise and homelab environments alike. It can ingest and synchronize user identities from legacy and modern directory services, including:
- Active Directory (AD)
- Lightweight Directory Access Protocol (LDAP)
- External Databases
By establishing an LDAP federation, an administrator can bridge a local domain, such as rhmlab.local, into the Keycloak realm. This creates a unified identity plane where users existing in a corporate or private directory are automatically recognized within the Keycloak environment. A significant operational detail during this configuration is the behavior of the user interface; upon the initial configuration of LDAP federation, the Keycloak user list may appear entirely empty. This is not an indication of failure but a consequence of how the synchronization is indexed. To verify the presence of federated users, an explicit search operation must be performed within the Keycloak admin console.
Beyond federation, Keycloak operates using the concept of Realms. A Realm is an isolated space within Keycloak that manages its own set of users, clients, and roles. For instance, in a dedicated laboratory or homelab setup, a realm named rhmlab can be created to house specific applications. Within this realm, administrators can define "Clients"—which are the applications (like Grafana) requesting authentication—and "Roles," which define what a user is permitted to do once they have been authenticated.
Implementing Single Sign-On via OAuth2 and OpenID Connect
Single Sign-On (SSO) is the process of allowing a user to authenticate once and gain access to multiple independent software systems without being prompted for credentials again. When integrating Keycloak with Grafana, the underlying mechanism is typically OAuth 2.0 or OpenID Connect. This integration allows Grafana to delegate the responsibility of verifying user identities to Keycloak.
The configuration of this integration requires precise coordination between the Keycloak client definition and the Grafana server configuration. A critical realization for many engineers is that official documentation for both Grafana and Keycloak can occasionally become outdated, particularly as Keycloak evolves its features—such as the introduction of automated provisioning in version v26.0.0 via bootstrapping confidential clients.
Keycloak Client Configuration via Infrastructure as Code
In modern DevOps workflows, configuring Keycloak clients manually through the UI is discouraged in favor of Infrastructure as Code (IaC). Using tools like OpenTofu, administrators can define the keycloak_openid_client resource to ensure repeatable and version-controlled deployments. A properly configured client for Grafana must include specific parameters to ensure the OAuth handshake completes successfully.
The following configuration block demonstrates a robust implementation using OpenTofu:
hcl
resource "keycloak_openid_client" "grafana" {
realm_id = keycloak_realm.homelab.id
client_id = "grafana"
name = "Grafana Client"
enabled = true
access_type = "CONFIDENTIAL"
client_secret = "yourclientsecret"
standard_flow_enabled = true
implicit_flow_enabled = false
direct_access_grants_enabled = true
use_refresh_tokens = true
root_url = "https://grafana.lan"
admin_url = "https://grafana.lan"
base_url = "/applications"
valid_redirect_uris = [
"https://grafana.lan/login/generic_oauth"
]
web_origins = [
"https://grafana.lan"
]
valid_post_logout_redirect_uris = [
"https://grafana and .lan/login"
]
}
The impact of misconfiguring the valid_redirect_uris cannot be overstated. If the URI provided in the Keycloak client does not exactly match the callback URL used by Grafana, the authentication flow will terminate with an error, preventing any user from logging in. This highlights the necessity of the root_url parameter, which must be correctly set to ensure that the callback URL generated during the OAuth request is accurate.
Furthermore, the scopes requested by the client define the extent of the data shared between the identity provider and the service provider. To ensure a complete user profile is available in Grafana, the default scopes must be explicitly defined:
hcl
resource "keycloak_openid_client_default_scopes" "grafana_client_default_scopes" {
depends_on = [keycloak_openid_client_optional_scopes.grafana_client_optional_scopes]
realm_id = keycloak_realm.homelab.id
client_id = keycloak_openid_client.grafana.id
default_scopes = [
"email",
"offline_access",
"profile",
"roles",
]
}
By including email, profile, and roles, the Grafana instance receives the necessary metadata to identify the user and assign them the correct permission levels.
Role Mapping and Authorization Granularity
Authentication proves who the user is, but authorization determines what they can do. In the context of the Grafana-Keycloak integration, this is achieved through role mapping. Grafana recognizes a specific hierarchy of internal roles:
- GrafanaAdmin: The highest level of privilege, allowing full system configuration.
- Admin: Provides access to organization-level management and dashboard editing.
and - Editor: Allows for the creation and modification of dashboards and folders.
- Viewer: Provides read-only access to existing dashboards.
To implement this, administrators must configure a client role mapper in Keycloak. Instead of relying on complex resource_access structures, a more direct approach is to map Keycloak client roles directly to these Grafana roles. This simplifies the mapping logic and reduces the likelihood of configuration errors.
The following OpenTofu snippet illustrates how to define a specific realm role that will eventually be mapped to a Grafana permission:
hcl
resource "keycloak_role" "realm_homelab_role_grafanaadmin" {
realm_id = keycloak_realm.homelab.id
client_id = keycloak_openid_client.grafana.id
name = "grafanaadmin"
description = "Grafana Super Admin Role"
}
This structure allows for a seamless transition where a user assigned the grafanaadmin role in Keycloak is automatically granted GrafanaAdmin privileges in Grafana upon login.
Observability: Visualizing Keycloak Metrics in Grafana
An essential component of maintaining a healthy identity infrastructure is observability. Keycloak, particularly versions running on the Quarkus framework, provides a wealth of micro-profile metrics that can be exported and visualized. This allows administrators to monitor HTTP request latency, authentication success/failure rates, and JVM performance.
The integration pipeline for these metrics typically follows a standard observability pattern: Keycloak exports metrics, a Prometheus instance scrapes these metrics, and Grafana queries Prometheus to render visual dashboards.
Keycloak Dashboard Components and Evolution
The community-driven keycloak-grafana-dashboard repository provides pre-built JSON dashboards that can be imported into Grafana. These dashboards are designed to visualize Quarkus MicroProfile metrics, providing deep insights into the Keycloak deployment.
The evolution of these dashboards demonstrates the ongoing need to adapt to Keycloak's architectural shifts:
| Version | Primary Modification/Focus |
|---|---|
| Version 1 | Initial release for Quarkus-based Keycloak metrics |
| Version 2 | Implementation of time-series graph type switches |
| Version 3 | Adjustments for Keycloak version 25 metrics compatibility |
| Version 4 | Optimization of the dashboard JSON file size |
| Version 5 | Refactoring of Grafana data source variable names |
| Version 6 | Finalization of the dashboard naming convention |
To deploy these dashboards, the process involves cloning the repository and importing the dashboard.json file:
bash
git clone -b BRANCH_FROM_STEP_1 https://github.com/keycloak/keycloak-grafana-dashboard.git
For high-fidelity visualizations, such as HTTP request latency heatmaps, it is imperative to ensure that histograms are enabled within the Keycloak configuration. This is achieved by setting the following property to true:
http-metrics-histograms-enabled = true
Without this setting, the dashboard will lack the granular data necessary to render heatmaps, significantly reducing the utility of the observability stack.
Operational Considerations and Troubleshooting
Successful integration requires addressing several edge-case scenarios that can disrupt the user experience. One such scenario involves user identity collisions. If an organization uses multiple authentication providers (e.g., Keycloak for internal users and Grafana.com for external users), and those providers share the same email address, Grafana may struggle to resolve the correct identity. In such cases, specialized configuration is required to ensure that the email address is mapped to the correct internal UID.
Furthermore, the user experience within the Grafana UI changes dynamically based on the authenticated role. This is not merely a matter of interface aesthetics but a fundamental security control.
The differentiation in user experience is categorized as follows:
- Admin Role: Access to comprehensive menus, including server configuration, data source management, and user permissions.
- Viewer Role: Access is strictly limited to viewing existing dashboards, with no ability to edit or create new content.
- Profile Management: Users can navigate to their profile via the dashboard icon, but the visibility of profile details (such as email or custom attributes) is restricted by the authenticated role's permissions.
When troubleshooting the login flow, the "Sign in with Keycloak" button is the primary entry point. If this button fails to redirect the user to the Keycloak login page, the issue almost certainly resides in the root_url or valid_redirect_uris configuration within the Keycloak client settings or the Grafana [server] configuration.
Conclusion: The Integrated Ecosystem
The integration of Keycloak and Grafana transcends simple authentication; it represents the creation of a cohesive, secure, and observable ecosystem. By leveraging Keycloak as a centralized authority, organizations can implement a robust Single Sign-On strategy that scales with their infrastructure. The use of Infrastructure as Code to manage Keycloak clients ensures that security policies are reproducible and resistant to human error. Simultaneously, the deployment of specialized Grafana dashboards transforms raw, ephemeral metrics into actionable intelligence, allowing for proactive management of the identity layer. This synergy between identity and observability is a prerequisite for any mature, production-grade Kubernetes or cloud-native deployment, providing the visibility required to maintain security and the automation required to maintain scale.