Generate shareable, login-free links for Grafana dashboards using API key authentication. - Application Real-Time Monitoring Service

Generate shareable, login-free dashboard links via API key authentication.

Background

In native Grafana, direct access to a dashboard requires either using snapshots or enabling anonymous access. Snapshots are static and do not show real-time data updates, while anonymous access without an IP whitelist can be a security risk. In contrast, Managed Service for Grafana allows you to generate shareable, login-free dashboard links using API key authentication.
- You can share these links with other users.
- Users with a link can access the dashboard without logging in, as the API key provides authentication.
In Grafana 10.0.x, the API key feature is replaced by service account tokens, but API keys are still available. In Grafana 11.x, API keys have been completely removed, and the API key management page returns a 404 error. In this version, only service account tokens provide authentication. For more information, see Service accounts.

Step 1: Configure Grafana parameters

Log on to the ARMS console. In the left-side navigation pane, choose Managed Service for Grafana > Workspace Management.
On the Workspace Management page, click the ID of the workspace that you want to manage.
In the left-side navigation pane, click Parameter Settings.
In the parameter list on the left, select aliyun, and then click Modify Parameters.
Set the api_key_share parameter to true, and then click Save and Apply.

In the aliyun configuration category, find the api_key_share parameter in the parameter list.
Optional: To enable iframe embedding, configure the following parameters.
- For cross-domain embedding
  Your domain must use HTTPS. Then, set the following three security parameters.
```
allow_embedding=true
cookie_samesite=none
cookie_secure=true
```
- For same-domain embedding
  
  In the security section, set the allow_embedding parameter to true to enable iframe embedding.
- If you embed the iframe in another Grafana instance, adjust the panels parameters in that instance.
```
enable_alpha = true
disable_sanitize_html = true
```

Step 2: create an API key

The steps for creating an API key differ for Grafana 9.0.x and 10.0.x. Check your Grafana version and follow the appropriate procedure.

The API key feature has been removed in Grafana 11.x. Instead, create a service account token by following the procedure for Grafana 10.0.x.

If you upgrade from 9.0.x to 10.0.x, API keys created in Grafana 9.0.x are still visible on the Administration > api keys page. You can click migrate to service account to migrate them to a service account. After migration, the api keys page is hidden. Existing API keys will continue to work.

Grafana 9.0.x

Log on to the ARMS console. In the left-side navigation pane, choose Managed Service for Grafana > Workspace Management.
On the Workspace Management page, find the workspace that you want to manage and click the URL in the URL column to go to Grafana.

Note
You can log on to Grafana with the administrator account of Grafana and the password that you configured when you created the workspace. You can also click Sign in with Alibaba Cloud to log on to Grafana with the current Alibaba Cloud account.
In the upper-left corner of the Grafana homepage, click the icon.
In the left navigation pane of Grafana, choose Configuration > API keys.

Note
Admin permissions are required to access this page.

Click New API key or Add API key and configure the parameters.

Parameter	Description
Key name	A unique name for the API key.
Role	Set to Viewer.
Time to live	The validity period. For example: 60s (60 seconds), 10m (10 minutes), or 1d (1 day).

Click Add. In the dialog box that appears, copy and save the API key.

Important
The API key cannot be viewed again after the dialog box is closed.

In the API key created dialog box, click the Copy button next to the Key field to copy the API key. The dialog box also provides a cURL command example for authenticating requests by using the Authorization HTTP header: curl -H "Authorization: Bearer eyJrIjoi..." https://grafana-xxx.grafana.aliyuncs.com/api/dashboards/home.

Grafana 10.0.x

Log on to the ARMS console. In the left-side navigation pane, choose Managed Service for Grafana > Workspace Management.
On the Workspace Management page, find the workspace that you want to manage and click the URL in the URL column to go to Grafana.

Note
You can log on to Grafana with the administrator account of Grafana and the password that you configured when you created the workspace. You can also click Sign in with Alibaba Cloud to log on to Grafana with the current Alibaba Cloud account.
In the upper-left corner of the Grafana homepage, click the icon.
In the left navigation pane of Grafana, choose Manage > Service Accounts.
Important
- You need administrator permissions to access this menu.
- A service account consumes one user account.

Click Add service account, enter the parameters, and then click Create.

Parameter	Description
Display name	A unique name for the service account.
Role	Set to Viewer.

On the right side of the page, click Add service account token and enter the parameters.

Parameter	Description
Display name	A unique name for the token.
Expiration	The validity period of the token. No Expiration: The token does not expire. Set Expiration date: Specify an expiration date.
Expiration date	Required when you select Set Expiration date.

Click Generate token. In the dialog box that appears, click Copy to clipboard and close.

Important

The token cannot be viewed again after the dialog box is closed.

Step 3: Generate a shareable link

Grafana 9.0.x

In the Grafana UI, open the dashboard that you want to share.
Click the icon and get the shareable link from the Link tab.

Append &aliyun_api_key=<API key value> to the end of the link. Replace <API key value> with the API key that you obtained in Step 2.

https://grafana-example.grafana.aliyuncs.com/d/TZWea****/test?orgId=1&from=167081684****&to=167083844****&aliyun_api_key=eyJr****WkIwNnN2c0RTSD******

Use the shareable link to access the Grafana dashboard without logging in.

Grafana 10.0.x

In the Grafana UI, open the dashboard that you want to share.
Click the icon and get the shareable link from the Link tab.

In the dialog box, you can set options such as lock time range (which converts a relative time range to an absolute one), theme (current, dark, or light), and shorten URL. In the Link URL section at the bottom, click the Copy button.
Append &aliyun_api_key=<API key value> to the end of the link. Keep the URL parameter name aliyun_api_key unchanged, and replace its value with the service account token that you obtained in Step 2.
```
https://grafana-example.grafana.aliyuncs.com/d/TZWea****/test?orgId=1&from=167081684****&to=167083844****&aliyun_api_key=eyJrIjoiWkIwNnN2c0RTSD******
```
Use the shareable link to access the Grafana dashboard without logging in.

Step 4: Generate a high-security shareable link (optional)

The shareable links generated in Step 3: Generate a shareable link require periodic API key rotation to prevent security risks from key exposure. This section describes how to generate a high-security shareable link for an API key in Grafana 9.0.x and for a service account token in Grafana 10.0.x.

Before you begin, you must set the api_key_share_version runtime parameter to v2.

Log on to the ARMS console. In the left-side navigation pane, choose Managed Service for Grafana > Workspace Management.
On the workspace management page, click the ID of the target workspace. In the left-side navigation pane, click Parameter Settings.
Set the runtime parameter for api_key_share_version to v2, and then click Save and Apply.

API key (Grafana 9.0.x)

Base64-decode the API key that you obtained in Step 2: Create an API key.

Base64 is a common encoding method used to transmit 8-bit bytecode over the network. It uses 64 printable characters to represent binary data.

You can search for a common tool website for decryption, such as base64.

Decode in Java.

package main;
import java.util.Base64;
public class Base64Example{
    public static void main(String[] args) {
        String apiKey = "eyJr****REpzZGYzd2JIa0N3ekgyWjlWWmhrSTM5bWdGT2hGSmwiLCJuIjoidGVzdDEiLCJpZCI6MX0=";
        String decodeKey = new String(Base64.getDecoder().decode(apiKey));
        System.out.println(decodeKey);
    }
}

Output:

{"k":"DJsd****HkCwzH2Z9VZhkI39mgFOhFJl","n":"test1","id":1}

Decode in Go.

package main;
import "fmt"
import "encoding/base64"
func main() {
	apiKey := "eyJr****REpzZGYzd2JIa0N3ekgyWjlWWmhrSTM5bWdGT2hGSmwiLCJuIjoidGVzdDEiLCJpZCI6MX0="
	decodeKey, err := base64.StdEncoding.DecodeString(apiKey)
	if err != nil {
		fmt.Println(err.Error())
		return
	}
	fmt.Println(string(decodeKey))
}

Output:

{"k":"DJsd****HkCwzH2Z9VZhkI39mgFOhFJl","n":"test1","id":1}

Derive a PBKDF2 hash from the k value in the decoded JSON object.

PBKDF2 (Password-Based Key Derivation Function 2) is a key derivation function used to securely derive a cryptographic key from a password and other parameters, such as a salt and the number of iterations. It is commonly used for password storage and is designed to make it more difficult for an attacker to recover plaintext passwords or crack the derived keys even if a database is compromised.

You can derive the hash in different ways. The following table describes the required parameters.

Parameter	Description
salt	Set this to the API key name, which is the `n` value from the decoded JSON object. In this example, the value is `test1`.
iterations	Set the value to `10000`.
output length	Set the value to `50` bytes.
key size	Set the value to `256` bits.
Output type	Set the type to `Hex`.

You can search for common online encryption tools, such as PBKDF2.

Derive the hash in Java.

package main;
import javax.crypto.SecretKeyFactory;
import java.security.GeneralSecurityException;
import javax.crypto.spec.PBEKeySpec;
import java.security.spec.KeySpec;
public class PBKDFExapmle {
    public static void main(String[] args) {
        String password = "DJsd****HkCwzH2Z9VZhkI39mgFOhFJl";
        String salt = "test1";
        int iterationCount = 10000;
        int outputLength = 50 * 8;
        try {
            KeySpec spec = new PBEKeySpec(password.toCharArray(), salt.getBytes(), iterationCount, outputLength);
            SecretKeyFactory skf = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256");
            byte[] keyBytes = skf.generateSecret(spec).getEncoded();
            System.out.println(bytesToHex(keyBytes));
        } catch (GeneralSecurityException e) {
            e.printStackTrace();
        }
    }
    private static String bytesToHex(byte[] bytes) {
        StringBuilder hexString = new StringBuilder();
        for (byte b : bytes) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
                hexString.append('0');
            }
            hexString.append(hex);
        }
        return hexString.toString();
    }
}

Output:

1e5b**80184e78832544aae4d2e031a3539c10b575b75d7c1d44af49fcf5a7de9c58a5f0035ce35fff0e5b0476e882**

Derive the hash in Go.

package main;
import "fmt"
import "encoding/hex"
import "crypto/sha256"
import "golang.org/x/crypto/pbkdf2"
func main() {
    password:="DJsd****HkCwzH2Z9VZhkI39mgFOhFJl"
    salt:="test1"
    newPasswd := pbkdf2.Key([]byte(password), []byte(salt), 10000, 50, sha256.New)
	encodePassword:= hex.EncodeToString(newPasswd)
	fmt.Println(encodePassword)
}

Output:

1e5b**80184e78832544aae4d2e031a3539c10b575b75d7c1d44af49fcf5a7de9c58a5f0035ce35fff0e5b0476e882**

Compute an MD5 signature from the PBKDF2 output.

The MD5 message-digest algorithm is a widely used cryptographic hash function that produces a 128-bit (16-byte) hash value to ensure the integrity of information transmission.

Construct the string to be signed as follows: <PBKDF2 Password> + "_" + <current Unix timestamp in seconds>

PBKDF2 Password: 1e5b**80184e78832544aae4d2e031a3539c10b575b75d7c1d44af49fcf5a7de9c58a5f0035ce35fff0e5b0476e882**

If the current system time is 2024-09-20 17:12:13, the Unix timestamp in seconds is 1726823533.

String to sign: 1e5b**80184e78832544aae4d2e031a3539c10b575b75d7c1d44af49fcf5a7de9c58a5f0035ce35fff0e5b0476e882**_1726823533

You can compute the MD5 signature in different ways:

You can search for common online encryption tools, such as MD5.

Compute the MD5 signature in Java.

package main;
import java.security.MessageDigest;
public class MD5 {
    public static void main(String[] args) {
        String pbkdfPassword = "1e5b****80184e78832544aae4d2e031a3539c10b575b75d7c1d44af49fcf5a7de9c58a5f0035ce35fff0e5b0476e882****";
        long timeSeconds=System.currentTimeMillis()/1000;
        String key=pbkdfPassword+"_"+timeSeconds;
        System.out.println(MD5.getMD5String(key,"UTF-8"));
    }
    public static String getMD5String(String str, String charset) {
        try {
            MessageDigest messageDigest = MessageDigest.getInstance("MD5");
            messageDigest.reset();
            messageDigest.update(str.getBytes(charset));
            byte[] byteArray = messageDigest.digest();
            StringBuffer md5StrBuff = new StringBuffer();
            for (int i = 0; i < byteArray.length; i++) {
                if (Integer.toHexString(0xFF & byteArray[i]).length() == 1) {
                    md5StrBuff.append("0").append(
                        Integer.toHexString(0xFF & byteArray[i]));
                } else {
                    md5StrBuff.append(Integer.toHexString(0xFF & byteArray[i]));
                }
            }
            return md5StrBuff.toString().toLowerCase();
        } catch (Exception e) {
            e.printStackTrace();
            throw new RuntimeException("MD5 error:"+e.getMessage());
        }
    }
}

Compute the MD5 signature in Go.

package main;
import (
    "crypto/md5"
    "encoding/hex"
    "fmt"
    "io"
    "time"
    "strconv"
)
func main() {
    // The string for which you want to calculate the MD5 hash.
    pbkdfPassword := "1e5b****80184e78832544aae4d2e031a3539c10b575b75d7c1d44af49fcf5a7de9c58a5f0035ce35fff0e5b0476e882****"
    timeSeconds:= time.Now().Unix()
    key:=pbkdfPassword+"_"+strconv.FormatInt(timeSeconds, 10)
    // Use the MD5 package to calculate the MD5 hash of the string.
    hash := md5.New()
    io.WriteString(hash, key)
    md5Str := hash.Sum(nil)
    // Convert the binary MD5 hash to a hexadecimal string.
    md5StrHex := hex.EncodeToString(md5Str)
    fmt.Println("MD5 of", key, "is", md5StrHex)
}

Append the generated MD5 signature information as parameters to the link.

Parameters:

Parameter	Description	Example
aliyun_api_key_sign	The MD5 signature, which changes over time.	c3bf89b867cc88df72d507edc4d1****
aliyun_api_key_timestamp	The signing timestamp. The signature expires if the difference between this timestamp and the server time exceeds one minute.	1726823533
aliyun_api_key_name	The name of the API key.	test1
aliyun_api_key_org_id	The ID of the organization to which the API key belongs.	1
aliyun_api_key_expire_seconds	The duration, in seconds, that the session remains valid after logging in with the signed URL.	Default: 3600

Example:

https://grafana-example.grafana.aliyuncs.com/d/TZWea****/test?orgId=1&from=167081684****&to=167083844****&aliyun_api_key_sign=c3bf89b867cc88df72d507edc4d1****&aliyun_api_key_timestamp=1726823533&aliyun_api_key_name=test1&aliyun_api_key_org_id=1

You can now programmatically generate more secure, login-free links to Grafana, which also prevents API key exposure.

Service account token (Grafana 10.0.x)

Split the service account token from Step 2: Create a service account token and then derive a PBKDF2 hash from its components.

Split the service account token by the underscore (_) character.

# Example service account token:
Token: glsa_yV9HAOVCjNKkvKoLMiypOc5T0Oov****_4f5ff3ce
# After splitting:
Prefix: glsa
Secret: yV9HAOVCjNKkvKoLMiypOc5T0Oov****
Salt:   4f5ff3ce

You can derive the hash in different ways. The following table describes the required parameters.

Parameter	Description
salt	Set this to the token's suffix. In this example, the value is `4f5ff3ce`.
iterations	Set the value to `10000`.
output length	Set the value to `50` bytes.
key size	Set the value to `256` bits.
Output type	Set the type to `Hex`.

You can search for a common tool website for decryption, such as charsetpbkdf2.

Derive the hash in Java.

package main;
import javax.crypto.SecretKeyFactory;
import java.security.GeneralSecurityException;
import javax.crypto.spec.PBEKeySpec;
import java.security.spec.KeySpec;
public class PBKDFExapmle {
    public static void main(String[] args) {
        String password = "yV9H****jNKkvKoLMiypOc5T0OovHXPV";
        String salt = "4f5ff3ce";
        int iterationCount = 10000;
        int outputLength = 50 * 8;
        try {
            KeySpec spec = new PBEKeySpec(password.toCharArray(), salt.getBytes(), iterationCount, outputLength);
            SecretKeyFactory skf = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256");
            byte[] keyBytes = skf.generateSecret(spec).getEncoded();
            System.out.println(bytesToHex(keyBytes));
        } catch (GeneralSecurityException e) {
            e.printStackTrace();
        }
    }
    private static String bytesToHex(byte[] bytes) {
        StringBuilder hexString = new StringBuilder();
        for (byte b : bytes) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
                hexString.append('0');
            }
            hexString.append(hex);
        }
        return hexString.toString();
    }
}

Output:

c3cd****971bab928e4ecd6e7a00c74657696ea07d38c43f3bb5dc3190f2285cb80695cf7bf2f25c9b1f34fe1e0f9549****

Derive the hash in Go.

package main;
import "fmt"
import "encoding/hex"
import "crypto/sha256"
import "golang.org/x/crypto/pbkdf2"
func main() {
    password:="yV9H****jNKkvKoLMiypOc5T0OovHXPV"
    salt:="4f5ff3ce"
    newPasswd := pbkdf2.Key([]byte(password), []byte(salt), 10000, 50, sha256.New)
	encodePassword:= hex.EncodeToString(newPasswd)
	fmt.Println(encodePassword)
}

Output:

c3cd****971bab928e4ecd6e7a00c74657696ea07d38c43f3bb5dc3190f2285cb80695cf7bf2f25c9b1f34fe1e0f9549****

Compute an MD5 signature from the PBKDF2 output.

The MD5 Message-Digest Algorithm is a widely used cryptographic hash function that can produce a 128-bit (16-byte) hash value used to ensure the integrity and consistency of information transmission.

Construct the string to be signed as follows: <PBKDF2 Password> + "_" + <current Unix timestamp in seconds>

PBKDF2 Password: c3cd****971bab928e4ecd6e7a00c74657696ea07d38c43f3bb5dc3190f2285cb80695cf7bf2f25c9b1f34fe1e0f9549****

If the current system time is 2024-09-20 17:12:13, the Unix timestamp in seconds is 1726823533.

String to sign: c3cd****971bab928e4ecd6e7a00c74657696ea07d38c43f3bb5dc3190f2285cb80695cf7bf2f25c9b1f34fe1e0f9549****_1726823533

You can compute the MD5 signature in different ways:

You can search for commonly used online encryption tools, such as MD5.

Compute the MD5 signature in Java.

package main;
import java.security.MessageDigest;
public class MD5 {
    public static void main(String[] args) {
        String pbkdfPassword = "c3cd****971bab928e4ecd6e7a00c74657696ea07d38c43f3bb5dc3190f2285cb80695cf7bf2f25c9b1f34fe1e0f9549****";
        long timeSeconds=System.currentTimeMillis()/1000;
        String key=pbkdfPassword+"_"+timeSeconds;
        System.out.println(MD5.getMD5String(key,"UTF-8"));
    }
    public static String getMD5String(String str, String charset) {
        try {
            MessageDigest messageDigest = MessageDigest.getInstance("MD5");
            messageDigest.reset();
            messageDigest.update(str.getBytes(charset));
            byte[] byteArray = messageDigest.digest();
            StringBuffer md5StrBuff = new StringBuffer();
            for (int i = 0; i < byteArray.length; i++) {
                if (Integer.toHexString(0xFF & byteArray[i]).length() == 1) {
                    md5StrBuff.append("0").append(
                        Integer.toHexString(0xFF & byteArray[i]));
                } else {
                    md5StrBuff.append(Integer.toHexString(0xFF & byteArray[i]));
                }
            }
            return md5StrBuff.toString().toLowerCase();
        } catch (Exception e) {
            e.printStackTrace();
            throw new RuntimeException("MD5 error:"+e.getMessage());
        }
    }
}

Compute the MD5 signature in Go.

package main;
import (
    "crypto/md5"
    "encoding/hex"
    "fmt"
    "io"
    "time"
    "strconv"
)
func main() {
    // The string for which you want to calculate the MD5 hash.
    pbkdfPassword := "c3cd****971bab928e4ecd6e7a00c74657696ea07d38c43f3bb5dc3190f2285cb80695cf7bf2f25c9b1f34fe1e0f9549****"
    timeSeconds:= time.Now().Unix()
    key:=pbkdfPassword+"_"+strconv.FormatInt(timeSeconds, 10)
    // Use the MD5 package to calculate the MD5 hash of the string.
    hash := md5.New()
    io.WriteString(hash, key)
    md5Str := hash.Sum(nil)
    // Convert the binary MD5 hash to a hexadecimal string.
    md5StrHex := hex.EncodeToString(md5Str)
    fmt.Println("MD5 of", key, "is", md5StrHex)
}

Append the generated MD5 signature information as parameters to the link.

Parameters:

Parameter	Description	Example
aliyun_api_key_sign	The MD5 signature, which changes over time.	c3bf89b867cc88df72d507edc4d1****
aliyun_api_key_timestamp	The signing timestamp. The signature expires if the difference between this timestamp and the server time exceeds one minute.	1726823533
aliyun_api_key_name	The name of the service account token.	sa-1-****-***-75c7-41ae-94da-*******
aliyun_api_key_org_id	The ID of the organization to which the service account token belongs.	1
aliyun_api_key_expire_seconds	The duration, in seconds, that the session remains valid after logging in with the signed URL.	Default: 3600

Example:

https://grafana-example.grafana.aliyuncs.com/d/TZWea****/test?orgId=1&from=167081684****&to=167083844****&aliyun_api_key_sign=c3bf89b867cc88df72d507edc4d1****&aliyun_api_key_timestamp=1726823533&aliyun_api_key_name=sa-1-******-*****-75c7-41ae-94da-*******&aliyun_api_key_org_id=1

You can now programmatically generate more secure, login-free links to Grafana, preventing service account token exposure.

FAQ

When accessing an embedded dashboard, the page fails to load and the browser displays a refused to connect error.

Possible cause: The allow_embedding parameter is not set for an embedded dashboard. To configure the allow_embedding parameter, see Step 1.
The dashboard does not display any data. The page shows a Not found message and a yellow Unauthorized warning notification, and the dashboard area is empty.
For embedded dashboards, this issue can occur if the browser cannot write a cookie. Possible causes include:
- Cross-domain requests: If the root domains are different, the default configuration prevents cookies from being written.
- The cookie_samesite parameter is set to none, but the cookie_secure parameter is set to false.
- The domain uses HTTP. Because the cookie_secure parameter is ineffective over HTTP, you must serve your domain over HTTPS.
Solution: Reconfigure the Grafana parameters as described in Step 1.
When I access a dashboard through a shared link, Grafana displays the error If you're seeing this Grafana has failed to load its application files. The page suggests troubleshooting steps for reverse proxy configurations, sub-path deployments (check root_url or set serve_from_sub_path = true), local development builds, restarting grafana-server, and browser compatibility.
Possible causes:
- Your browser version is outdated.
- Your browser's settings are blocking the embedded dashboard.
  Solution:
  1. Check your browser's settings to allow cookies.
  2. If you are using Chrome in incognito mode, allow all cookies.
For dashboard embedding, should I set a short validity period for an API key and rotate it frequently, or should I configure a long-lived key?

You can configure the validity period based on your security requirements. We recommend rotating the key every three months. If an API key is compromised, delete it immediately.
Is there a limit on the number of API keys I can create?

The Grafana source code does not impose a hard limit. However, the UI can only display a maximum of 100 keys on the management page. For easier management, we recommend using 100 keys or fewer.
Does the system automatically delete an API key when its validity period expires?

No, expired API keys are not automatically deleted. They remain in the system but are hidden by default. On the API keys page in Grafana, you can click Include expired keys to display them. Enabling the Include expired keys toggle displays the records for expired API keys, including their name, role, and expiration time. To remove a key, click the delete button in the corresponding row.