dstore-dist-report-api

Root Node Config¶

A sample dstore-dist-report-apiconfiguration is shown below:

listen_addr: "localhost:8080"

elasticsearch:
  addr: https://localhost:19200
  index: my-forwarder-index*
  # Auth username.
  user: admin
  # Auth password.
  password: changeme
  tlsconfig:
    insecure_skip_verify: true

log:
  # Trace loglevel would not be set in production environments
  level: Trace

The following YAML key-values are supported for configuration at the root node:

Parameter	Type	Description
`api_key`	string	API Key to use for authorization using the `X-API-Key` header. If not specified, and no other authorization method is specified, then no authorization will be required.
`elasticsearch`	Elasticsearch
`http`	HTTP Metrics	Prometheus Metrics HTTP Listener
`listen_addr`	`<ip:port>`	The address to listen on for REST API queries. The value is an address:port string, in either v4 or v6 format. IPv6 addresses must be placed in square brackets like this `[::1]`. You can omit the address to listen on all local addresses
`oauth2`	OAuth2/OpenID Connect	OAuth2/OpenID Connect Authorization Configuration
`tlsconfig`	TLS Config	TLS Configuration for the listener
`log`	Log Config	Log configuration. Note - enable `Trace` level logging to see all Opensearch/Elasticsearch Requests and Responses

HTTP Metrics¶

The following YAML fields are supported for configuration:

Parameter	Type	Default	Description
`address`	`<ip:port>`		The address to listen on for prometheus metrics. The value is an address:port string, in either v4 or v6 format. IPv6 addresses must be placed in square brackets like this `[::1]`.

Elasticsearch¶

The following YAML fields are supported for configuration:

Parameter	Type	Description
`addr`	`string`	The URL of the elasticsearch server
`api_key`	`string`	Alternative auth method
`cloud_id`	`string`	Alternative auth method
`index`	`string`	Pattern of the elasticsearch index to retrieve events from, e.g. logstash-*
`password`	`string`	The password to authenticate to elasticsearch
`readiness_interval`	`go:`DurationString	How often to check the Elasticsearch connection for readiness
`startup_retries`	`integer`	On startup, how many times to retry connecting to Elasticsearch (default 100)
`tlsconfig`	TLS Config	TLS configuration for the connection to elasticsearch. Leave out if not using TLS
`user`	`string`	The username to authenticate to elasticsearch
`wait_interval`	`go:`DurationString	On startup, how long to wait for an Elasticsearch connection to succeed before giving up (default 500ms)

OAuth2/OpenID Connect¶

The following YAML fields are supported for configuration:

Parameter	Type	Description
`bearer`	Bearer Token Authorization	Configure OAuth2 Bearer Token Authorization

Bearer Token Authorization¶

OAuth Bearer Token Authorization is based on the flows in RFC 7662 and works as follows:

Clients wishing to access the API obtain a token from an OAuth2 authorization server, via the token endpoint
Clients then make API requests with a Authorization: Bearer <token> header
dstore-dist-report-api validates the token using the token introspection endpoint described in RFC 7662

Currently only Client Credentials Grant is supported in terms of authenticating to the token introspection endpoint (this involves sending the Client ID and Secret as Basic Authentication).

The configuration of this feature is achieved using the following YAML fields:

Parameter	Type	Mandatory	Description
`client_id`	`string`	yes	The Client ID to present to the token introspection endpoint
`client_secret`	`string`	yes	The Client Secret to present to the token introspection endpoint
`issuer_url`	`string`	yes	The Issuer URL of the Authorization Server
`required_scopes`	`Array of string`		List any scopes which are required to be present in the token for authorization to succeed
`tlsconfig`	TLS Config		TLS configuration for the connection to the introspection endpoint
`disable_token_cache`	`boolean`		Disable caching of bearer tokens - this will affect performance since every request will require an introspection lookup to the authorization server

Authorization Preference¶

If OAuth Bearer Token Authorization is configured, all requests must be authorized using this method, and no other method will work, e.g. X-API-Key authorization.

If Oauth is not configured, and an api_key is configured, then X-API-Key authorization must be used if authorization is desired.

If neither are configured, then all API requests will be accepted with no authorization required.