Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
otelcol.auth.oauth2
otelcol.auth.oauth2
exposes a handler
that can be used by other otelcol
components to authenticate requests using OAuth 2.0.
The authorization tokens can be used by HTTP and gRPC based OpenTelemetry exporters. This component can fetch and refresh expired tokens automatically. For further details about OAuth 2.0 Client Credentials flow (2-legged workflow) see this document.
NOTE:
otelcol.auth.oauth2
is a wrapper over the upstream OpenTelemetry Collectoroauth2client
extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.
Multiple otelcol.auth.oauth2
components can be specified by giving them
different labels.
Usage
otelcol.auth.oauth2 "LABEL" {
client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
token_url = "TOKEN_URL"
}
Arguments
Name | Type | Description | Default | Required |
---|---|---|---|---|
client_id | string | The client identifier issued to the client. | no | |
client_id_file | string | The file path to retrieve the client identifier issued to the client. | no | |
client_secret | secret | The secret string associated with the client identifier. | no | |
client_secret_file | secret | The file path to retrieve the secret string associated with the client identifier. | no | |
token_url | string | The server endpoint URL from which to get tokens. | yes | |
endpoint_params | map(list(string)) | Additional parameters that are sent to the token endpoint. | {} | no |
scopes | list(string) | Requested permissions associated for the client. | [] | no |
timeout | duration | The timeout on the client connecting to token_url . | "0s" | no |
The timeout
argument is used both for requesting initial tokens and for refreshing tokens. "0s"
implies no timeout.
At least one of the client_id
and client_id_file
pair of arguments must be
set. In case both are set, client_id_file
takes precedence.
Similarly, at least one of the client_secret
and client_secret_file
pair of
arguments must be set. In case both are set, client_secret_file
also takes
precedence.
Blocks
The following blocks are supported inside the definition of
otelcol.auth.oauth2
:
Hierarchy | Block | Description | Required |
---|---|---|---|
tls | tls | TLS settings for the token client. | no |
tls block
The tls
block configures TLS settings used for connecting to the token client. If the tls
block isn’t provided,
TLS won’t be used for communication.
The following arguments are supported:
Name | Type | Description | Default | Required |
---|---|---|---|---|
ca_file | string | Path to the CA file. | no | |
ca_pem | string | CA PEM-encoded text to validate the server with. | no | |
cert_file | string | Path to the TLS certificate. | no | |
cert_pem | string | Certificate PEM-encoded text for client authentication. | no | |
insecure_skip_verify | boolean | Ignores insecure server TLS certificates. | no | |
include_system_ca_certs_pool | boolean | Whether to load the system certificate authorities pool alongside the certificate authority. | false | no |
insecure | boolean | Disables TLS when connecting to the configured server. | no | |
key_file | string | Path to the TLS certificate key. | no | |
key_pem | secret | Key PEM-encoded text for client authentication. | no | |
max_version | string | Maximum acceptable TLS version for connections. | "TLS 1.3" | no |
min_version | string | Minimum acceptable TLS version for connections. | "TLS 1.2" | no |
cipher_suites | list(string) | A list of TLS cipher suites that the TLS transport can use. | [] | no |
reload_interval | duration | The duration after which the certificate is reloaded. | "0s" | no |
server_name | string | Verifies the hostname of server certificates when set. | no |
If the server doesn’t support TLS, you must set the insecure
argument to true
.
To disable tls
for connections to the server, set the insecure
argument to true
.
If reload_interval
is set to "0s"
, the certificate never reloaded.
The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:
ca_pem
andca_file
cert_pem
andcert_file
key_pem
andkey_file
If cipher_suites
is left blank, a safe default list is used.
See the Go TLS documentation for a list of supported cipher suites.
Exported fields
The following fields are exported and can be referenced by other components:
Name | Type | Description |
---|---|---|
handler | capsule(otelcol.Handler) | A value that other components can use to authenticate requests. |
Component health
otelcol.auth.oauth2
is only reported as unhealthy if given an invalid
configuration.
Debug information
otelcol.auth.oauth2
does not expose any component-specific debug information.
Example
This example configures otelcol.exporter.otlp to use OAuth 2.0 for authentication:
otelcol.exporter.otlp "example" {
client {
endpoint = "my-otlp-grpc-server:4317"
auth = otelcol.auth.oauth2.creds.handler
}
}
otelcol.auth.oauth2 "creds" {
client_id = "someclientid"
client_secret = "someclientsecret"
token_url = "https://example.com/oauth2/default/v1/token"
}
Here is another example with some optional attributes specified:
otelcol.exporter.otlp "example" {
client {
endpoint = "my-otlp-grpc-server:4317"
auth = otelcol.auth.oauth2.creds.handler
}
}
otelcol.auth.oauth2 "creds" {
client_id = "someclientid2"
client_secret = "someclientsecret2"
token_url = "https://example.com/oauth2/default/v1/token"
endpoint_params = {"audience" = ["someaudience"]}
scopes = ["api.metrics"]
timeout = "3600s"
}