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

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 访问密钥的值
```
interface Props extends DataSourcePluginOptionsEditorProps<MyDataSourceOptions, MySecureJsonData> {}
```
```
const { secureJsonData, secureJsonFields } = options;
const { apiKey } = secureJsonData;
```
注意
您可以执行此操作，直到用户保存配置；当用户保存配置时，Grafana 会清除该值。之后，您可以使用 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 中，从 instanceSettings 中提取代理 URL 到名为 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 并发送到令牌 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 := instanceSettings.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 插件 SDK for Go 创建 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​