Deployment Types
nevisAuth supports multiple deployment types and multiple instances. The deployment type can be defined per instance. nevisAuth instances can be conveniently created using The administrative command-line interface.
Instance creation example
nevisauth inst create <instance> AUTH_DEPLOY_TYPE=<selectedDeploymentType>
Deployment type requirements and recommendations
- The standalone deployment type requires OpenJDK 1.8.0. The standalone deployment type is available on Red Hat Enterprise Linux 7, SUSE Linux Enterprise Server 12 and the nevisAppliance.
- The JBoss 5 deployment type requires adnjboss 5.1.6.1 and adnjdk18. The JBoss 5 deployment type is available on all supported operating systems.
- The WildFly 10 deployment type requires adnwildfly. The WildFly 10 deployment type is available on Red Hat Enterprise Linux 7, SUSE Linux Enterprise Server 12 and the nevisAppliance.
Recommendation
We recommend using the standalone deployment mode. The WildFly 10 deployment type is considered as experimental.Standalone
The standalone deployment type uses an embedded container. There is no need to install a separate container.
The standalone deployment type is the default deployment type for nevisAuth. If AUTH_DEPLOY_TYPE is not set during instance creation, the instance will be set up based on the standalone deployment type. To explicitly specify the usage of the standalone deployment type during instance creation (or handover), set the AUTH_DEPLOY_TYPE variable to *AUTH_DEPLOY_TYPE=standalone*.
The following configuration files control the behavior of nevisAuth in the standalone deployment type:
| Configuration file | Deployment type | Remarks |
|---|---|---|
| env.conf | all | Administration command and process environment: *JAVA_HOME (optional): use specified JRE/JDKAll other parameters should not be changed. * JAVA_OPTS: JVM command-line options The JAVA_OPTS environment variable can be an expression that will be replaced. |
Example 1: (using single quotes)
JAVA_OPTS=(
'-server'
'-Djavax.net.ssl.keyStorePassword=${exec:cat /var/opt/pwd.txt}'
)
Example 2: (using double quotes)
JAVA_OPTS=(
"-server"
"-Djavax.net.ssl.keyStorePassword=\${exec:cat /var/opt/pwd.txt}"
)
Old string syntax: (cannot handle spaces in JVM arguments and inline comments)
JAVA_OPTS="-server \
-Djavax.net.ssl.keyStorePassword=\${exec:cat /var/opt/pwd.txt}"
If you use double quotes, escape the '$' sign.
For more on expressions, see Standalone nevisauth.yml expression]. Example: CLASSPATH="/var/opt/nevisauth/<instance>/lib/:"*
| Configuration file | Deployment type | Remarks |
|---|---|---|
| nevisauth.yml | all | Server configuration: Scaling (concurrency with worker threads) Network settings (host, port, protocol, tls, ...) |
| log4j.xml | all | Logging configuration: Configuration of log levels for in Audit channel (if the file rotation policy or output file needs to be customized) |
| esauth4.xml | all | The SessionCoordinator and AuthEngine are configured in the esauth4.xml file. The schema esauth4.dtd is used to validate this configuration. It contains a complete reference to all possible configuration attributes as well as the values for the built-in defaults. |
| LitDict.propertiesLitDict_de.propertiesLitDict_fr.properties**LitDict_it.properties | all | Contains the built-in language support for the default esauth4.xml configuration. See for details. |
| esauth4.security | all | Additional Java cryptographic providers to be loaded for HSM support. The following providers are supported: Sun Java 1.5 PKCS#11 provider (limited support due to implementation restrictions, e.g., keys and certificates with different labels and multiple copies of the same certificate are not supported) IBM PKCS#11 provider. We recommend adding additional PKCS#11 providers with low priority to prevent side effects. |
| pkcs11.cfg | all | This file is referenced by esauth4.security if the JRE PKCS#11 layer needs to be configured. It contains vendor specific driver settings (PKCS#11 driver library to load, special settings how JRE should access the driver). |
| java-krb5.conf | all | This configuration file is required by the Kerberos support of Java.See. |
| kerberos-credentials.properties | all | This configuration file is required by the FrontendKerberosAuthState.See. |
The configuration files are located here:
- /var/opt/nevisauth/
<instance>/conf
Environment configuration
As the first priority, nevisAuth uses the Java installation defined in the file env.conf using the configuration property JAVA_HOME. If the JAVA_HOME property is not defined in the file env.conf, the Java version as defined in the PATH environment variable is used.
To define the usage of a specific Java installation, we recommend setting the configuration property JAVA_HOME in the file env.conf:
Example
JAVA_HOME=/etc/alternatives/jre_1.8.0
Server configuration properties
You can configure the server of the standalone deployment type through the properties in the file nevisauth.yml (see the in the property names represents one level of indentation in the nevisauth.yml YAML file. For example, server.tls.keystore is represented as follows in the YAML file:
YAML format
server:
tls:
keystore: /var/opt/keybox/default/node_keystore.jks
| Name | Example value | Default value | Remarks |
|---|---|---|---|
| server.name | <instance> | Name of the server. Give each server a unique name for the sake of identification. This name will also be logged. | |
| server.protocol | https | https | Enumeration: https, http(info) Set this property to "https" if you plan to use TLS. |
| server.port | 8991 | 8991 | Configures the port where the server will listen for incoming authentication requests |
| server.host | localhost | Configures the hostname on which the server will listen for incoming authentication requests | |
| server.tls.keystore | /var/opt/keybox/default/node_keystore.jks | Keystore object used for the TLS | |
| server.tls.keystore-passphrase | keystorepassword | ||
| server.tls.truststore | /var/opt/keybox/default/truststore.jks | Truststore object used for the TLS | |
| server.tls.truststore-passphrase | truststorepassword | ||
| server.tls.client-auth | required | disabled | Enumeration: required, requested, disabled- "required" is the successor of the server.tls.require-client-auth: true setting. It requires client authentication. - "requested" allows client authentication if the client certificate is sent. In case the client certificate was not sent, no client authentication will be performed.- "disabled" is the successor of the server.tls.require-client-auth: false setting. |
| server.tls.verify-hostname | true | false | If set to "true" and a two-way TLS connection is required, the server verifies that the IP address in the certificate presented by the client matches the IP address of the client. (info) The IP address is specified in the Subject Alternative Names field of the certificate.(info) A required two-way TLS connection corresponds with the following setting: server.tls.client-auth="required"In the TLS connection setups of Nevis, nevisProxy acts as a client whereas nevisAuth acts as a server. Hostname verification is a client-side feature by design, which allows for a stricter verification of the server identity. On the server side, there is is not included in the certificates by default. |
| server.tls.supported-protocols | TLSv1.2 | TLSv1.2 | Provides a list of protocols that are accepted by the client when trying to initiate a connection with TLS. |
| server.tls.cipher-suites | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | Provides a list of ciphers that are accepted by the client when trying to initiate a connection with TLS.The cipher name format is the one used in the Java Cryptography Architecture Oracle Providers Documentation for JDK 8. |
| server.max-threads | 200 | 200 | Number of threads used to process incoming requests |
| server.max-http-header-size | 16384 | 8192 (8 kilobytes) | Defines the maximum size in bytes of the request and response HTTP headers.Larger headers allow for more and/or larger cookies as well as more form content encoded in a URL. However, larger headers consume more memory and can make a server more vulnerable to denial of service attacks. |
| management.server.port | 9000 | 9000 | The port where the server exposes the liveness endpoint used by Kubernetes. Currently only HTTP is supported. This property is experimental and can change in future releases. |
| management.healthchecks.enabled | false | false | Shows whether the Integration with Kubernetes (liveness) is enabled. This property is experimental and can change in future releases. |
The property values in the file nevisauth.yml can be expressions that will be replaced. The next table shows the available syntax:
| Syntax | Example | Remarks |
|---|---|---|
| ${exec:command} | server.tls.keystore-passphrase: ${exec:/var/opt/keys/own/instance/keypass.sh}server.host: ${exec:hostname -f} | Executes the given command and uses its output as the value |
| ${env:variablename} | server.host: ${env:HOSTNAME} | Uses the value of the specified environment variable |
Standalone server command-line interface
For standalone deployments, the standalone command-line interface ) or by the user directly.
Use the standalone CLI to start nevisAuth without involvement of other system components like for example systemd.
You find the standalone script at /opt/nevisauth/bin/nevisauth-server. It provides the next command line options:
| Command line argument | Remarks | Default |
|---|---|---|
| -c, --config PATH | Required. Path to the configuration file nevisauth.yml. | No default |
| -n, --name NAME | Unique name for that Nevis component node.Overrides the value of the property server.name (in the nevisauth.yml file). | See the server.name property in the nevisauth.yml file. |
| -p, --port PORT | The HTTP/S port to listen on. TLS must be configured in the config file and not as an argument.Overrides the value of the property server.port (in the nevisauth.yml file). | See the server.port property in the nevisauth.yml file. |
| -H, --host HOST | The HTTP/S host to bind on. By default binds on all IPv4 and IPv6 interfaces.Overrides the value of the property server.host (in the nevisauth.yml file). | See the server.host property in the nevisauth.yml file. |
| --log-config PATH | Log configuration file to be used.If a log configuration is provided, nevisAuth will use the given configuration file to determine how logging should behave. If no configuration file is provided, nevisAuth will log to the console by default. | Not set |
| -V, --version | Display version and exit with status code 0. | |
| -h, --help | Show complete and detailed usage and exit with status code 0. |
Command-line arguments always prevail over the configuration in the nevisauth.yml file!
Example usage of the standalone CLI
To start an existing nevisAuth instance named "default" without using systemd to manage the service, set the following commands:
# set working directory
cd /var/opt/nevisauth/default
/opt/nevisauth/bin/nevisauth-server --config /var/opt/nevisauth/default/conf/nevisauth.yml --log-config /var/opt/nevisauth/default/conf/log4j.xml
Creating Self-Signed Certificates with Subject Alternative Names (SAN)
The commands in the following code block generate certificates that you can use in a test environment including a nevisAuth instance with two-way client authentication and hostname verification.
The neviskeybox command creates a keystore with two Subject Alternative Names (SANs): One of type DNS, and the other of type IP. You can use this keystore in nevisProxy to connect to nevisAuth.
Note that nevisAuth uses the DNS name in the SAN to verify only the IP, not the client identity.
The following code sample shows the correct syntax:
neviskeybox certreq -slot default -label node -subject 'cn=siven.ch,ou=auth,o=o=nevis-security,dc=com' -subjectAltName 'DNS:siven.ch,IP:10.0.0.1'
neviskeybox sign -ca testCA -out /tmp/node_new_cert.pem -file /var/opt/keybox/default/node_request.pem
neviskeybox import -file /tmp/node_new_cert.pem
neviskeybox access -slot default -label node -group nvbgroup -user nvpuser
neviskeybox passwd -keep -slot default -label node
JBoss 5
The JBoss 5 deployment type uses an adnjboss container. You specify the usage of a JBoss 5 deployment type during instance creation (or handover) by setting the AUTH_DEPLOY_TYPE variable to AUTH_DEPLOY_TYPE**=adnjboss.
The following configuration files control the behavior of nevisAuth in the JBoss 5 deployment type:
| Configuration file | Deployment type | Remarks |
|---|---|---|
| env.conf | all | Administration command and process environment: JAVA_HOME (optional): Use specified JRE/JDK. All other parameters should not be changed.File location:/var/opt/nevisauth/<instance>/conf/env.confwill be copied to/var/opt/adnjboss/<instance>/conf/env.conf.* |
| vmargs.conf | all | JVM environment (JVM command-line options): Heap size Garbage collector JSSE configuration properties JNDI configuration properties |
| server.xml | JavaEE (tomcat5) | Server configuration: Scaling (concurrency with worker threads) Network adapters (called connectors in tomcat, e.g., HTTP or HTTPS) |
| log4j.xml | all | Logging configuration: All tracing (if JavaEE deployment is used). Recommended settings:jcan.Op=INFO(performance tracing in production)AuthEngine=DEBUG(debug tracing for authentication processing) Audit channel (if file rotation policy or output file needs to be customized) |
| esauth4.xml | all | SessionCoordinator and AuthEngine are configured in the esauth4.xml file. The schema esauth4.dtd is used to validate this configuration. It contains a complete reference of all possible configuration attributes as well as the values for the built-in defaults. |
| LitDict.properties**LitDict_de.properties LitDict_fr.properties LitDict_it.properties | all | Contains the built-in language support for the default esauth4.xml configuration. See for details. |
| esauth4.security | all | Additional Java cryptographic providers to be loaded for HSM support. The following providers are supported: Sun Java 1.5 PKCS#11 provider (limited support due to implementation restrictions, e.g., keys and certificates with different labels and multiple copies of the same certificate are not supported) IBM PKCS#11 provider. We recommend adding additional PKCS#11 providers with low priority to prevent side effects. |
| pkcs11.cfg | all | This file is referenced by esauth4.security if the JRE PKCS#11 layer needs to be configured. It contains vendor specific driver settings (PKCS11 driver library to load, special settings how JRE should access the driver). |
| java-krb5.conf | all | This configuration file is required by the Kerberos support of Java.See. |
| kerberos-credentials.properties | all | This configuration file is required by the FrontendKerberosAuthState.See. |
Configuration files are located here:
- /opt/nevisauth/template/conf (default configuration for the JBoss and WildFly setup)
- /var/opt/nevisauth/
<instance>/conf (instance configuration) WildFly 10
Deployments based on WildFly 10 are considered experimental.
The WildFly 10 deployment type uses an adnwildfly container. You may specify the usage of the adnwildfly container during instance creation (or handover) by setting the AUTH_DEPLOY_TYPE variable to AUTH_DEPLOY_TYPE**=adnwildfly.
The following configuration files control the behavior of nevisAuth in the WildFly deployment type:
| Configuration file | Deployment type | Remarks |
|---|---|---|
| env.conf | all | Administration command and process environment: JAVA_HOME (optional): use specified JRE/JDKAll other parameters should not be changed. File location:/var/opt/adnwildfly/instances/<instance>/standalone/configuration/env.conf* |
| vmargs.conf | all | JVM environment (JVM command-line options): Heap size Garbage collector JSSE configuration properties JNDI configuration properties |
| standalone.xml | all | Part of adnwildfly. Used for the configuration of application server parameters such as extensions, profiles and subsystems, paths, interfaces, socket bindings and socket binding groups, system properties, etc. |
| log4j.xml | all | Logging configuration: All tracing (if JavaEE deployment is used). Recommended settings:jcan.Op=INFO(performance tracing in production)AuthEngine=DEBUG(debug tracing for authentication processing) Audit channel (if the file rotation policy or output file needs to be customized) |
| esauth4.xml | all | The SessionCoordinator and AuthEngine are configured in the esauth4.xml file. The schema esauth4.dtd is used to validate this configuration. It contains a complete reference to all possible configuration attributes as well as the values for the built-in defaults. |
| LitDict.propertiesLitDict_de.propertiesLitDict_fr.properties**LitDict_it.properties | all | Contains the built-in language support for the default esauth4.xml configuration. See for details. |
| esauth4.security | all | Additional Java cryptographic providers to be loaded for HSM support. The following providers are supported: Sun Java 1.5 PKCS#11 provider (limited support due to implementation restrictions, e.g., keys and certificates with different labels and multiple copies of the same certificate are not supported) IBM PKCS#11 provider. We recommend adding additional PKCS#11 providers with low priority to prevent side effects. |
| pkcs11.cfg | all | This file is referenced by esauth4.security if the JRE PKCS#11 layer needs to be configured. It contains vendor specific driver settings (PKCS#11 driver library to load, special settings how JRE should access the driver). |
| java-krb5.conf | all | This configuration file is required by the Kerberos support of Java.See. |
| kerberos-credentials.properties | all | This configuration file is required by the FrontendKerberosAuthState.See. |
Configuration files are located here:
- /var/opt/nevisauth/
<instance>/conf (instance configuration) - /var/opt/adnwildfly/instances/
<instance>/standalone/configuration (server configuration)