136 lines
4.8 KiB
Markdown
136 lines
4.8 KiB
Markdown
# OAuth2 Secret-store Plugin
|
|
|
|
The `oauth2` plugin allows to retrieve and maintain secrets from various OAuth2
|
|
services such as [Auth0][auth0], [AzureAD][azuread] or others (see
|
|
[Configuration section](#configuration)).
|
|
Tokens that are expired or are about to expire will be automatically renewed
|
|
by this secret-store, so other plugins referencing those tokens can then use
|
|
them to perform their API calls without hassle.
|
|
|
|
**Please note:** This plugin only supports the *2-legged client credentials*
|
|
flow.
|
|
|
|
You can use Telegraf to test token retrieval. Run
|
|
|
|
```shell
|
|
telegraf secrets help
|
|
```
|
|
|
|
to get more information on how to do access secrets with Telegraf.
|
|
|
|
## Usage <!-- @/docs/includes/secret_usage.md -->
|
|
|
|
Secrets defined by a store are referenced with `@{<store-id>:<secret_key>}`
|
|
the Telegraf configuration. Only certain Telegraf plugins and options of
|
|
support secret stores. To see which plugins and options support
|
|
secrets, see their respective documentation (e.g.
|
|
`plugins/outputs/influxdb/README.md`). If the plugin's README has the
|
|
`Secret-store support` section, it will detail which options support secret
|
|
store usage.
|
|
|
|
## Configuration
|
|
|
|
```toml @sample.conf
|
|
# Secret-store to retrieve and maintain tokens from various OAuth2 services
|
|
[[secretstores.oauth2]]
|
|
## Unique identifier for the secret-store.
|
|
## This id can later be used in plugins to reference the secrets
|
|
## in this secret-store via @{<id>:<secret_key>} (mandatory)
|
|
id = "secretstore"
|
|
|
|
## Service to retrieve the token(s) from
|
|
## Currently supported services are "custom", "auth0" and "AzureAD"
|
|
# service = "custom"
|
|
|
|
## Setting to overwrite the queried token-endpoint
|
|
## This setting is optional for some services but mandatory for others such
|
|
## as "custom" or "auth0". Please check the documentation at
|
|
## https://github.com/influxdata/telegraf/blob/master/plugins/secretstores/oauth2/README.md
|
|
# token_endpoint = ""
|
|
|
|
## Tenant ID for the AzureAD service
|
|
# tenant_id = ""
|
|
|
|
## Minimal remaining time until the token expires
|
|
## If a token expires less than the set duration in the future, the token is
|
|
## renewed. This is useful to avoid race-condition issues where a token is
|
|
## still valid, but isn't when the request reaches the API endpoint of
|
|
## your service using the token.
|
|
# token_expiry_margin = "1s"
|
|
|
|
## Section for defining a token secret
|
|
[[secretstores.oauth2.token]]
|
|
## Unique secret-key used for referencing the token via @{<id>:<secret_key>}
|
|
key = ""
|
|
## Client-ID and secret for the 2-legged OAuth flow
|
|
client_id = ""
|
|
client_secret = ""
|
|
## Scopes to send in the request
|
|
# scopes = []
|
|
|
|
## Additional (optional) parameters to include in the token request
|
|
## This might for example include the "audience" parameter required for
|
|
## auth0.
|
|
# [secretstores.oauth2.token.parameters]
|
|
# audience = ""
|
|
```
|
|
|
|
All services allow multiple `[[secretstores.oauth2.token]]` sections to be
|
|
specified to define different tokens for the secret store. Please make sure to
|
|
specify `key`s that are **unique** within the secret-store instance as those
|
|
are used to reference the tokens/secrets later.
|
|
|
|
The `oauth2` secret-store supports various services that might differ in the
|
|
required or allowed settings as listed below. All of the services accept
|
|
optional `scopes` and optional `parameter` settings if not stated otherwise.
|
|
|
|
Please **replace the placeholders** in the minumal example configurations below
|
|
and add `scopes` and/or `parameters` if required.
|
|
|
|
### Auth0
|
|
|
|
To use the [Auth0 service][auth0] for retrieving the token you need to set the
|
|
`token_endpoint` to your application's endpoint. Furthermore, specifying the
|
|
`audience` parameter is required. An example configuration look like
|
|
|
|
```toml
|
|
[[secretstores.oauth2]]
|
|
id = "secretstore"
|
|
service = "auth0"
|
|
token_endpoint = "https://YOUR_DOMAIN/oauth/token"
|
|
|
|
[[secretstores.oauth2.token]]
|
|
key = "mytoken"
|
|
client_id = "YOUR_CLIENT_ID"
|
|
client_secret = "YOUR_CLIENT_SECRET"
|
|
|
|
[secretstores.oauth2.token.parameters]
|
|
audience = "YOUR_API_IDENTIFIER"
|
|
```
|
|
|
|
### AzureAD
|
|
|
|
To use the [AzureAD service][azuread] for retrieving the token you need to set
|
|
the `tenant_id` and provide a valid `scope`. An example configuration look like
|
|
|
|
```toml
|
|
[[secretstores.oauth2]]
|
|
id = "secretstore"
|
|
service = "AzureAD"
|
|
tenant_id = "YOUR_TENANT_ID"
|
|
|
|
[[secretstores.oauth2.token]]
|
|
key = "mytoken"
|
|
client_id = "YOUR_CLIENT_ID"
|
|
client_secret = "YOUR_CLIENT_SECRET"
|
|
scopes = ["YOUR_CLIENT_ID/.default"]
|
|
```
|
|
|
|
### Custom service
|
|
|
|
If your service is not listed above, you can still use it setting
|
|
`service = "custom"` as well as the `token_endpoint`. Please make sure your
|
|
service is configured for the *2-legged client credentials* OAuth2 flow!
|
|
|
|
[auth0]: https://auth0.com
|
|
[azuread]: https://azure.microsoft.com/en/products/active-directory
|