Management Service

When heimdall is started, the management service is always exposed and offers endpoints for health monitoring and retrieving keys and certificates used by Heimdall for JWT creation.

By default, heimdall listens on 0.0.0.0:4457 for incoming requests and applies useful default timeouts and buffer limits. No additional options are configured by default, but you can adjust them as needed.

This service exposes the health and JWKS endpoints.

Configuration

The configuration of the management endpoint is defined under the management property. It supports the following properties.

host: string (optional)
Use this property to specify the TCP/IP address on which heimdall should listen for incoming connections. E.g. the entry 0.0.0.0 allows listening on all network interfaces for IPv4 and is the default setting.
port: integer (optional)
Use this property to specify the TCP port Heimdall should listen on. Defaults to 4457.
timeout: Timeout (optional)
Use this property to override heimdall’s default timeouts. The following options are available:
- idle: Duration (optional)
  The maximum time to wait for the next request when keep-alive is enabled. If set to 0s, the read timeout value is used. Defaults to 2 minutes.
- read: Duration (optional)
  The maximum time allowed to read the entire request, including the body. Defaults to 5 seconds. Setting this property to 0s disables the timeout.
- write: Duration (optional)
  The maximum duration before timing out response writes. Defaults to 10 seconds. Setting this property to 0s disables the timeout.
buffer_limit: BufferLimit (optional)
Defines buffer limits for inbound requests and outbound responses. The following options are available:
- read: ByteSize (optional)
  The maximum size of the read buffer for handling the full request, including the body. Defaults to 4KB.
- write: ByteSize (optional)
  The maximum size of the write buffer for responses. Defaults to 4KB.
cors: CORS (optional)
CORS (Cross-Origin Resource Sharing) headers can be configured using this option. This allows for fine-grained security settings.

tls: TLS (optional)

TLS-related configuration to ensure secure communication.

Although this property is optional, heimdall enforces its usage by default. This enforcement can be disabled (not recommended) by starting Heimdall with the --insecure-skip-ingress-tls-enforcement flag.

Example 1. Complex management service configuration

management:
  host: 127.0.0.1
  tls:
    key_store:
      path: /path/to/keystore.pem
      password: VerySecure!
  timeout:
    read: 1s
    write: 2s
    idle: 30s
  buffer_limit:
    read: 4KB
    write: 10KB

Last updated on Feb 13, 2025

Main Service Catalogue