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.
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.
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 | Remarks |
|---|---|
| env.conf | 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 the $ must be escaped.
For more on expressions see Standalone nevisauth.yml expression]. Example: CLASSPATH="/var/opt/nevisauth/<instance>/lib/:"*
| Configuration file | Remarks |
|---|---|
| nevisauth.yml | Server configuration: Scaling (concurrency with worker threads) Network settings (host, port, protocol, tls, ...) |
| log4j.xml | Logging configuration: Configuration of log levels for in Audit channel (if the file rotation policy or output file needs to be customized) |
| esauth4.xml | 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 | Contains the built-in language support for the default esauth4.xml configuration. See for details. |
| esauth4.security | 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 | 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 | This configuration file is required by the Kerberos support of Java.See. |
| kerberos-credentials.properties | 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 theserver.tls.require-client-auth: truesetting. It means that client authentication is required. "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 theserver.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 not enough information: You can verify the IP address only, because the hostname is not available. Therefore, to use the hostname verification feature in a Nevis TLS setup, the client (that is, nevisProxy) needs a fixIP address. Alternatively, regenerate the certificates each time the IP address changes.It is recommended leaving this configuration disabled, that is, setting the property server.tls.verify-hostnameto "false". Instead, enable the client-side hostname verification in the EsAuth4ConnectorServlet of nevisProxy. For more information, see the chapter "EsAuth4ConnectorServlet" in the nevisProxy reference guide.If you set this property to "true", you may need to regenerate the client certificates used to connect to nevisAuth. See the section Creating Self-Signed Certificates with Subject Alternative Names] 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 the IP only, notthe 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