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.

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