From 4952b7f22d5d8ca479efdeac373d40a80c7db2ea Mon Sep 17 00:00:00 2001
From: Jo <joao.guerreiro@grafana.com>
Date: Mon, 5 Sep 2022 08:46:50 +0100
Subject: [PATCH] Add JWT url auth documentation (#54040)

* add jwt auth docs

* add appropriate warnings to docs

* remove unimplemented login_token assumptions

* Update conf/sample.ini
---
 conf/sample.ini                               |  1 +
 devenv/docker/blocks/auth/jwt_proxy/readme.md |  1 -
 .../configure-authentication/jwt.md           | 44 +++++++++++++++++++
 3 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/conf/sample.ini b/conf/sample.ini
index a1214c88f0a..eb974068a0b 100644
--- a/conf/sample.ini
+++ b/conf/sample.ini
@@ -598,6 +598,7 @@
 ;expected_claims = {"aud": ["foo", "bar"]}
 ;key_file = /path/to/key/file
 ;auto_sign_up = false
+;url_login = false
 
 #################################### Auth LDAP ##########################
 [auth.ldap]
diff --git a/devenv/docker/blocks/auth/jwt_proxy/readme.md b/devenv/docker/blocks/auth/jwt_proxy/readme.md
index 1494ea3e4e8..55b810512b6 100644
--- a/devenv/docker/blocks/auth/jwt_proxy/readme.md
+++ b/devenv/docker/blocks/auth/jwt_proxy/readme.md
@@ -15,7 +15,6 @@ signout_redirect_url = http://env.grafana.local:8088/oauth2/sign_out
 
 [auth.jwt]
 enabled = true
-enable_login_token = true
 header_name = X-Forwarded-Access-Token
 username_claim = login
 email_claim = email
diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/jwt.md b/docs/sources/setup-grafana/configure-security/configure-authentication/jwt.md
index 2a5499451e2..946ff8a9a98 100644
--- a/docs/sources/setup-grafana/configure-security/configure-authentication/jwt.md
+++ b/docs/sources/setup-grafana/configure-security/configure-authentication/jwt.md
@@ -15,6 +15,10 @@ You can configure Grafana to accept a JWT token provided in the HTTP header. The
 - 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:
@@ -53,6 +57,46 @@ email_claim = sub
 
 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.