HTTP server

The Maverics Identity Orchestrator includes an HTTP server in order to consume and process requests for Apps and other endpoints. The server has various properties defined below that can be configured.

Configuration options

Address

The address declares which address the Orchestrator will listen on. If the host section of the address is blank, the Orchestrator will listen on all available unicast and anycast IP addresses of the local system.

Example with just port specified:

http:
  address: :443

Example with IP and port specified:

http:
  address: 127.0.0.1:443

Alternatively, the HTTP server address can be specified via the MAVERICS_HTTP_ADDRESS environment variable. If the address is defined in both config and environment variable, the value from the environment variable will be used.

export MAVERICS_HTTP_ADDRESS=":443"

TLS

tls defines the transport layer security object will be used for the server. The TLS object used for the server must include valid certFile and keyFile fields.

The HTTP server’s TLS key pair can also be defined as environment variables by setting both MAVERICS_TLS_SERVER_CERT_FILE and MAVERICS_TLS_SERVER_KEY_FILE. If the server’s TLS key pair is defined in both config and environment variables, the value from the environment variable will be used.

export MAVERICS_TLS_SERVER_CERT_FILE="/etc/certs/maverics.sonarsystems.co.crt"
export MAVERICS_TLS_SERVER_KEY_FILE="/etc/certs/maverics.sonarsystems.co.key"

Read Timeout

readTimeoutSeconds is an optional field used to define the maximum duration for reading the entire request, including the body. When not defined, a default of 20 seconds will be used. A zero value means there will be no timeout.

Read Header Timeout

readHeaderTimeoutSeconds is an optional field used to determine the amount of time allowed to read request headers. When not defined, a default of 5 seconds will be used. If zero, the value of readTimeoutSeconds is used. If zero and readTimeoutSeconds is also zero, there is no timeout.

Write Timeout

writeTimeoutSeconds is an optional field used to define the maximum duration before timing out writes of the response. When not defined, a default value of 20 seconds will be used. A zero value means there will be no timeout.

Idle Timeout

idleTimeoutSeconds is an optional field used to define the maximum amount of time to wait for the next request when keep-alives are enabled. When not defined, a default of 60 seconds will be used. If zero, the value of readTimeoutSeconds is used. If zero and readTimeoutSeconds is also zero, there is no timeout.

Endpoint Timeout

endpointTimeoutSeconds is an optional field used to define the maximum amount of time an HTTP endpoint has to process a request and write a response. When this timeout is exceeded, a 503 Service Unavailable error will be returned as the response. When not defined, a default of 15 seconds will be used. The value defined SHOULD be set to a lower value than the writeTimeoutSeconds, so a response can be written before the HTTP server times out a given connection.

Hosts

hosts define an optional list of server names that will be used for TLS handshakes. Please note that hosts are used solely for the TLS handshake and do not impact request routing within the Orchestrator. The server name indicator (SNI) on the TLS handshake is used to match the request to the correct host.

hosts cannot be defined with http.tls.

Server Name

serverName defines the server name value used for matching. This value will be matched with the SNI value on the TLS handshake. Either serverName or default must be defined.

Default

default defines whether the server is used when there is not an SNI match to another server. Either serverName or default must be defined.

TLS

tls defines the transport layer security object will be used for the server. The TLS object used for the server must include valid certFile and keyFile fields.

AccessLog

The accessLog section controls whether the Orchestrator writes access logs. These logs capture key details about each request, such as:

Request path (e.g., /login)
HTTP method (e.g., GET, POST)
HTTP version (e.g., HTTP/1.1)
Response status code (e.g., 200, 404)
Trace ID (e.g., 41afb4d60bf8f143bc5e5227662bba13)
Session ID (e.g., d7781cfb-c38a-46d0-9e8b-2ef199356a0a)
Bytes written (e.g., 1206)
Start time (e.g., 2025-04-03T13:40:37.706267Z)
End time (e.g., 2025-04-03T13:40:37.285727Z)
Duration (e.g., 1014000ns)

Example of logs:

ts=2025-04-03T13:40:37.285727Z level=debug msg="response written" traceID=41afb4d60bf8f143bc5e5227662bba13 sessionID=d7781cfb-c38a-46d0-9e8b-2ef199356a0a statusCode=200 bytesWritten=1206 endTimeUnixNS=1743687637285724000 durationNS=1014000
ts=2025-04-03T13:40:37.706267Z level=debug msg="request received" path=/acs method=POST host=localhost protocol=HTTP/2.0 traceID=5740bf3482f2f8f4e7e632154b6deb27 sessionID=d7781cfb-c38a-46d0-9e8b-2ef199356a0a startTimeUnixNS=1743687637706260000

Enabled

enabled field turns access logging on or off.

By default, access logging is disabled (false). Set this to true to start logging request details.

Level

level sets the log level of the access logs. Log level debug, info or error are accepted values. By default, if the log level is not defined, it will default to debug.

ℹ️

Access logging is useful for debugging and observability but may reduce performance when enabled, especially under high traffic.

Example Configuration

Basic HTTPS Server

tls:
  maverics:
    certFile: /etc/certs/example.com.crt
    keyFile: /etc/certs/example.com.key

http:
  address: :443
  tls: maverics
  readHeaderTimeoutSeconds: 5

Mutual TLS (mTLS) using SNI

tls:
  maverics:
    certFile: /etc/certs/example.com.crt
    keyFile: /etc/certs/example.com.key

  mtls:
    certFile: /etc/certs/secure.example.com.crt
    keyFile: /etc/certs/secure.example.com.key
    clientAuth: RequireAndVerifyClientCert
    clientCAFiles:
      - certs/mtlsCA.pem

http:
  address: :443
  hosts:
    # The TLS configuration that will be used for the 'secure.example.com' SNI value. 
    - serverName: secure.example.com
      tls: mtls

    # The default TLS configuration that will be used for all other SNI values besides 
    # 'secure.example.com'.
    - default: true
      tls: maverics

Enabling logging of access logs

http:
  accessLog:
    enabled: true
    level: debug

Transport security (TLS)