{"token_count": 2639} # Using JWT Authentication with Grafana In this guide, you will enroll Grafana as a Teleport-protected application that uses [JSON Web Token authentication](https://grafana.com/docs/grafana/latest/setup-grafana/configure-access/configure-authentication/jwt/). ## How it works Teleport issues short-lived JWTs and injects them into each proxied request to Grafana. Grafana is configured to trust Teleport’s JWT signer, allowing it to verify the user’s identity and retrieve role information from the Teleport-signed token. ## Prerequisites - A running Teleport cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: **Mac/Linux** ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` **Windows - Powershell** ``` $ $TELEPORT_DOMAIN = "teleport.example.com:443" $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation/single-machine.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` Connecting with TLS routing disabled This guide's commands assume your Teleport cluster uses TLS routing (`proxy_listener_mode: multiplex`), where the `tctl` and `tsh` clients reach every Teleport service through the Proxy Service's web address on port `443`. If you're not sure whether this applies to your cluster, check with whoever manages it. If your cluster uses separate listener ports instead, adjust ports as follows: - **`tsh` commands** (e.g., `tsh login --proxy=...`): continue using the Proxy Service web address on port `3080` (or `443` if behind a load balancer). Do not change these to port `3025`. - **Direct `tctl` or Auth Service API commands**: use port `3025` for the Auth Service gRPC listener: ``` $ tctl status --auth-server=teleport.example.com:3025 ``` * Check that you can connect to your Teleport cluster and verify that you can run `tctl` and `tsh` commands using your current credentials. 1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username. 2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not. **In an interactive shell:** Run the following command. By default, this triggers a multi-factor authentication prompt: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.10.0 CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` **On non-interactive environments:** If you are running `tsh` and `tctl` as an AI agent, in a CI/CD environment, or similar, make sure the `TELEPORT_IDENTITY_FILE` environment variable is assigned to a valid file path with credentials for your cluster. `tsh` and `tctl` read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you [set up Machine ID](https://goteleport.com/docs/machine-workload-identity/getting-started.md) to provision one automatically. When executing `tctl` commands with an identity file, you must pass the `--auth-server` flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, `tctl` connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to `3025` if you are contacting the Auth Service directly with `tctl`: ``` $ tctl status --auth-server=teleport.example.com:443 ``` For `tsh` commands that read an identity file, you must pass the `--proxy` flag, which points `tsh` to the address of the Teleport Proxy Service: ``` $ tsh status --proxy=teleport.example.com ``` Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file: ``` $ export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}" ``` Add the `--auth-server` or `--proxy` flags to all subsequent `tctl` and `tsh` commands. If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. * Running [Application Service](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/connecting-apps.md). * Access to main config of your Grafana instance ## Step 1/3. Configure JWT authentication in Grafana Add an `auth.jwt` section in Grafana’s main configuration file. Replace teleport.example.com with the domain name of your Teleport cluster: ``` [auth.jwt] enabled = true # HTTP header to look into to get a JWT token. header_name = Authorization # JSON Web Key Set (JWKS) URL from your Teleport cluster. jwk_set_url = https://teleport.example.com/.well-known/jwks.json # Teleport username can be found in "sub" or "username" claims. username_claim = sub # Map Teleport users to Grafana organization roles based on their Teleport # roles. Adjust accordingly. # # In this example, if the user's Teleport role list (the "roles" claim) contains # "editor", assign them the Grafana "Editor" role. All other users get the # "Viewer" role. # # Teleport user traits are also available in the "traits" claim and can be # used in expressions in the same way as roles. role_attribute_path = contains(roles[*], 'editor') && 'Editor' || 'Viewer' # auto-create users if they are not already matched. auto_sign_up = true ``` Restart your Grafana instance after updating the config. ## Step 2/3. Register a Grafana application in Teleport You can register the Grafana application in Teleport by defining it in your Teleport Application Service configuration, or by using dynamic registration with `tctl` or Terraform. Assign app URI to the domain of your Grafana instance: **Static configuration** Add an application entry in your Teleport Application Service configuration file, `teleport.yaml`: ``` app_service: enabled: true apps: - name: "grafana" uri: app URI rewrite: headers: - "Authorization: Bearer {{internal.jwt}}" ``` Restart the Teleport Application service. **tctl** Create an `app` resource definition file named `app-grafana.yaml`: ``` # app-grafana.yaml kind: app version: v3 metadata: name: grafana spec: uri: app URI rewrite: headers: - name: "Authorization" value: "Bearer {{internal.jwt}}" ``` Create the `app` resource with: ``` $ tctl create -f app-grafana.yaml ``` **Terraform** Create a `teleport_app` resource in terraform: ``` resource "teleport_app" "grafana" { version = "v3" metadata = { name = "grafana" labels = { "teleport.dev/origin" = "dynamic" } } spec = { uri = "app URI" rewrite = { headers = [{ name = "Authorization" value = "Bearer {{internal.jwt}}" }] } } } ``` Apply the configuration: ``` $ terraform apply ``` The header rewrite configuration above will replace the `{{internal.jwt}}` template variable with a Teleport-signed JWT token in each request. ## Step 3/3. Connect to Grafana Log in to your Teleport cluster in your browser at https\://teleport.example.com. In the **Resources** tab, locate the `grafana` application and click **Launch**. Grafana will open and you should be automatically logged in as your Teleport user. You can verify this by clicking your profile icon in the upper-right corner. ## Next steps - Get more information about integrating with [Teleport JWT tokens](https://goteleport.com/docs/enroll-resources/application-access/jwt/introduction.md). - See the [dynamic registration](https://goteleport.com/docs/enroll-resources/application-access/configuration/dynamic-registration.md) guide. - Learn more about [accessing APIs](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/api-access.md) with the Teleport Application Service. - Take a look at application-related [Access Controls](https://goteleport.com/docs/enroll-resources/application-access/configuration/controls.md).