Identity Gateway 7.2

ServerTlsOptions

When IG is server-side, applications send requests to IG or request services from IG. IG is acting as a server of the application, and the application is acting as a client.

ServerTlsOptions configures the TLS-protected endpoint when IG is server-side.

In standalone mode, use ServerTlsOptions in admin.json.

Usage

{
  "type": "ServerTlsOptions",
  "config": {
    "keyManager": [ KeyManager reference, ...], // Use "keyManager" or
    "sni": object,                              // "sni", but not both
    "trustManager": [ TrustManager reference, ...],
    "sslCipherSuites": [ configuration expression<string>, ...],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, ...],
    "alpn": object,
    "clientAuth": configuration expression<enumeration>,
  }
}

Properties

Either sni or keyManager must be configured. When both are configured, sni takes precedence and a warning is logged. When neither is configured, an exception is thrown and a warning is logged.

"sni": object, required if keyManager is not configured

Not supported in web container mode.

Server Name Indication (SNI) is an extension of the TLS handshake, to serve different secret key and certificate pairs to the TLS connections on different server names. Use this property to host multiple domains on the same machine. For more information, see Server Name Indication.

During a TLS handshake, vert.x accesses secret key and certificate pairs sychronously; they are loaded in memory at IG startup, and must be present. You must restart IG to update a secret key and certificate pair.

For an example that uses this property, see Serve different certificates for TLS connections to different server names.

{
  "sni": {
    "serverNames": map,
    "defaultSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
  }
}
serverNames: map of configuration expression<string>:configuration expression<secret-id>, required

A map of server name to secret ID:

  • The server name is the name of server provided during TLS handshake

  • The secret ID represents the secret key and certificate pair to use for that server

    "serverNames": {
  "app1.example.com": "my.app1.secretId",
  "app2.example.com": "my.app2.secretId",
  "*.test.com": "my.wildcard.test.secretId"
}
    "serverNames": {
  "${server.name.available.at.config.time}" : "${secret.id.available.at.config.time}"
}

Note the following points:

  • One server cannot be mapped to multiple certificates.

    IG cannot provide multiple certificates for the same server name, as is allowed by Java’s KeyManagers.

  • Multiple servers can be mapped to one certificate.

    Map server names individually. In the following configuration, both server names use the same certificate:

    "serverNames": {
  "cat.com" : "my.secret.id",
  "dog.org" : "my.secret.id"
}

    Use the * wildcard in the server name to map groups of server names. In the following configuration, app1.example.com and app2.example.com use the same certificate:

    "serverNames": {
  "*.example.com": "my.wildcard.secret.id"
}
"defaultSecretId": configuration expression<secret-id>, required

The secret ID representing the certificate to use when an unmapped server name is provided during TLS handshake.

For information about how IG manages secrets, see Secrets.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for each secret ID. For more information, see SecretsProvider.

"keyManager": array of KeyManager references, required if sni is not configured

One or more KeyManager objects to serve the same secret key and certificate pair for TLS connections to all server names in the deployment. Key managers are used to prove the identity of the local peer during TLS handshake, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the KeyManagers to which ServerTlsOptions refers are used to prove this IG’s identity to the remote peer (client-side). This is the usual TLS configuration setting (without mTLS).

  • When ClientTlsOptions is used in a ClientHandler or ReverseProxyHandler configuration (client-side), the KeyManagers to which ClientTlsOptions refers are used to prove this IG’s identity to the remote peer (server-side). This configuration is used in mTLS scenarios.

    Provide the name of one or more of the following objects defined in the heap, or configure one or more of the following objects inline:

Default: None

"sslCipherSuites": array of configuration expression<strings>, optional

Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.

For information about the available cipher suite names, see the documentation for the Java Virtual Machine (JVM). For Oracle Java, see the list of JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

"sslContextAlgorithm": configuration expression<string>, optional

The SSLContext algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine (JVM).

Default: TLS

"sslEnabledProtocols": array of configuration expression<strings>, optional

Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.

For information about the available protocol names, see the documentation for the Java Virtual Machine (JVM). For Oracle Java, see the list of Additional JSSE Standard Names.

Follow these protocol recommendations:

  • Use TLS 1.3 when it is supported by available libraries, otherwise use TLS 1.2.

  • If TLS 1.1 or TLS 1.0 is required for backwards compatibility, use it only with express approval from enterprise security.

  • Do use deprecated versions SSL 3 or SSL 2.

Default: TLS 1.3, TLS 1.2

"trustManager": array of TrustManager references, optional

One or more of the following TrustManager objects to manage IG’s public key certificates:

Trust managers verify the identity of a peer by using certificates, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the TrustManagers to which ServerTlsOptions refers are used to verify the remote peer’s identity (client-side). This configuration is used in mTLS scenarios.

  • When ClientTlsOptions is used in a ClientHandler or a ReverseProxyHandler configuration (client-side), the TrustManager to which ClientTlsOptions refers are used to verify the remote peer’s identity (server-side). This is the usual TLS configuration setting (without mTLS).

If trustManager is not configured, IG uses the default Java truststore to verify the remote peer’s identity. The default Java truststore depends on the Java environment. For example, $JAVA_HOME/lib/security/cacerts.

Default: None

"alpn": object, optional

Not supported in web container mode.

A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections.

{
  "alpn": {
    "enabled": configuration expression<boolean>
  }
}
enabled: configuration expression<boolean>, optional

  • true: Enable ALPN. Required for HTTP/2 connections over TLS

  • false: Disable ALPN.

Default: true

"clientAuth": configuration expression<enumeration>, optional

The authentication expected from the client. Use one of the following values:

  • REQUIRED: Require the client to present authentication. If it is not presented, then decline the connection.

  • REQUEST: Request the client to present authentication. If it is not presented, then accept the connection anyway.

  • NONE: Accept the connection without requesting or requiring the client to present authentication.

Default: NONE

Example

See the following examples that use ServerTlsOptions: