Authentication & Identity
Relevant source files
The following files were used as context for generating this wiki page:
- pkg/services/auth/auth.go
- pkg/services/login/loginattempt/login_attempt.go
- pkg/services/ldap/ldap.go
- contribute/architecture/k8s-inspired-backend-arch.md
- contribute/backend/recommended-practices.md
- public/app/features/alerting/unified/AGENTS.md
- contribute/backend/instrumentation.md
- contribute/developer-guide.md
The Authentication & Identity system in Grafana manages user verification, session persistence, and authorization across both legacy and modern architectural components. It ensures that requests to the Grafana API—whether through the UI or direct programmatic calls—are properly attributed to a user or service account and that the requester has the appropriate permissions to perform actions on specific resources.
The system is currently undergoing a transition from implicit organization-based context found in Legacy APIs to an explicit, namespace-oriented resource model inspired by Kubernetes. This transformation affects how identity is propagated through the backend layers and how authorization is checked at the resource level.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:1-15, contribute/architecture/k8s-inspired-backend-arch.md:120-125
Authentication Mechanisms
Grafana supports multiple methods for identifying a requester. The primary mechanisms include session-based authentication for interactive users, API keys, and Service Account tokens for programmatic access.
Legacy vs. Resource API Auth
The authentication flow differs significantly between the two API styles:
- Legacy APIs: Rely on implicit organization context. The identity is typically determined by an active session or an API key, where the "Org context" is derived from the session state rather than the URL.
- Resource APIs: Follow a Kubernetes-like model where the namespace in the URL path (e.g.,
/apis/.../namespaces/<namespace>/...) maps to a Grafana Organization ID or Cloud Stack ID. This provides an explicit scoping for identity and permissions.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:18-35
Default Credentials and Environment
For local development, Grafana initializes with default credentials. Users are required to change these upon first login to establish a secure identity.
| User | Default Password | Action |
|---|---|---|
admin | admin | Password change required on first login |
Sources: contribute/developer-guide.md:144-150
Access Control (RBAC)
Authorization in Grafana is governed by a Role-Based Access Control (RBAC) system. RBAC is the standard authorization model for Grafana OSS and Enterprise, replacing older fixed-role systems with a more granular permission-based approach.
Frontend Authorization Checking
In the frontend, permissions are evaluated using specialized hooks that check if the current user possesses the required action permissions.
The useAbilities hook is the primary interface for frontend permission checks, returning a can function that accepts specific access control actions.
Sources: public/app/features/alerting/unified/AGENTS.md:275-285
Backend Identity and Context Propagation
Identity information is passed through the backend layers using context.Context. This context provides the full lifecycle for an API request, including metadata about the authenticated user.
Key practices for backend identity propagation:
- Propagation: The
context.Contextmust be passed from the API request through the service, bus, and database layers. - User Information: The context contains the authenticated user's ID, Org ID, and associated permissions.
- Tracing: Contextual logging and distributed tracing use this context to correlate actions with specific identities via a
traceID.
Sources: contribute/backend/recommended-practices.md:160-175, contribute/backend/instrumentation.md:75-85
Security and Identity Best Practices
Maintaining the integrity of the Identity system requires strict instrumentation and input handling rules to prevent the exposure of sensitive credentials.
Sanitization and Logging
Loggers must be careful not to parameterize sensitive information. User-provided input or structs that might contain secrets must be validated and sanitized before being recorded in system logs.
| Component | Responsibility |
|---|---|
| Log Keys | Use camelCase identifiers (e.g., remoteAddr). |
| Sanitization | Remove secrets/credentials from log messages and metadata. |
| User Input | Validate all data originating from user sessions before logging. |
Sources: contribute/backend/instrumentation.md:25-35, contribute/backend/instrumentation.md:46-52
Resource History and Auditing
The Resource API architecture introduces a resource_history table within the unified storage layer. Every modification to a resource is tagged with a resourceVersion, providing an audit trail of which identity modified which resource and when. This is used for optimistic concurrency control to prevent conflicting updates between different users.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:65-75
Authentication Flow in Resource APIs
The following sequence illustrates how a request is handled when interacting with the Resource API, contrasting it with internal service interactions.
In this flow, the API Handlers are responsible for translating the authenticated namespace into a concrete Organization ID used by the Unified Storage and database layers.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:130-150
Summary
Authentication and Identity in Grafana serve as the foundation for secure multi-tenancy. By utilizing context.Context for propagation and RBAC for enforcement, the system maintains a consistent security posture. The ongoing shift toward Resource APIs further standardizes identity handling by aligning with industry-standard patterns for namespacing and versioning.