mirror of
https://github.com/grafana/grafana.git
synced 2025-07-31 22:02:17 +08:00
4952b7f22d
* add jwt auth docs * add appropriate warnings to docs * remove unimplemented login_token assumptions * Update conf/sample.ini
146 lines
4.5 KiB
Markdown
146 lines
4.5 KiB
Markdown
---
|
|
aliases:
|
|
- /docs/grafana/latest/auth/jwt/
|
|
- /docs/grafana/latest/setup-grafana/configure-security/configure-authentication/jwt/
|
|
description: Grafana JWT Authentication
|
|
title: Configure JWT Authentication
|
|
weight: 500
|
|
---
|
|
|
|
# Configure JWT authentication
|
|
|
|
You can configure Grafana to accept a JWT token provided in the HTTP header. The token is verified using any of the following:
|
|
|
|
- PEM-encoded key file
|
|
- JSON Web Key Set (JWKS) in a local file
|
|
- JWKS provided by the configured JWKS endpoint
|
|
|
|
This method of authentication is useful for integrating with other systems that
|
|
use JWKS but can't directly integrate with Grafana or if you want to use pass-through
|
|
authentication in an app embedding Grafana.
|
|
|
|
## Enable JWT
|
|
|
|
To use JWT authentication:
|
|
|
|
1. Enable JWT in the [main config file]({{< relref "../../configure-grafana/" >}}).
|
|
1. Specify the header name that contains a token.
|
|
|
|
```ini
|
|
[auth.jwt]
|
|
# By default, auth.jwt is disabled.
|
|
enabled = true
|
|
|
|
# HTTP header to look into to get a JWT token.
|
|
header_name = X-JWT-Assertion
|
|
```
|
|
|
|
## Configure login claim
|
|
|
|
To identify the user, some of the claims needs to be selected as a login info. You could specify a claim that contains either a username or an email of the Grafana user.
|
|
|
|
Typically, the subject claim called `"sub"` would be used as a login but it might also be set to some application specific claim.
|
|
|
|
```ini
|
|
# [auth.jwt]
|
|
# ...
|
|
|
|
# Specify a claim to use as a username to sign in.
|
|
username_claim = sub
|
|
|
|
# Specify a claim to use as an email to sign in.
|
|
email_claim = sub
|
|
|
|
# auto-create users if they are not already matched
|
|
# auto_sign_up = true
|
|
```
|
|
|
|
If `auto_sign_up` is enabled, then the `sub` claim is used as the "external Auth ID". The `name` claim is used as the user's full name if it is present.
|
|
|
|
## Iframe Embedding
|
|
|
|
If you want to embed Grafana in an iframe while maintaning user identity and role checks,
|
|
you can use JWT authentication to authenticate the iframe.
|
|
|
|
> **Note**: for scenarios where verifying viewer identity is not required,
|
|
> [public dashboards]({{< relref "../../../dashboards/dashboard-public" >}}) embedding should be used.
|
|
|
|
In this scenario, you will need to configure Grafana to accept a JWT
|
|
provided in the HTTP header and a reverse proxy should rewrite requests to the
|
|
Grafana instance to include the JWT in the request's headers.
|
|
|
|
> **Note**: for embedding to work `allow_embedding` must be enabled in the [security section]({{< relref "../../configure-grafana#allow_embedding" >}}).
|
|
|
|
In a scenario where it is not possible to rewrite the request headers you
|
|
can use URL login instead.
|
|
|
|
### URL login
|
|
|
|
`url_login` allows grafana to search for a JWT in the URL query parameter
|
|
`auth_token` and use it as the authentication token.
|
|
|
|
> **Warning**: this can lead to JWTs being exposed in logs and possible session hijacking if the server is not
|
|
> using HTTP over TLS.
|
|
|
|
```ini
|
|
# [auth.jwt]
|
|
# ...
|
|
url_login = true # enable JWT authentication in the URL
|
|
```
|
|
|
|
An example of an URL for accessing grafana with JWT URL authentication is:
|
|
|
|
```
|
|
http://env.grafana.local/d/RciOKLR4z/board-identifier?orgId=1&kiosk&auth_token=eyJhbxxxxxxxxxxxxx
|
|
```
|
|
|
|
A sample repository using this authentication method is available
|
|
at [grafana-iframe-oauth-sample](https://github.com/grafana/grafana-iframe-oauth-sample).
|
|
|
|
## Signature verification
|
|
|
|
JSON web token integrity needs to be verified so cryptographic signature is used for this purpose. So we expect that every token must be signed with some known cryptographic key.
|
|
|
|
You have a variety of options on how to specify where the keys are located.
|
|
|
|
### Verify token using a JSON Web Key Set loaded from https endpoint
|
|
|
|
For more information on JWKS endpoints, refer to [Auth0 docs](https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets).
|
|
|
|
```ini
|
|
# [auth.jwt]
|
|
# ...
|
|
|
|
jwk_set_url = https://your-auth-provider.example.com/.well-known/jwks.json
|
|
|
|
# Cache TTL for data loaded from http endpoint.
|
|
cache_ttl = 60m
|
|
```
|
|
|
|
### Verify token using a JSON Web Key Set loaded from JSON file
|
|
|
|
Key set in the same format as in JWKS endpoint but located on disk.
|
|
|
|
```ini
|
|
jwk_set_file = /path/to/jwks.json
|
|
```
|
|
|
|
### Verify token using a single key loaded from PEM-encoded file
|
|
|
|
PEM-encoded key file in PKIX, PKCS #1, PKCS #8 or SEC 1 format.
|
|
|
|
```ini
|
|
key_file = /path/to/key.pem
|
|
```
|
|
|
|
## Validate claims
|
|
|
|
By default, only `"exp"`, `"nbf"` and `"iat"` claims are validated.
|
|
|
|
You might also want to validate that other claims are really what you expect them to be.
|
|
|
|
```ini
|
|
# This can be seen as a required "subset" of a JWT Claims Set.
|
|
expect_claims = {"iss": "https://your-token-issuer", "your-custom-claim": "foo"}
|
|
```
|