为数据源插件添加身份验证

Grafana 插件可以通过使用数据源代理或通过自定义后端插件对第三方 API 执行经过身份验证的请求。

选择身份验证方法

可以通过以下两种方式之一配置您的数据源插件以对第三方 API 进行身份验证

使用数据源代理方法，或者
构建后端插件。

情况	使用
您是否需要使用基本身份验证或 API 密钥对插件进行身份验证？	使用数据源代理。
您的 API 是否支持使用客户端凭据的 OAuth 2.0？	使用数据源代理。
您的 API 是否使用数据源代理不支持的自定义身份验证方法？	使用后端插件。
您的 API 是否通过 HTTP 以外的协议进行通信？	使用后端插件。
您的插件是否需要警报支持？	使用后端插件。

加密数据源配置

数据源插件有两种存储自定义配置的方式：jsonData 和 secureJsonData。

具有查看者角色的用户可以访问数据源配置，例如jsonData的内容（明文）。如果您已启用匿名访问，则任何可以访问其浏览器中 Grafana 的人都可以查看jsonData的内容。

Grafana Enterprise 的用户可以将对数据源的访问权限限制为特定用户和团队。有关更多信息，请参阅数据源权限。

您可以通过在浏览器的开发者控制台中输入window.grafanaBootData来查看当前用户可以访问的设置。

警告

不要将jsonData与敏感数据（如密码、令牌和 API 密钥）一起使用。如果需要存储敏感信息，请改用secureJsonData。

在 secureJsonData 中存储配置

如果需要存储敏感信息，请使用secureJsonData而不是jsonData。每当用户保存数据源配置时，secureJsonData中的机密信息都会发送到 Grafana 服务器，并在存储之前进行加密。

加密安全配置后，将无法再从浏览器访问。保存机密信息后，唯一访问它们的方法是使用数据源代理。

为您的数据源插件添加机密配置

要向数据源插件添加机密信息，您可以添加对配置 API 密钥的支持。

在types.ts中创建一个新接口以保存 API 密钥

export interface MySecureJsonData {
  apiKey?: string;
}

通过更新ConfigEditor的 props 以接受接口作为第二个类型参数，为您的secureJsonData对象添加类型信息。从ConfigEditor内部的options prop 访问机密的 value
```
interface Props extends DataSourcePluginOptionsEditorProps<MyDataSourceOptions, MySecureJsonData> {}
```
```
const { secureJsonData, secureJsonFields } = options;
const { apiKey } = secureJsonData;
```
注意
您可以这样做，直到用户保存配置；当用户保存配置时，Grafana 会清除该 value。之后，您可以使用secureJsonFields来确定该属性是否已配置。

要安全地更新插件配置编辑器中的机密信息，请使用onOptionsChange prop 更新secureJsonData对象

const onAPIKeyChange = (event: ChangeEvent<HTMLInputElement>) => {
  onOptionsChange({
    ...options,
    secureJsonData: {
      apiKey: event.target.value,
    },
  });
};

定义一个可以接受用户输入的组件

<Input
  type="password"
  placeholder={secureJsonFields?.apiKey ? 'configured' : ''}
  value={secureJsonData.apiKey ?? ''}
  onChange={onAPIKeyChange}
/>

可选：如果希望用户能够重置 API 密钥，则需要在secureJsonFields对象中将该属性设置为false

const onResetAPIKey = () => {
  onOptionsChange({
    ...options,
    secureJsonFields: {
      ...options.secureJsonFields,
      apiKey: false,
    },
    secureJsonData: {
      ...options.secureJsonData,
      apiKey: '',
    },
  });
};

一旦用户可以配置机密信息，下一步就是了解如何将它们添加到我们的请求中。

使用数据源代理进行身份验证

用户保存数据源配置后，浏览器中将不再提供机密数据源配置。只能在服务器上访问加密的机密信息。那么如何将它们添加到您的请求中呢？

Grafana 服务器附带一个代理，允许您为请求定义模板：代理路由。Grafana 将代理路由发送到服务器，解密机密信息以及其他配置，并在发送请求之前将它们添加到请求中。

注意

请务必不要将数据源代理与身份验证代理混淆。数据源代理用于对数据源进行身份验证，而身份验证代理用于登录 Grafana 本身。

为您的插件添加代理路由

要通过 Grafana 代理转发请求，您需要配置一个或多个代理路由。代理路由是代理处理的任何传出请求的模板。您可以在plugin.json文件中配置代理路由。

将路由添加到plugin.json
src/plugin.json
```
"routes": [
  {
    "path": "example",
    "url": "https://api.example.com"
  }
]
```
注意
每次更改plugin.json文件时，都需要构建插件并重新启动 Grafana 服务器。

在DataSource中，将代理 URL 从instanceSettings提取到名为url的类属性中

export class DataSource extends DataSourceApi<MyQuery, MyDataSourceOptions> {
  url?: string;

  constructor(instanceSettings: DataSourceInstanceSettings<MyDataSourceOptions>) {
    super(instanceSettings);

    this.url = instanceSettings.url;
  }

  // ...
}

在query方法中，使用BackendSrv发出请求。URL 路径的第一部分需要与代理路由的path匹配。数据源代理将this.url + routePath替换为路由的url。根据我们的示例，请求的 URL 将为https://api.example.com/v1/users
```
import { getBackendSrv } from '@grafana/runtime';
```
```
const routePath = '/example';

getBackendSrv().datasourceRequest({
  url: this.url + routePath + '/v1/users',
  method: 'GET',
});
```

为您的插件添加动态代理路由

Grafana 将代理路由发送到服务器，数据源代理在发出请求之前解密任何敏感数据并将模板变量与解密的数据进行插值。

要将用户定义的配置添加到您的路由中

对于存储在jsonData中的配置，使用.JsonData。例如，其中projectId是jsonData对象中属性的名称
src/plugin.json
```
"routes": [
  {
    "path": "example",
    "url": "https://api.example.com/projects/{{ .JsonData.projectId }}"
  }
]
```
对于存储在secureJsonData中的敏感数据，使用.SecureJsonData。例如，其中password是secureJsonData对象中属性的名称
src/plugin.json
```
"routes": [
  {
    "path": "example",
    "url": "https://{{ .JsonData.username }}:{{ .SecureJsonData.password }}@api.example.com"
  }
]
```

除了将 URL 添加到代理路由外，还可以添加标头、URL 参数和请求正文。

向代理路由添加 HTTP 标头

以下是如何添加name和content作为 HTTP 标头的示例

src/plugin.json
"routes": [
  {
    "path": "example",
    "url": "https://api.example.com",
    "headers": [
      {
        "name": "Authorization",
        "content": "Bearer {{ .SecureJsonData.apiToken }}"
      }
    ]
  }
]

向代理路由添加 URL 参数

以下是如何添加name和content作为 URL 参数的示例

src/plugin.json
"routes": [
  {
    "path": "example",
    "url": "http://api.example.com",
    "urlParams": [
      {
        "name": "apiKey",
        "content": "{{ .SecureJsonData.apiKey }}"
      }
    ]
  }
]

注意

请注意，urlParams配置仅在数据源插件中受支持。它不支持应用插件。

向代理路由添加请求正文

以下是如何将username和password添加到请求正文的示例

src/plugin.json
"routes": [
  {
    "path": "example",
    "url": "http://api.example.com",
    "body": {
      "username": "{{ .JsonData.username }}",
      "password": "{{ .SecureJsonData.password }}"
    }
  }
]

为您的插件添加 OAuth 2.0 代理路由

由于您对每个路由的请求都是使用 OAuth 2.0 身份验证在服务器端发出的，因此仅支持机器到机器请求。换句话说，如果您需要使用客户端凭据以外的其他授权，则需要自行实现。

要使用 OAuth 2.0 进行身份验证，请将tokenAuth对象添加到代理路由定义中。如有必要，Grafana 会向tokenAuth中定义的 URL 发出请求以检索令牌，然后再向代理路由中的 URL 发出请求。Grafana 会在令牌过期时自动续订令牌。

在tokenAuth.params中定义的任何参数都将编码为application/x-www-form-urlencoded并发送到token URL。

src/plugin.json
{
  "routes": [
    {
      "path": "api",
      "url": "https://api.example.com/v1",
      "tokenAuth": {
        "url": "https://api.example.com/v1/oauth/token",
        "params": {
          "grant_type": "client_credentials",
          "client_id": "{{ .SecureJsonData.clientId }}",
          "client_secret": "{{ .SecureJsonData.clientSecret }}"
        }
      }
    }
  ]
}

注意

请注意，tokenAuth配置仅在数据源插件中受支持。它不支持应用插件。

使用后端插件进行身份验证

虽然数据源代理支持HTTP API最常用的身份验证方法，但使用代理路由有一些限制。

代理路由仅支持HTTP或HTTPS。
代理路由不支持自定义令牌身份验证。

如果您的插件适用上述任何限制，则需要添加一个后端插件。由于后端插件在服务器上运行，因此它们可以访问解密的密钥，这使得实现自定义身份验证方法更加容易。

解密的密钥可从实例设置中的DecryptedSecureJSONData字段获取。

func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
  instanceSettings := req.PluginContext.DataSourceInstanceSettings

  if apiKey, exists := settings.DecryptedSecureJSONData["apiKey"]; exists {
    // Use the decrypted API key.
  }

  // ...
}

转发已登录用户的OAuth身份

如果您的数据源使用与Grafana本身相同的OAuth提供程序，例如，使用通用OAuth身份验证，则您的数据源插件可以重用已登录Grafana用户的访问令牌。

要允许Grafana将访问令牌传递到插件，请更新数据源配置并将jsonData.oauthPassThru属性设置为true。 DataSourceHttpSettings设置提供了一个切换按钮，即转发OAuth身份选项。您也可以构建一个合适的切换按钮，以便在数据源配置页面UI中设置jsonData.oauthPassThru。

配置后，Grafana可以将授权HTTP标头（如Authorization或X-ID-Token）转发到后端数据源。此信息可在QueryData、CallResource和CheckHealth请求中获取。

要使Grafana转发标头，请使用Grafana Go插件SDK创建一个HTTP客户端，并将ForwardHTTPHeaders选项设置为true（默认情况下，它设置为false）。此软件包公开了请求信息，这些信息可以随后转发到下游或直接在插件中使用，或者两者兼而有之。

func NewDatasource(ctx context.Context, settings backend.DataSourceInstanceSettings) (instancemgmt.Instance, error) {
  opts, err := settings.HTTPClientOptions(ctx)
	if err != nil {
		return nil, fmt.Errorf("http client options: %w", err)
	}

    // Important: Reuse the same client for each query to avoid using all available connections on a host.

  opts.ForwardHTTPHeaders = true

	cl, err := httpclient.New(opts)
	if err != nil {
		return nil, fmt.Errorf("httpclient new: %w", err)
	}
	return &Datasource{
		httpClient: cl,
	}, nil
}

func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
    // Necessary to keep the Context, since the injected middleware is configured there
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://some-url", nil)
    if err != nil {
      return nil, fmt.Errorf("new request with context: %w", err)
    }
    // Authorization header is automatically injected if oauthPassThru is configured
    resp, err := ds.httpClient.Do(req)
    // ...
}

您可以在此处查看完整的插件示例：datasource-http-backend。

从HTTP请求中提取标头

如果您需要直接访问HTTP标头信息，您也可以从请求中提取该信息。

func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
  token := strings.Fields(req.GetHTTPHeader(backend.OAuthIdentityTokenHeaderName))
  var (
    tokenType   = token[0]
    accessToken = token[1]
  )
  idToken := req.GetHTTPHeader(backend.OAuthIdentityIDTokenHeaderName) // present if user's token includes an ID token

  // ...
  return &backend.CheckHealthResult{Status: backend.HealthStatusOk}, nil
}

func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
  token := strings.Fields(req.GetHTTPHeader(backend.OAuthIdentityTokenHeaderName))
  var (
    tokenType   = token[0]
    accessToken = token[1]
  )
  idToken := req.GetHTTPHeader(backend.OAuthIdentityIDTokenHeaderName)

  for _, q := range req.Queries {
    // ...
  }
}

func (ds *dataSource) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
  token := req.GetHTTPHeader(backend.OAuthIdentityTokenHeaderName)
  idToken := req.GetHTTPHeader(backend.OAuthIdentityIDTokenHeaderName)

  // ...
}

使用cookie

转发已登录用户的cookie

您的数据源插件可以将已登录Grafana用户的cookie转发到数据源。使用数据源配置页面上的DataSourceHttpSettings组件。它提供了允许的cookie选项，您可以在其中指定cookie名称。

配置后，与授权标头一样，如果您使用SDK HTTP客户端，这些cookie将自动注入。

提取已登录用户的cookie

如果需要，您也可以在QueryData、CallResource和CheckHealth请求中提取cookie。

QueryData

func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
  cookies:= req.GetHTTPHeader(backend.CookiesHeaderName)

  // ...
}

CallResource

func (ds *dataSource) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
  cookies:= req.GetHTTPHeader(backend.CookiesHeaderName)

  // ...
}

CheckHealth

func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
  cookies:= req.GetHTTPHeader(backend.CookiesHeaderName)

  // ...
}

转发已登录用户的用户标头

当send_user_header启用时，Grafana使用X-Grafana-User标头将用户标头传递到插件。您可以转发此标头以及授权标头或已配置的cookie。

QueryData

像这样转发QueryData标头

func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
  u := req.GetHTTPHeader("X-Grafana-User")

  // ...
}

CallResource

像这样转发CallResource标头

func (ds *dataSource) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
  u := req.GetHTTPHeader("X-Grafana-User")

  // ...
}

CheckHealth

像这样转发CheckHealth标头

func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
  u := req.GetHTTPHeader("X-Grafana-User")

  // ...
}

选择身份验证方法​

加密数据源配置​

在 secureJsonData 中存储配置​

为您的数据源插件添加机密配置​

使用数据源代理进行身份验证​

为您的插件添加代理路由​

为您的插件添加动态代理路由​

向代理路由添加 HTTP 标头​

向代理路由添加 URL 参数​

向代理路由添加请求正文​

为您的插件添加 OAuth 2.0 代理路由​

使用后端插件进行身份验证​

转发已登录用户的OAuth身份​

从HTTP请求中提取标头​

使用cookie​

转发已登录用户的cookie​

提取已登录用户的cookie​

转发已登录用户的用户标头​

QueryData​

CallResource​

CheckHealth​