Management

The Management service is always there, regardless of the mode of operation Heimdall is started in. By default, Heimdall listens on 0.0.0.0:4457 endpoint for incoming requests in this mode of operation and also configures useful default timeouts. No other options are configured. You can however adjust the configuration for your needs.

This service exposes the health and the JWKS endpoints.

Configuration

The configuration for of the Management endpoint can be adjusted in the management property, which lives in the serve property of heimdall’s configuration and supports the following properties.

  • host: string (optional)

    By making use of this property, you can specify the TCP/IP address on which heimdall should listen for connections from client applications. The entry 0.0.0.0 allows listening for all IPv4 addresses. 0.0.0.0 is also the default setting.

    Example 1. Configure heimdall to allow only local TCP/IP “loopback” connections to be made.
    management:
  host: 127.0.0.1

  • port: integer (optional)

    By making use of this property, you can specify the TCP port the heimdall should listen on. Defaults to 4457.

    Example 2. Configure heimdall to listen on port 4444 for incoming requests.
    management:
  port: 4444

  • verbose_errors: boolean (optional)

    By making use of this property you can instruct Heimdall to preserve error information and provide it in the response body to the caller. Defaults to false.

    Heimdall supports MIME type negotiation. So, if the client sets the HTTP Accept header to e.g. application/json, and Heimdall run into an unhandled internal error condition, in addition to responding with 500 Internal Server Error, it will render an error message, like shown below, if verbose_errors has been set to true.

    {
  "code": "internalServerError",
  "message": "whatever led to the error"
}

    The message will however contain just high-level information, like "failed to parse something", but will not contain any stack traces.

    Example 3. Configure verbose errors
    management:
  verbose_errors: true

  • timeout: Timeout (optional)

    Like written in the introduction of this section, Heimdall configures useful timeout defaults. You can however override this by making use of the timeout option and specifying the timeouts, you need.

    Example 4. Setting the read timeout to 1 second, write timeout to 2 seconds and the idle timeout to 1 minute.
    management:
  timeout:
    read: 1s
    write: 2s
    idle: 1m

  • cors: CORS (optional)

    CORS (Cross-Origin Resource Sharing) headers can be added and configured by making use of this option. This functionality allows for advanced security features to quickly be set.

    Example 5. Possible CORS configuration
    management:
  cors:
    allowed_origins:
      - example.org
    allowed_methods:
      - HEAD
      - PATCH
    allow_credentials: true
    max_age: 10s

  • tls: TLS (optional)

    By default, the Management endpoint accepts HTTP requests. Depending on your deployment scenario, you could require Heimdall to accept HTTPS requests only. You can do so by making use of this option.

    Example 6. TLS configuration
    management:
  tls:
    key: /path/to/private_key.pem
    cert: /path/to/certificate.pem

Last updated on Jul 26, 2022

Proxy
Common Configuration Options