MTG CLM Autoenrollment Connector Configuration

Application Context Path and Port Numbers

The application contains an embedded Tomcat web server, accessible from an Apache web server via the AJP and HTTP protocols.

The application has its own AJP and HTTP port numbers and its own context path, as follows:

Application	Port Number	Context Path
MTG CLM Autoenrollment Connector	8706 (AJP)	certificate-enrollment-proxy
MTG CLM Autoenrollment Connector	8506 (HTTP)	certificate-enrollment-proxy

Application

Port Number

Context Path

MTG CLM Autoenrollment Connector

8706 (AJP)

certificate-enrollment-proxy

MTG CLM Autoenrollment Connector

8506 (HTTP)

certificate-enrollment-proxy

These port numbers must be defined in the worker.properties file.
Example for the MTG CLM Autoenrollment Connector application: worker.certificate-enrollment-proxy.port=8706

To support DNS name resolution, the application may open ephemeral UDP ports.

Heap Size

Each application starts with a specific heap size.

The heap size is defined in the file /etc/opt/mtg-certificate-enrollment-proxy/`mtg-certificate-enrollment-proxy.service.conf`.

The following table defines the size and the file where the heap size is specified for each application.

Application	File	The maximum heap size	The initial Java heap size
MTG CLM Autoenrollment Connector	mtg-certificate-enrollment-proxy.service.conf	-Xmx512M	-Xms512M

Application

File

The maximum heap size

The initial Java heap size

MTG CLM Autoenrollment Connector

mtg-certificate-enrollment-proxy.service.conf

-Xmx512M

-Xms512M

The heap size must be adjusted to your requirements.

Configuration Files

There is a configuration file application.properties for the Java application.

During initial installation, application.properties is pre-populated with default values inherited from the corresponding configuration templates.

All values must be reviewed and, if necessary, changed to the appropriate values.

The default configuration templates are stored in the directory /etc/opt/<application name>.

After an update installation, the package manager may place a newer version of the configuration files alongside the existing one.

Always compare the standard configuration files with the new version.

If an update requires additional/modified parameters, these must be manually added to the existing configuration files.

Please also check the package’s release notes for any such additional/modified parameters.

Parameters in configuration files are always case-sensitive!

Configuration file

MTG CLM Autoenrollment Connector is a standalone Java application.

The applet’s application.properties file is located in:

/etc/opt/<application name>/application.properties

Server Properties

Table 1. Configuration parameter for server properties
Parameter	Required	Default	Description
server.port	false	8506	Server HTTP port.
server.ssl.enabled	false	true	Enables TLS for SCEP server
server.ssl.enabled-protocols	false	TLSv1.2	Define SSL enabled protocols
server.ssl.key-store	false	classpath:keystore.p12	Path to the server SSL keystore
server.ssl.key-store-type	false	PKCS12	The format used for the keystore. It could be set to JKS in case it is a JKS file
server.ssl.key-store-password	false	-	The password of the keystore (see parameter server.ssl.key-store).
server.ssl.key-alias	false	-	The alias of the keystore entry used
server.ssl.trust-store	false	-	The location of a truststore file containing trusted certificates that are used to verify all TLS connections that the application is initiating.
server.ssl.trust-store-type	false	JKS	The type of the truststore (see parameter server.ssl.trust-store).
server.ssl.trust-store-password	false	-	Trust store password (see parameter server.ssl.trust-store).
server.ssl.client-auth	false	need	SSL client authentication

Tomcat AJP Properties

By default, MTG CLM Autoenrollment Connector is configured to connect to an Apache HTTP server via AJP.

Use the following properties to configure AJP for the embedded Tomcat.

For a description of the properties, see tomcat.apache.org/tomcat-9.0-doc/config/ajp.html.

tomcat.ajp.maxThreads=200 (1)
tomcat.ajp.minSpareThreads=10 (2)
tomcat.ajp.processorCache=200 (3)
tomcat.ajp.secretRequired=false (4)
tomcat.ajp.secret= (5)

1	The maximum number of threads to create for processing requests, thus determining the maximum number of concurrent requests that can be handled.
2	The minimum number of threads that are always running.
3	The protocol handler stores processor objects in the cache to improve performance.

This setting determines how many of these objects are cached.

+ <4> If this attribute is true, the AJP Connector will only start if the "secret" attribute is configured with a non-null value.

The default value is false.

+ <5> Only requests from Apache workers with this secret keyword are accepted.

The default value is null.

This attribute must be specified with a non-null value if secretRequired is explicitly configured to true.

Adjust the secret to match the worker<worker.list.name>.secret defined in worker.properties, see mod_jk Configuration.

If you do not want to use the Tomcat AJP connector with the Apache HTTP server, set tomcat.ajp.enabled to false to disable the Tomcat AJP connector.

The server’s default HTTP port is 8506, and server.address is limited to 127.0.0.1 by default.

With the Tomcat AJP connector disabled, it may be necessary to comment out this restriction if a reverse proxy is used to accept SSL/TLS client connections on another machine, or if Tomcat itself is to accept SSL/TLS client connections.

In the latter case, the keystore and truststore must be configured accordingly.

The keystore and truststore must also be configured if a reverse proxy is used that connects to Tomcat via TLS.

If no client certificate is used for reverse proxy authentication, set server.ssl.client-auth to none.

Table 2. Configuration parameters for Tomcat properties
Parameter	Required	Default	Description
tomcat.ajp.enable	false	false	If set to true, this property enables the additional embedded tomcat ajp connector that is required by Apache HTTPd.
tomcat.ajp.port	false	8706	Specifies the port for the ajp connector. It is used only if tomcat.ajp.enable is set to true.
tomcat.ajp.secret.required	false	false	If set to true, this property specified that an ajp secret is required by the ajp connector. It is used only if tomcat.ajp.enable is set to true.
tomcat.ajp.secret	false	-	Specifies the ajp secret to be used by the ajp connector. It is used only if tomcat.ajp.enable is set to true.

MTG-CLM Integration

MTG CLM Autoenrollment Connector can be integrated with the MTG-CLM to enable certificate management.

To do this, a new API client must first be created.

The client’s secret and provider ID are stored in the application.properties file (see section 4.1).

Here, the client’s provider ID must be set in the clm.apiclient.id property, and the secret in the clm.apiclient.secret property.

The clm.url property must be configured to point to the URL where MTG-CLM is running, or, in the case of multiple CLM instances, to the address of the load balancer.

Additionally, the openid.provider.baseUrl property must be configured to point to the base URL of the Keycloak instance connected to MTG-CLM.

Table 3. Configuration parameters for the CLM properties
Parameter	Required	Default	Description
clm.url	true	-	Points to the HTTP location where the CLM is running.
clm.apiclient.id	true	-	The provider ID that the RA API Client uses for the connection to the CLM. This can be obtained from the CLM when an API client with a default policy is configured. Example: ffc0d281-f9df-45cd-a30d-1881cd67012a
clm.apiclient.secret	true	-	The secret that the RA API Client uses for the connection to the CLM. This can be obtained from the CLM when an API client with a default policy is configured.
openid.provider.baseUrl	true	-	Points to the HTTP location where the Keycloak server is running.
clm.client.truststore.path	false	-	The location of a keystore file containing certificates that are used to verify the TLS connection to the RA. It can be left empty.
clm.client.truststore.password	false	-	The password protecting the truststore (see property clm.client.truststore.path). It can be left empty.
clm.client.truststore.type	false	JKS	The format of the truststore (see property clm.client.truststore.path). Valid values are `JKS`, `JCEKS` or `PKCS12`.
clm.client.tls.version	false	TLSv1.2	The version of the TLS protocol to use in the connection to the CLM. Valid values are `TLSv1.2` or `TLSv1.3`. It can be left empty.
clm.client.timeout.seconds	false	120	An integer value specifying the seconds to timeout the connection to the CLM. It can be left empty.
openid.client.truststore.path	false	-	The location of a keystore file containing certificates that are used to verify the TLS connection to the Keycloak server. It can be left empty.
openid.client.truststore.password	false	-	The password protecting the truststore (see property openid.client.truststore.path). It can be left empty.
openid.client.truststore.type	false	JKS	The format of the truststore (see property openid.client.truststore.path). Valid values are `JKS`, `JCEKS` or `PKCS12`. It can be left empty.
openid.client.tls.version	false	TLSv1.2	The version of the TLS protocol to use in the connection to the Keycloak server. Valid values are `TLSv1.2` or `TLSv1.3`. It can be left empty.
openid.client.timeout.seconds	false	120	An integer value specifying the seconds to timeout the connection to Keycloak server. It can be left empty.
clm.client.http.proxy.host	false	-	Specifies the host of the HTTP proxy server for the connection to CLM. It can be left empty.
clm.client.http.proxy.port	false	-	Specifies the port of the HTTP proxy server for the connection to CLM. It can be left empty.
openid.client.http.proxy.host	false	-	Specifies the host of the HTTP proxy server for the connection to the OpenID server. It can be left empty.
openid.client.http.proxy.port	false	-	Specifies the port of the HTTP proxy server for the connection to the OpenID server. It can be left empty.
policy.mapping.file	false	-	The path of the JSON file for mapping Microsoft certificate templates to CLM policies.
http.connection.pool.maxconnections	false	5	Specifies the maximum number of connections in the connection pool. It affects HTTP connections to CARA, Keycloak, and other certificate provider specific HTTP connections. See also ConnectionPoolSpec.
http.connection.pool.maxidletime	false	20	Specifies the maximum idle time of a connection (in seconds). It affects HTTP connections to CARA, Keycloak, and other certificate provider specific HTTP connections. See also ConnectionPoolSpec.
http.connection.pool.maxlifetime	false	60	Specifies the maximum lifetime of a connection (in seconds). It affects HTTP connections to CARA, Keycloak, and other certificate provider specific HTTP connections. See also ConnectionPoolSpec.
http.connection.pool.pendingacquiretimeout	false	60	Specifies the maximum time after which a pending acquire must be completed (in seconds). It affects HTTP connections to CARA, Keycloak, and other certificate provider specific HTTP connections. See also ConnectionPoolSpec.
http.connection.pool.pendingacquiremaxcount	false	5	Specifies the maximum number of registered requests for acquire to keep in a pending queue. When invoked with -1 the pending queue will not have upper limit. It affects HTTP connections to CARA, Keycloak, and other certificate provider specific HTTP connections. See also ConnectionPoolSpec.
http.connection.pool.evictinbackground	false	60	Specifies the background eviction time (in seconds). If this property’s value is greater than zero, then the connection pool is regularly checked for connections, that are applicable for removal. It affects HTTP connections to CARA, Keycloak, and other certificate provider specific HTTP connections. See also ConnectionPoolSpec.

CEP Server

MTG CLM Autoenrollment Connector also provides the CEP server functionality necessary for auto-enrollment. This uses the certificate templates stored in Active Directory.

An important aspect of the response as a CEP server is the URL at which MTG CLM Autoenrollment Connector can be reached.

Table 4. Configuration parameters for the CEP server properties
Parameter	Required	Default	Description
cep.aecUrl[0]	true	-	The URL at which the AEC can be reached for certificate enrollment.
cep.aecUrl[1]	false	-	The URL at which a second AEC instance can be reached for certificate enrollment.

Client authentication via Kerberos

app.auth.service-principal= (1)
app.auth.keytab-location= (2)

1	The Service Principal Name (SPN) of the application.
2	The path to the keytab file.

The Service Principal Name (SPN) of the application has the following form:

HTTP/<FQDN of the server on which the application is running>

In Active Directory, the SPN must be created using the setspn command, which associates the SPN with a user account.

Example:

setspn -s HTTP/service.example.com sample-service-user

The keytab file must contain an encrypted hash of the password of the user account associated with the SPN.

Access to the keytab file should therefore be restricted.

The keytab file must be generated on a Windows server (not on a Windows client) connected to Active Directory using the following command:

ktpass -out <keytab-path> -mapUser <service-user-account-name>@<domain-name-in-upper-case-letters> +rndPass -mapOp set +DumpSalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -princ <service-principal-name>

Example:

ktpass -out application.keytab -mapUser sample-service-user@EXAMPLE.COM +rndPass -mapOp set +DumpSalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -princ HTTP/service.example.com

Since the application does not use weak encryption algorithms such as DES and RC4 To support Kerberos, the use of AES-128 and AES-256 must be enabled in the Active Directory settings of the user account associated with the SPN.

Table 5. Configuration parameters for Kerberos properties
Parameter	Required	Default	Description
app.auth.service-principal	true	-	The Service Principal Name (SPN) of this service in the form: `HTTP/<FQDN of the server where this service is running>` The Service Principal Name (SPN) of the application.
app.auth.keytab-location	true	-	The path of the keytab file.

Client Authorization

To authorize clients, i.e., whether a certificate may be generated for a request, this can be restricted to a specific group membership in Active Directory. An Active Directory group name can be configured for this purpose, to which the clients must belong.

Table 6. Configuration parameters for authorization properties
Parameter	Required	Default	Description
app.memberOf	false	-	The name of the AD group to which the clients must belong.

LDAP Properties

Properties to access the LDAP server in Active Directory.

LDAP Server Properties

ldap.server.host= (1)
ldap.server.port=-1 (2)

1	The FQDN of the domain controller.
2	The port of the LDAP server; a value less than 0 means that the default port should be used: 389 for ldap and 636 for ldaps.

SSL Properties for Connections to the LDAP Server

The SSL properties for connections to the KMS server.

If these are not set, connections to the LDAP server are not secured by TLS.

ldap.ssl.enabled=false (1)

1	If false, connections to the LDAP server are not secured by TLS.

SSL Truststore Properties

Properties for the truststore, which must contain at least the root certificate.

If you want to trust a self-signed certificate, add it to the truststore.

ldap.ssl.truststore.path=false (1)
ldap.ssl.truststore.type=JKS (2)
ldap.ssl.truststore.password= (3)

1	The path to the truststore file.
2	The type of truststore file, JKS or PKCS12.
3	The password for the truststore file.

Must be set if path is set.

Properties for LDAP Server Authentication

ldap.auth.service-principal= (1)
ldap.auth.keytab-location= (2)
ldap.auth.qop= (3)

1	The principal name of the user who performs the LDAP queries.
2	The path to the keytab file.
3	The SASL protection mechanisms.

The principal name of the user performing the LDAP queries has the following form:

<LDAP user account name>@<domain name in uppercase>

Example:

ldap-user@EXAMPLE.COM

In Active Directory, this user must have read and write permissions to the LDAP entries to retrieve additional user and computer information when a certificate is requested and to store newly issued certificates in LDAP.

The keytab file must contain an encrypted hash of the LDAP user account password.

Access to the keytab file should therefore be restricted.

The keytab file must be generated on a Windows server (not on a Windows client) connected to Active Directory using the following command: The warnings issued can be ignored:

ktpass -out <keytab-path> -mapUser <LDAP user's account name>@<domain name in uppercase> +rndPass -mapOp set +DumpSalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -princ <LDAP user's principal name>

Example:

ktpass -out ldap.keytab -mapUser ldap-user@EXAMPLE.COM +rndpass -mapOp set +DumpSalt -crypto AES256-SHA1 -pType KRB5_NT_PRINCIPAL -princ ldap-user@EXAMPLE.COM

Since the application does not support weak encryption algorithms such as DES and RC4, the use of these must be disabled in the LDAP user account settings in Active Directory. AES-128 and AES-256 encryption must be enabled.

LDAP Search Properties

ldap.search.baseDN= (1)

1	The BaseDN in the form:

DC=domain,DC=top-level domain

Example:
DC=example,DC=com

LDAP Connection Pool Properties

A connection pool is used

if its use is enabled and
if no TLS connections are used or
the default truststore is used.

ldap.connection-pool.enabled=true (1)
ldap.connection-pool.init-size=1 (2)
ldap.connection-pool.max-size= (3)
ldap.connection-pool.pref-size= (4)
ldap.connection-pool.timeout= (5)

1	Specifies whether the connection pool is enabled.
2	Specifies the number of connections to be created initially.
3	Specifies the maximum number of connections to be created.
4	Specifies the preferred number of connections to be created.
5	Specifies the duration that an unused connection remains in the connection pool before it is closed and removed (resolution: milliseconds).

Unlike the Oracle documentation for LDAP Connection Pools, the value here can be specified in a Chrono unit, e.g., 30s.

The default Chrono unit is ms (milliseconds).

See Units Configuration for supported Chrono units.

All LDAP Properties

Table 7. Configuration parameters for LDAP properties
Parameter	Required	Default	Description
ldap.server.host	true	-	Full qualified domain name (FQDN) of the LDAP server.
ldap.server.port	false	8506	Server HTTP port.
ldap.ssl.enabled	false	true	Indicates whether the connection to the LDAP server shall be secured by TLS.
ldap.ssl.trust-store	false	-	The location of a keystore file containing certificates used to verify the LDAP server.
ldap.ssl.trust-store-type	false	JKS	The type of the truststore (see parameter ldap.ssl.trust-store).
ldap.ssl.trust-store-password	false	-	Trust store password (see parameter ldap.ssl.trust-store).
ldap.auth.service-principal	true	-	The Principal Name of the user to use for LDAP requests in the form: `<LDAP user’s account name>@<domain name in upper case letters>`
ldap.auth.keytab-location	true	-	The location / path of the keytab file for the LDAP authentication.
ldap.search.baseDN	true	-	The LDAP search baseDN in the form `DC=<domain>,DC=<top level domain>`
ldap.connection-pool.enabled	false	-	Indicates whether using a connection pool is enabled.
ldap.connection-pool.init-size	false	1	The number of connections to create initially.
ldap.connection-pool.max-size	false	-	The maximum number of connections that can be maintained concurrently.
ldap.connection-pool.pref-size	false	-	The preferred number of connections that should be maintained concurrently.
ldap.connection-pool.timeout	false	-	The duration an idle connection may remain in the pool without being closed and removed from the pool.
ldap.auth.qop	false	auth	Specifies the SASL protection mode to be used. Please note that the modes specified here must also be supported by the windows domain controllers. See also QOP

OpenSearch Properties

Table 8. Configuration parameters for OpenSearch properties
Parameter	Required	Default	Description
management.elastic.metrics.export.enabled	false	-	If set to true then metrics are sent to an OpenSearch server. It can be left empty.
management.elastic.metrics.export.host	false	-	Specifies the URL where the OpenSearch server can be accessed. It can be left empty.
management.elastic.metrics.export.user-name	false	-	Specifies the user who has access to the OpenSearch server. It can be left empty.
management.elastic.metrics.export.password	false	-	Specifies the password of the user of the OpenSearch server. It can be left empty.

Apache Configuration

You can deploy Apache in front of your MTG applications to terminate the TLS connection and/or as a load balancer.

You can use your distribution’s default package or the MTG-httpd package (recommended).

The default configuration for the MTG-httpd package is located in /etc/opt/apache2/

SSL/TLS Configuration

If you are running multiple applications on the same machine, you can bind the application to the loopback network interface and use the following Apache configuration to terminate TLS:

SSLEngine on
SSLCertificateFile /etc/opt/apache2/ssl.cert/server.crt
SSLCertificateKeyFile /etc/opt/apache2/ssl.key/server.key.private
SSLCACertificateFile /etc/opt/apache2/ca/ca.crt
SSLOptions +ExportCertData +StrictRequire +StdEnvVars

<Location /<CONTEXT>/>
 SSLRequireSSL
</Location>

JkMount /<CONTEXT>* <ajp_worker_name>
JkMount /<CONTEXT>/* <ajp_worker_name>

Where:

SSLOptions: Sets additional required options for SSL
server.crt / server.key.private: Is the Apache web server certificate/key
ca.crt: Is the certificate of the server certificate issuer
CONTEXT: Is the context to be used by the application. Corresponds to server.servlet.context-path in application.properties (standard applications) or Context path in the Tomcat server.xml.
ajp_worker_name: Corresponds to the mod_jk handler name defined in workers.properties.

Einige Anwendungen erfordern eine gegenseitige TLS-Authentifizierung (Client-Zertifikate). In diesem Fall sieht die apache location-config wie folgt aus:

<Location /<CONTEXT>>
    SSLRequireSSL
    SSLVerifyClient optional
    SSLVerifyDepth 2
</Location>

Wobei :

SSLVerifyClient: erzwingt TLS-Client-Authentifizierung
SSLVerifyDepth: maximale Anzahl von Zwischen-CAs

mod_jk Configuration

mod_jk is used to communicate with a Tomcat servlet runner via AJP.

Most MTG server applications either run in a central Tomcat instance or include their own Tomcat instance (standalone applications).

Please refer to the product/package description for further details.

mod_jk must be loaded in httpd.conf: LoadModule jk_module modules/mod_jk.so

The following configuration example shows how to configure mod_jk in Apache httpd:

JkWorkersFile /etc/opt/apache2/workers.properties
JkLogFile /var/log/apache/mod_jk.log
JkLogLevel warn
JkOptions +ForwardKeySize +ForwardURIProxy -ForwardDirectories
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkShmFile /usr/local/apache2/logs/mod_jk.shm

Where:

JkWorkersFile: is the path to the file workers.properties.
JkLogFile: is the path to the log file of the mod_jk module * JkLogLevel: is the log volume of mod_jk * JkOptions: adds additional options for mod_jk * JkLogStampFormat: defines the log format * JkShmFile: defines the path to the status file

The referenced file workers.properties could look like this: Appearance:

worker.list=firstworker,secondworker

worker.firstworker.type=ajp13
worker.firstworker.host=127.0.0.1
worker.firstworker.port=8009
worker.firstworker.secret=PASSWORD

worker.secondworker.type=ajp13
worker.secondworker.host=127.0.0.1
worker.secondworker.port=8010
worker.secondworker.secret=PASSWORD2

Adjust the worker port to match the "server.port" defined in the "application.properties" file (for standalone applications) or the AJP connector port of your running Tomcat instance.
The secret corresponds to the tomcat.ajp.secret defined in the application.properties file (standalone applications) or the AJP connector secret of your running Tomcat instance.

Encryption

A certificate is required for the SSL connection between MTG CLM Autoenrollment Connector and the external caller.

The configuration for the SSL certificate with private key and chain is included in the apache-config.