Grafana JWT authentication setup

Grafana JWT authentication lets your application sign users straight into Grafana

Your application already authenticates users, and you want them to open Grafana dashboards without a second login. Grafana's JWT login makes this possible by accepting a signed token issued by that application and creating or matching a Grafana user from it. The Grafana authentication docs list JWT as supported in all editions, so this pattern does not depend on Grafana Enterprise. The work is in the details: how Grafana verifies the signature against your key set, which claims must be present, whether users are created automatically, and how roles and organizations are assigned.

This page covers each of those decisions in turn: JWKS verification, the required claims, auto sign-up, role and org mapping, and the fact that JWT login has no refresh token support. The last point matters most for portals. A token that expires ends the Grafana session, so your application must decide how long tokens live, how users are sent back through your own login when they expire, and what happens to a dashboard embed that is open for longer than a token lifetime. Confirm these behaviors against the Grafana version you plan to run before you design the token flow.

Start by listing the users who need Grafana access and the roles each should hold, then check whether your application already carries that information in its tokens. If it does not, the mapping will need a change in the application before Grafana can use it. Confirm with your own security team how signing keys will be published and rotated, since a verification setup that cannot follow key rotation will fail for every user at once. Treat the Grafana host as a trust boundary: anyone who can obtain a validly signed token can sign in as that user, so token issuance and key handling deserve the same review as your other single sign-on paths.

What you need in place before configuring Grafana JWT login

JWT login hands Grafana's sign-in to a token issued by your application, so the work depends on three sides being ready: a supported Grafana build on a production-grade database, an issuer that can sign tokens and publish verification keys, and a network path and TLS setup that let Grafana trust them. Check these before touching grafana.ini, because most failed rollouts trace back to one of them.

A supported Grafana release

Pick a current Grafana minor release and plan to move with the cadence rather than freezing on an old build. Grafana's upgrade guidance describes major releases once a year, minor releases every other month, and patch releases at least monthly, with each minor release supported for 9 months. Confirm the JWT options in the version you choose against the authentication docs, and record the exact version in your change ticket so the configuration is tested against the build you run in production.

Production database backend

Grafana defaults to SQLite, which the installation docs say does not scale for production. Plan for MySQL 8.0 or later, or PostgreSQL 12 or later, before you create users through JWT, because the users, orgs and auth tokens Grafana creates on first login are stored there. Moving databases after users exist adds migration work, so decide the backend and its backup regime first.

Issuer that signs and publishes keys

Your portal or application must sign the tokens with a private key and expose the matching public keys, normally as a JWKS document at a stable URL. Confirm that the issuer can rotate keys without breaking verification, that it sets the claims you plan to require (such as the login and email values Grafana reads), and that it can issue short-lived tokens. Remember that Grafana does not refresh JWT sessions, so the issuer must handle reissue at the point where a user returns to Grafana.

Network path to the key source

Grafana must reach the JWKS endpoint, or the key file if you verify with a static key, from every node that serves logins. Check egress rules, proxies, DNS resolution and firewall policy in both directions for the Grafana servers, including any high availability nodes behind a load balancer. For air-gapped or restricted networks, agree with the security team how keys will be published and refreshed, since a blocked endpoint will fail every sign-in.

TLS on both sides

Serve Grafana over HTTPS and confirm the issuer's JWKS endpoint presents a certificate that the Grafana servers trust, including any internal certificate authority. Use secure and SameSite cookies as the hardening guidance recommends, since embedded dashboards and portal redirects depend on cookie behavior across domains. Document which hostnames and certificate chains are in scope so a renewal does not silently break sign-in.

Separate non-production Grafana

Build a test instance with the same Grafana version, database engine and JWT settings as production, and point it at a test issuer with its own keys. Use it to confirm required claims, role and org mapping, and the behavior when a token is expired or unsigned, before any production users see the change. Keep test users, dashboards and data sources separate from production, and plan how the test configuration will be promoted into your provisioning or deployment code.

Grafana JWT authentication setup sequence

This sequence takes a JWT login from an agreed token contract to a tested Grafana configuration, so that signed tokens from your application sign users in with the roles and organizations you intend. Each step closes with a check you can run before the next one starts.

Agree the token contract with the application owner
Before touching Grafana, the team that owns the portal or embedding application and the Grafana owner agree in writing on the token contract: the signing algorithm, the issuer and audience values, the key ID scheme, the expiry the application will set, which claims every token carries, and how user email, login and role information are represented. Confirm that the application can rotate its signing keys and publish them at a JWKS endpoint that Grafana can reach. The step is done when both owners have signed off the contract and the application team can produce a sample token that matches it. Keep the contract in version control so later changes are reviewed.
Enable JWT login and set the key source
In the Grafana authentication configuration, enable the JWT login method and point it at the key source named in the contract, which is normally a JWKS URL for public-key verification. Set the expected issuer, audience and header or cookie location the application uses to send the token. Grafana does not support refresh tokens for this flow, so plan for the application to issue short-lived tokens and reauthenticate users when they expire. Exact configuration keys change between releases, so confirm each key name against the configure authentication documentation for the Grafana version you run. The step is done when Grafana starts cleanly with the setting enabled and the JWKS endpoint is reachable from the Grafana host.
Define the required claims
List the claims Grafana must find in every token and decide which are mandatory for login. At minimum, the login identifier and an email address are typically required, and the team decides whether a name, role claim or organization claim must also be present. Document what happens when a claim is absent, since a token that verifies but lacks a required claim should be refused rather than accepted with defaults. Keep the list short so the application team can produce it reliably. The step is done when the claim list appears in the contract and a test token missing one required claim is rejected by Grafana with no session created.
Decide whether auto sign-up is needed
Auto sign-up creates a Grafana user the first time a valid token arrives for an unknown identity. Turn it on only if the portal is the intended source of accounts, and leave it off if users must already exist in Grafana. When it is off, a valid token for an unknown user should fail with a clear message. Record the decision and the reason in the contract, because it determines who can appear in your Grafana instance. The step is done when a token for a user who does not yet exist either creates the account, as intended, or is refused, and the result matches the decision recorded.
Configure role and organization mapping
Map the role and organization claims in the token to Grafana roles and organizations. Use the mapping options the configure authentication documentation lists for your release, and confirm the claim path syntax against the version you run. Set a default role for users whose token carries no role claim, and keep it at the minimum your dashboards allow. Test each mapping with a token for a user in each intended role and organization. The step is done when each test token lands the user in the expected organization with the expected role, and a token with an unrecognized role value falls back to the default instead of gaining more access.
Test with signed tokens in staging
Run the full test set in a staging Grafana that uses the same configuration as production, with its own JWKS endpoint or test key pair. Include at least three tokens: one valid token that should log in, one signed with an unknown key or with an altered signature that must be rejected, and one valid token with a required claim removed that must also be rejected. Add an expired token, a token with the wrong audience or issuer, and a token for a user in each mapped role. Record the outcome of each case. The step is done when every case produces the outcome in the contract and the logs show the expected accept or reject decision.
Confirm production readiness and rotation
Before production, confirm the JWKS endpoint availability for the Grafana host, the key rotation procedure, and what happens when the application issues tokens with a new key ID. Verify that the production configuration matches the staging configuration except for the endpoints and secrets. Agree who owns key rotation and the process for changing the configuration on a Grafana upgrade, because keys and option names can change between releases. The step is done when the rotation procedure has been rehearsed in staging and both owners have signed the production change.

How Grafana decides whether to trust a token

Grafana accepts a JWT as a login only after it passes a set of checks, and the most important one is signature verification. Grafana fetches the public keys that your application publishes in a JWKS (JSON Web Key Set) document and uses the key that matches the token's key identifier to confirm the token was signed by your application and was not altered. Beyond the signature, Grafana checks that the token has not expired, that its issuer and audience match what you configured, and that the claims Grafana needs, such as the login and email, are present. Confirm the exact checks, the option names and the claim requirements in the Grafana authentication documentation for the version you deploy, because these settings differ between releases and this page does not reproduce them. Test each rejection path, including a token with a bad signature, an expired token, a wrong audience and a missing claim, before any user reaches the portal.

Key rotation is a planning item for the application team, not a Grafana setting you can leave until later. Your application signs tokens with a private key and publishes the matching public key in its JWKS. When you retire an old key, any token signed with it will fail verification in Grafana, so the new key must be published and picked up by Grafana before the application starts signing with it, and the old key must stay published until tokens signed with it have expired. Agree on the overlap window, the process for publishing a new key, and who owns the change before go-live. Also confirm how often and how Grafana refreshes the key set, because a long cache can delay the rotation you expect.

Because Grafana does not support refresh tokens for JWT logins, the lifetime you give each token is also a security decision. A short lifetime limits how long a stolen token is useful, but a user whose session ends will be sent back to your application to obtain a new token. Decide the lifetime with the portal's session policy in mind, and document who is responsible for issuing fresh tokens and for revoking access when a user leaves. This choice belongs in the written scope, because it affects both the application code and the operational runbook.

Which token claims map to which Grafana user attributes

This table lists the identity fields your application should put in its JWT and the Grafana user, login, role and organization settings each one feeds. Read the required column first, since a missing email claim blocks user creation. Confirm every claim and setting name against the Grafana authentication docs before you build the token issuer.

Identity field	Grafana setting it populates	Required	Notes for the build
Subject (sub)	Unique identifier used to match an existing Grafana user on repeat logins	Yes	Must be stable per user. Changing it creates a second Grafana account for the same person.
Login or username	Grafana login name for the user	Confirm	Name the claim your application issues and confirm in the docs whether Grafana reads it or derives the login from email.
Email	Email address stored on the user, required for user creation	Yes	Without this claim Grafana cannot create the account on first sign-in, so treat it as a hard requirement in the token.
Display name	Name shown in the Grafana user profile	No	Optional. Useful for audit trails and shared dashboard ownership views.
Role claim	Organization role (for example Viewer, Editor or Admin) via a role path expression	Confirm	Set the claim path in the JWT role setting. Roles must use the exact values Grafana expects, so check the documented role names.
Organization claim	Organization the user is placed into, through org mapping	Confirm	Needed only for multi-org setups. Confirm the claim name and whether the value must match an existing org name or ID.
Issuer and audience (iss, aud)	Checked during token verification, not stored on the user	Yes	Grafana validates these against your configured issuer and expected audience. A mismatch rejects the login.
Expiry (exp)	Token lifetime check at login only	Yes	Grafana does not support refresh tokens, so your application must issue a new token when the session needs to continue.

Portal link, embedded panel or full Grafana access: which pattern fits

Users click a link in your portal, the application passes a signed JWT to Grafana, and the user lands in the full Grafana interface. They see Grafana navigation, search and every dashboard their role and organization allow, so the application controls the sign-in moment more than what the user sees afterward. This is the simplest pattern to explain and to test.

User experience: users move between your portal and Grafana as a normal Grafana session, with the standard menu and folder tree.
Claims and roles: the token needs a stable subject, an email claim and a role claim that maps to a Grafana role in the target organization. Confirm the exact claim names and mapping settings in the authentication docs before you write the mapping.
Cookie considerations: the session lives as a browser cookie on the Grafana domain. If the portal and Grafana sit on different sites, confirm the secure and SameSite settings against the hardening guidance.
Operational risk: a broad role claim gives every portal user the same reach across dashboards, so limit organization membership to what each audience needs.

Before launch, check which dashboards and data sources a Viewer can open, and test the link from a fresh browser session.

Security controls for JWT login into Grafana

A JWT login path turns the identity system of another application into Grafana's front door, so the trust decisions sit outside Grafana's own login screen. The controls below cover which tokens Grafana accepts, how long they live, how new accounts appear, and how the browser session and embedded dashboards are protected.

Restrict trusted keys and issuers

Grafana verifies each token against the key set at the configured JWKS endpoint, and the issuer and audience settings decide which tokens are even considered. Use an HTTPS JWKS URL you control, confirm the expected iss and aud values with the application team, and reject any token whose signing key or issuer is not on that list. Ask who can rotate the signing keys and how a compromised key would be removed from the endpoint.

Plan token lifetimes without refresh

Grafana's JWT login does not support refresh tokens, so the application must issue a new token before the Grafana session would otherwise end. Short token lifetimes limit the window in which a stolen token is useful, while very short lifetimes force frequent re-login for analysts on long shifts. Agree the lifetime with the application owner, test what happens when a token expires mid-session, and document the expected behavior for users.

Enforce secure and SameSite cookies

The security hardening guidance recommends secure cookies so session cookies only travel over HTTPS, and SameSite settings that limit cross-site sending of those cookies. Embedding Grafana in a portal changes which cookie rules apply, so test sign-in from the portal origin in each target browser. Confirm the cookie settings in your Grafana configuration match the hardening guidance and that the portal and Grafana share a sound HTTPS setup.

Set a Content Security Policy for embeds

When dashboards appear inside a portal, the portal's origin must be allowed to frame Grafana, and the Content Security Policy must name only the origins that need it. A permissive frame policy lets any site embed your dashboards, while an overly strict one breaks the embed silently. Define the allowed frame ancestors and script sources explicitly, then test each embedded page after every Grafana upgrade.

Limit auto sign-up and admin claims

Auto sign-up creates a Grafana user the first time a valid token arrives, so any token the trusted issuer signs can create an account. Keep auto sign-up off unless the portal is the only way in, and map roles only from claims the issuer controls. Do not let token claims grant server administrator rights, and review which organizations a new account can join by default before go-live.

Lock Grafana to token paths

If users can still reach Grafana directly, they can bypass the portal and sign in through other methods, or send crafted requests to the login path. Restrict network access so only the portal and administrators reach the Grafana URL, disable login methods you do not intend to use, and confirm that unauthenticated requests cannot reach dashboards or the metrics endpoint. Test the lockdown from outside the approved network.

Why JWT logins to Grafana fail and how to fix them

This table lists the failures teams most often hit when a portal token is accepted as a Grafana login, with the likely cause and the fix for each. Read it while testing a new JWT setup or when users report a login that does not work, and check every setting name and log message against the Grafana version you run.

Failure	Likely cause	Fix
Signature rejected	The public key in the JWKS endpoint does not match the key that signed the token, often after the application rotated its signing key or Grafana cached an old key set	Confirm the key ID (kid) in the token header appears in the JWKS URL configured for Grafana. Publish the new key before switching signing, then restart or wait out the cache. Confirm the exact log message for the target version.
Token expired before login	The token lifetime is shorter than the time between issuing the token and the user's browser reaching Grafana, such as a redirect through several hops	Shorten the gap by redirecting immediately after issuing the token. Set the expiry in the portal with enough margin for the redirect, and confirm the clock skew allowed by your Grafana version.
Missing email or subject claim	The portal token omits the claim Grafana reads for the login name or email, or uses a different claim name than the configured one	Confirm the claim names in the Grafana authentication settings against the token your portal issues. Add the missing claim in the portal and decode a sample token to verify it before rollout.
User not created	Auto sign-up is disabled, so Grafana rejects a valid token for a user who has no existing account	Enable automatic sign-up in the JWT section of the authentication settings if policy allows it. Otherwise pre-create the user. Confirm the setting name in your version's configuration reference.
Wrong role or organization	The role or org claim is missing, misspelled, or mapped to a default role, so users land with more or fewer rights than intended	Verify the role claim path in a decoded token, then test each portal group with a sample account. Confirm the role mapping and org mapping settings for your version and review existing users after each change.
Session ends without refresh	Grafana's JWT login does not issue or renew refresh tokens, so the session lasts only as long as the Grafana session and the portal token allows	Plan for users to sign in again through the portal when the session ends. Design the portal so the link to Grafana issues a fresh token on each visit, and confirm current session lifetime settings with Grafana documentation.

Questions teams ask before building Grafana JWT login

Is JWT login available in the open-source edition of Grafana?

Yes. According to the Grafana authentication docs, all editions support JWT, along with LDAP, generic OAuth, Entra ID, Okta, GitHub, GitLab, Google OAuth and auth proxy. What requires Grafana Enterprise is a different set of features, including SAML, team sync, active sync and SCIM provisioning. JWT therefore does not need to be bought as a separate license, but the features your identity team expects, such as group-based team membership, may still depend on the edition. Confirm the exact configuration keys and behavior against the docs for the Grafana version you run, since the supported options can change between releases.

What drives the cost of building Grafana JWT login?

The cost comes from the people doing the work and the decisions they have to make, not from the Grafana configuration itself. The largest components are usually the design of the token contract with your application team, the verification setup for the signing keys, testing of role and organization mapping across user types, and the operational handoff. Cost goes up when token claims are inconsistent, when several portals issue tokens with different rules, or when you need evidence for an audit. It goes down when claims are already defined and one application is in scope. A written quote should list each of these as a line item, state what is one-time and what recurs, and name who maintains key rotation afterward.

How long does a JWT login project usually take?

Duration depends on how much of the design already exists. A single portal with settled claims and an existing Grafana instance moves much faster than a case with several issuers, multiple organizations and undefined role rules. The main variables are the state of the issuing application, whether a JWKS endpoint already exists, how many organizations and roles must be mapped, and how long user acceptance testing takes with real accounts. No duration is set by the product itself, so ask for a timeline built from the written scope and confirm each dependency with your application owners before work starts.

What must our internal team provide before the work starts?

Your team provides the decisions and access that only your organization can supply. These are typically:

Changes to the application that issues tokens, including the signing algorithm, the key identifier and the claims each token carries
A published JWKS endpoint or equivalent key source that Grafana can reach, with a process for rotating keys
A claim design that names the user identifier, email, role and organization values Grafana will read
Test users in each role and organization, plus a named owner who signs off on user acceptance testing

Without these inputs, the verification and mapping work stalls, so agree on owners and dates in the written scope.

Can a capable internal team build JWT login without outside help?

Yes, a team with experience in JWT validation, Grafana administration and its own token issuing application can build it alone. The work is well bounded: configure the JWT section of the Grafana configuration, verify tokens against your key source, set required claims, enable auto sign-up if wanted, and map roles and organizations. The risks sit in the details. Token lifetime, the lack of refresh token support, and handling of revoked users need deliberate design because the application must issue a new token when a session ends. Teams without this experience often choose a partner to review the design, test the failure paths and document the result.

What goes wrong most often with JWT login in Grafana?

The most common failures are mismatched claims, incorrect key handling and sessions that outlive their intent. A token missing a required claim, a key that fails to load from the JWKS endpoint after rotation, or an organization mapping that places users in the wrong org will each block or misdirect logins. Because Grafana does not support refresh tokens for JWT, the issuing application must manage session length and reissue tokens, so expiry settings should be tested end to end. Check these cases in a staging instance before production, and record the expected behavior for each one.

How does JWT login affect security and compliance evidence?

JWT login moves trust to your token issuer, so the security posture depends on how that issuer signs tokens, how keys are protected and rotated, and whether Grafana verifies signatures against the correct keys. Keep the key source reachable only over controlled paths, log authentication events in both the application and Grafana, and document who can change role mapping. Grafana's security hardening guidance covers cookies, headers and exposure controls that apply alongside JWT. DeployOpen prepares the configuration, controls and evidence for a compliance assessment, but independent auditors and certification bodies issue any audit report or certification.

How DeployOpen scopes and delivers a Grafana JWT integration

DeployOpen plans, builds, documents and supports the JWT login path between your application and a self-hosted Grafana instance inside your own infrastructure. Each engagement starts from a written, fixed scope that names the token issuer, claims, role and organization mapping, and the embedding pages involved.

How we scope

We map your token issuer, signing keys and JWKS endpoint to the Grafana settings that verify them.
We define the required claims, the login claim, and which roles and organizations each claim maps to.
We agree in writing which portals, embedded dashboards and user groups are in scope before work starts.

How we build

We configure JWT authentication in a non-production Grafana, with auto sign-up and role mapping set to your agreed model.
We test expired, malformed and wrongly signed tokens, plus users with missing or unexpected claims, before any release.
We confirm that the Grafana instance is reachable only through the paths your design intends, including the embedding origin.

How we hand over

We document the token contract, claim meanings, key rotation steps and the role and organization mapping table.
We deliver configuration as files your team can review, version and reproduce in your own environment.
We walk your engineers through token refresh design, since Grafana does not support refresh tokens for this login path.

How we support

Fixed-scope engagements end with agreed deliverables, and changes to scope are handled in writing.
Ongoing support, Grafana upgrades and continuous testing are available as a retainer.
We recommend re-running login and token tests after each Grafana upgrade, so changes to the JWT path are caught early.

Grafana JWT authentication for portals and embedded dashboards