Configuration options for the Nomad server on Domino

Note: As of Nomad 1.0.13, Nomad will no longer read the saml config from nomad-config.yml, please migrate your SAML configuration to Domino by following Configure SAML authentication for Nomad server on Domino.

Configure TLS using CertMgr on Domino

Follow the instructions in the Domino documentation for setting up a manual or Let's Encrypt certificate for the Domino server.
Ensure that the document for the certificate configuration lists the current Domino server as usable.
Ensure there is a replica of certstore.nsf on the Domino server you are configuring, and that it is up-to-date with any previous changes.
Set the ini setting NOMAD_WEB_HOST on the Domino server to the hostname in your certificate.
For example, if your Domino server's certificate hostname is domino.acme.com, use console command: set config NOMAD_WEB_HOST=domino.acme.com. Wildcards certificates also work. If you have a wildcard certificate, use the wildcard hostname as the ini value.
Re-launch nomad task. For example: restart task nomad

Configuration file

You may place a nomad-config.yml file in your Domino data directory. This is a YAML file.

The values listed here, as indicated, are the default values. You do not need to set them unless you want to change them.

Setting the ip address and port to listen on

# these are the defaults
host: '0.0.0.0'
port: 9443

Setting the servers addresses and ports

Nomad server on Domino should be able to lookup and connect to the other Domino servers in your domain by default, but if you do run into errors related to connecting to the other Domino servers (for example, Nomad: nwsp:wss:error Error: connect ETIMEDOUT), you may specify the servers: option with a line for each canonical name follow by the ip address and port:

servers:
  CN=domino/O=EXAMPLE: 127.0.0.1:1352

If you are having issues related to IPv6 such as nwsp:wss:error Error: connect ECONNREFUSED ::1:1352 and you do not want to generally enable IPv6 in Domino nor change the operating system's preference to be IPv4 over IPv6, you may specify all of your Domino servers in this section with the IPv4 addresses.

Setting the default mail servers

During initial configuration of the Nomad client, the user's information will be attempted to be obtained via the user's mail server. If the user has an assigned mail server, nothing more needs to be done. But if the user does not have an assigned mail server, a default server, randomly chosen from the defaultMailServers list, can be utilized instead:

defaultMailServers:
  - CN=domino1/O=EXAMPLE
  - CN=domino2/O=EXAMPLE

You can force the defaultMailServers list to be used for everyone by specifying:

force_default_mail_servers: true

Setting the directory where temporary files are stored

By default, temporary files (for example, the deploy nsf file) will be stored in the operating system's temp directory. To have the files stored in a different directory, specify cacheFiles.

cacheFiles: '/where/you/want'

Configuring the session cookie

If not set, the server generates a random secret on startup.

Pick a random string for the secret. You may change this as often as you like. Changing the value invalidates everyone's session.

# these are the defaults
session:
  secret: # default: randomly generated 32 character value
  sameSite: none
  secure: true

Configuring LTPA for use behind SafeLinx

If you have a custom cookie name, you can set this.

# these are the defaults
ltpa:
  cookieName: LtpaToken2

Configure how frequently the server will check CertMgr for updated certificate

# these are the defaults
tlsPoll: 3600000 # one hour in milliseconds

Nomad federated login

For federated login to work, you must place your deploy.nsf at <nomad-files>/config/deploy.nsf.

<nomad-files> refers to the location where the Nomad for web browsers client files were unzipped as part of the Nomad server file being unzipped in Installation. By default, <nomad-files> are placed in <Domino program directory>/nomad-files/.

For more information, see Configuring Nomad federated login.

Configure TLS certificate

If you did not configure TLS using CertMgr (recommended), you can also configure the TLS certificate via the config file.

Note: The ca value may be omitted if your cert contains a full pem chain.

ca: # file location or contents of the ca's certificate pem file
cert: # file location or contents of the certificate pem file
key: # file location or contents of the certificate key pem file

Configuring optional HTTP headers

You may configure optional HTTP headers to be included in the response. Defaults are set for security purposes, but you may add to or modify this list by uncommenting them and changing them here; if you need to remove a default header, set its value to "". These default security headers are also included in the documentation page with SafeLinx as the Nomad server. For more information, see Optional headers.

# HTTP headers added to the server response
httpHeaders:
  # Defaults:
  # Strict-Transport-Security: max-age=7776000; includeSubDomains
  # X-Content-Type-Options: nosniff
  # Referrer-Policy: strict-origin-when-cross-origin
  # X-Frame-Options: DENY
  # X-XSS-Protection: 1; mode=block
  # Permissions-Policy: "accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), cross-origin-isolated=(self), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), geolocation=(self), gyroscope=(), hid=(), idle-detection=(), magnetometer=(), microphone=(), midi=(), navigation-override=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), serial=(), sync-xhr=(), usb=(), web-share=()"
  # Content-Security-Policy: "default-src 'self'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'; script-src-elem 'self' 'unsafe-inline'; style-src 'unsafe-inline'; style-src-elem 'self' 'unsafe-inline'; img-src 'self' blob: data:; font-src 'self' data:; frame-src 'self'"

For deployments using SAML or OIDC, the Content-Security-Policy header likely requires further additions for the identity provider (IdP) for at least the following directives. This may vary depending on your IdP:

img-src - to load image assets from the identity provider
connect-src - to make requests to the identity provider
frame-src - to initiate the SAML assertion

The following is an example configuration for SAML with AWS as the identity provider:

 Content-Security-Policy: "default-src 'self'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'; script-src-elem 'self' 'unsafe-inline'; 
style-src 'unsafe-inline'; style-src-elem 'self' 'unsafe-inline'; img-src 'self' blob: data: https://*.amazonaws.com 
https://*.awsapps.com; connect-src 'self' data: https://*.amazonaws.com https://*.awsapps.com; font-src 
'self' data:; frame-src 'self' https://*.amazonaws.com https://*.awsapps.com"

Configuring HTTP port for use behind a reverse proxy

Nomad server on domino HTTP port is defined by the “httpPort” option (default value is 9080).

By default, Nomad server on Domino will redirect all HTTP requests to their corresponding HTTPS URLs.

With the "trustProxy" set to true and "X-Forwarded-Proto: https" header in request, Nomad server on Domino can directly handle incoming HTTP requests without redirecting to HTTPS.

```
# these are the defaults
# httpPort: 9080
# trustProxy: false
```

The HTTP listener can be turned off by setting the “httpPort” option to 0. The HTTPS listener can also be turned off by setting the “port” option to 0.

Support Let’s Encrypt HTTP-01 challenge requests

Nomad server on Domino can work with Domino CertMgr to handle Let’s Encrypt HTTP-01 challenge requests.

Upon receiving HTTP-01 challenge requests, Nomad server on Domino will query the response from the certstore.nsf database and respond back to complete the challenge. When no response is found in the certstore.nsf database, Nomad server on Domino will respond with a 404 status code.

The following example displays a successfully request/response:


# HTTP-01 challenge request:
./.well-known/acme-challenge/DOMINO-CertMgr-DiagChallenge-HTTP01

# Nomad server response:
DOMINO-ACME-PROTOCOL-CHALLENGE-DATA-OK

For complete flow of requesting a certificate from the Let's Encrypt CA with Domino CertMgr, see Requesting a certificate from the Let's Encrypt CA.

For more information on Let’s Encrypt HTTP-01 challenge, see this article.

Configure Domino as OIDC provider

Configure Nomad server on Domino with Domino as the OIDC provider by adding the following "oidc" section to nomad-config.yml. Replace with values established in Configuring Nomad server on Domino with Domino as OIDC provider.

nfl section is optional only needed if you want to configure Nomad Federated Login. see Configuring Nomad Federated Login with Domino as OIDC provider.

oidc:
  issuer:
  issuerMetadataOverrides:
    end_session_endpoint:
  client:
    client_id:
    client_secret:
    redirect_uris:
  nfl:
    vaultScope:
    vaultAud:

Configure Access Logging

Nomad server on Domino can be configured to log all http access logs to a rotating file. To enable this, add the following lines to your nomad-config.yml file.

access_log:
  enabled: true

Logs will appear in the IBM_TECHNICAL_SUPPORT folder with the format nomad.access.<date>.log. There will be a maximum of 10 files that are rotated daily. The logs will contain the info-level logging from the https://github.com/rwf2/Rocket rocket http server.

Configuring Server-Side Sessions

Nomad server on Domino manages user-specific data through server-side sessions. The default session size of these sessions can be configured using the session_cache_size parameter.

session_cache_size: 10000

Administrators can monitor session usage with the following command:

tell nomad cache show session

To clear server-side session cache, use:

 tell nomad cache clear session