Authentication for Datasource Plugins

    The plugin config page should save the API key/password to be encrypted (using the feature) and then when a request from the datasource is made, the Grafana Proxy will:

    • decrypt the API key/password on the backend.
    • carry out authentication and generate an OAuth token that will be added as an Authorization HTTP header to all requests (or it will add a HTTP header with the API key).
    • renew the token if it expires.This means that users that access the datasource config page cannot access the API key or password after is saved the first time and that no secret keys are sent in plain text through the browser where they can be spied on.

    For backend authentication to work, the external/third-party API must either have an OAuth endpoint or that the API accepts an API key as a HTTP header for authentication.

    You can specify routes in the plugin.json file for your datasource plugin. Here is an example with lots of routes (though most plugins will just have one route).

    When you build your url to the third-party API in your datasource class, the url should start with the text specified in the path field for a route. The proxy will strip out the path text and replace it with the value in the url field.

    For example, if my code makes a call to url azuremonitor/foo/bar with this code:

    1.   "path": "azuremonitor",
    2.   "method": "GET",
    3.   "url": "https://management.azure.com",
    4.   ...
    5. }]

    then the Grafana proxy will transform it into “ and add CORS headers.

    The method parameter is optional. It can be set to any HTTP verb to provide more fine-grained control.

    When using routes, you can also reference a variable stored in JsonData or SecureJsonData which will be interpolated when connecting to the datasource.

    With JsonData:

    With SecureJsonData:

    1. "routes": [{
    3.       "method": "*",
    4.       "url": "{{.SecureJsonData.dynamicUrl}}",
    5. }]

    An app using this feature can be found here.

    When a user saves a password or secret with your datasource plugin’s Config page, then you can save data to a column in the datasource table called secureJsonData that is an encrypted blob. Any data saved in the blob is encrypted by Grafana and can only be decrypted by the Grafana server on the backend. This means once a password is saved, no sensitive data is sent to the browser. If the password is saved in the jsonData blob or the password field then it is unencrypted and anyone with Admin access (with the help of Chrome Developer Tools) can read it.

    This is an example of using the secureJsonData blob to save a property called password:

    Some third-party API’s accept a HTTP Header for authentication. The below has a headers section that defines the name of the HTTP Header that the API expects and it uses the blob to fetch an encrypted API key. The Grafana server proxy will decrypt the key, add the X-API-Key header to the request and forward it to the third-party API.

    1. {
    2.   "path": "appinsights",
    3.   "method": "GET",
    4.   "url": "https://api.applicationinsights.io",
    5.   "headers": [
    6.     {"name": "X-API-Key", "content": "{{.SecureJsonData.appInsightsApiKey}}"}
    7.   ]
    8. }

    The token auth section in the plugin.json file looks like this:

    The plugin.json files are only loaded when the Grafana server starts so when a route is added or changed then the Grafana server has to be restarted for the changes to take effect.