Control how the Servers are configured during installation by editing the properties contained in the nnl-install.properties file. This file specifies directory locations, hostname and port numbers for the nodes, database properties, tenant properties, as well as information to support out-of-band (OOB) authentication. This installer script contains detailed comments describing each property.
Refer to the Sample nnl-install.properties file to see a finished installer script.
Edit <NNL_HOME>/install/nnl-install.properties for your configuration and required properties:
A. Assign Server-related Properties
Property | Description |
|---|---|
ACCEPT_NNL_LICENSE_ENV | Mandatory. Boolean. Indicates acceptance of the Server licensing agreement. Must be true for the Server to work. |
JAVA_HOME_ENV | Mandatory. The full path to the JDK install directory. |
NNL_ADMIN_URL_ENV | Mandatory. The hostname and port number of your Admin node. |
NNL_CLEANUP_ENV | Optional. Whether cleanup is required after installation.
|
NNL_CRYPTO_PLUGIN_CLASS_NAME | Optional. Specifies the Crypto Plugin class name used to encrypt/decrypt data. For example: com.noknok.uaf.crypto.internal.handlers.SampleCryptoPlugin |
NNL_EXT_DIR_PATHS | Optional. A comma-separated list of directories containing custom libraries (or custom data encryption plugins). Supports encryption of data at rest. Ask Nok Nok Customer Support for Data at Rest Encryption Configuration Technical Note for details about implementing encryption. |
NNL_INSTALL_DIR_ENV | Mandatory. The full path to the Server installation root directory. Typically where you extracted the server tar file. |
NNL_INSTALL_MODE_ENV | Optional. Indicates your desired installation type, production or non-production. Use non-production for evaluation, development, testing, or staging. Leave this blank (default) for a non-production installation. Set this to "production" for a production installation. |
NNL_JAVA_OPTS_PROPERTIES | Optional. Specifies the JAVA, CATALINA, nnl.restrict.input. field.regex and other system properties. These properties are required for Java and web applications. The values are used by setenv.sh and other NNL internal scripts. Multiple properties can be set with a blank space as delimiter. |
NNL_JS_APPSDK_URL | Optional. Specifies the hostname and port number of your Nok Nok JS AppSdk. The origin for NNL_JS_APPSDK_URL and the API_SERVER_URL should be the same. If they are different, then you must set up Cross-Origin Resource Sharing between the two origins. Example value: https://nnlapi.example.com/nnljs |
NNL_SECRETS_PLUGIN_CLASS_NAME | Optional. Specifies the Secrets plugin class name. If a Secrets Plugin is deployed, do one of the following:
|
NNL_SERVER_URL_ENV | Mandatory. The host name and port number of the Runtime node (or Auth Server). If you have a load balancer before your runtime nodes, use the load balancer’s hostname and port: https://<load-balancer-hostname>.<domain-name>:<port>. |
TOMCAT_INSTALL_DIR_ENV | Mandatory. The full path to the Tomcat install directory. |
B. Assign Log Properties
During installation, you can select an appropriate logging level for your needs that balances the amount of information captured with the troubleshooting you have to do. You can also specify the time zone to use when the date and time are saved in a log entry.
Property | Description |
|---|---|
NNL_LOG_LEVEL_FOR_PROD | Controls the logging level for the diagnostic log (nnl.log), an invaluable tool for troubleshooting production installations. Defaults to ERROR for production installations and INFO for development installations.
|
NNL_LOGS_DATETIME_FORMAT | The specified format and time zone to use for diagnostic log entry timestamps (nnl.log). Defaults to {ISO8601}{UTC}. The value must be a valid Java time zone string, examples include:
|
NNL_ENABLE_ACCESS_LOG | Enable structured access logs that record requests and responses made to the Auth Server and the API Server. Defaults to false. Example: NNL_ENABLE_ACCESS_LOG=true Auth Server access log: <TOMCAT_HOME>/logs/nnl-access.log API Server access log: <TOMCAT_DIR>/logs/nnlgateway-access.log |
NNL_ACCESS_LOG_REQUEST_HEADER_FILTER | A CSV list of Server request headers that you don't want included in the access logs. By default, all request headers are logged. In this example, these 4 request headers are filtered out of the access logs. Example: NNL_ACCESS_LOG_REQUEST_HEADER_FILTER=postman-token,host,accept-encoding,path |
C. Assign Database-connection-related Properties for the Operational Database
Property | Description |
|---|---|
DB_ADDITIONAL_PROPS_ENV | Optional. Specifies the additional JDBC connection properties if required for the database. These properties are key/value pairs with a semicolon as delimiter. |
DB_ENCRYPTED_USER_PASSWD_ENV | Required if you are not using the Secrets plugin. The Authentication Server uses this password to access the Operational Database. Enter encrypted password. To encrypt the password, follow steps in Step 4. Encrypt Credentials Used by the Server. |
DB_SECRET_HANDLE_ENV | Optional. If you are using the Secrets plugin, then this property specifies the handle for the operational database password in your external secrets manager. Prefix the handle with {handle}. For example, DB_SECRET_HANDLE_ENV={handle}runtimedb.password.handle |
DB_TYPE_ENV | Required. The type of database that you are using: oracle, mysql, cockroachdb, or postgres. |
DB_USER_NAME_ENV | Required. The Operational Database user name. |
SKIP_DB_SCHEMA_CREATION | Optional. Tells the installer whether database setup is required or not.
|
DB_DRIVER_CLASS_NAME_ENV | Optional. Specifies the database driver class name. If you use the standard JDBC drivers such as PostgreSQL JDBC Driver, MySQL Connector/J, or Oracle JDBC Driver, then nnl-install.sh configures this property automatically. Configure this property if you want to use a custom JBDC driver. For example, to use an AWS JDBC Wrapper, configure this property to software.amazon.jdbc.Driver. |
If SKIP_DB_SCHEMA_CREATION is true, then you must create the database tables manually before executing nnl-install.sh. See Step 9. H. in Before You Begin for instructions.
For the remaining database properties, you can either use DB_CUSTOM_JDBC_STRING or the properties listed in the table below.
The information contained in DB_CUSTOM_JDBC_STRING is equivalent to assigning values to the DB_* properties shown under it. DB_CUSTOM_JDBC_STRING’s value overrides values assigned to the properties listed under it in the table if they are present in the installer script.
Property | Description |
|---|---|
DB_CUSTOM_JDBC_STRING | A database connection string. |
DB_HOSTNAME_ENV | The Operational Database hostname or IP address. |
DB_PORT_ENV | The Operational Database port number. |
DB_NAME_ENV |
|
Example connection strings that you can assign to DB_CUSTOM_JDBC_STRING are listed below:
MySQL
"jdbc:mysql://localhost:3306/testdb?useSSL=true\&requireSSL=true\&verifyServerCertificate=true\&trustCertificateKeyStoreUrl=file:///etc/cert/truststore.jks\&trustCertificateKeyStorePassword=storepass"Postgres
"jdbc:postgresql://localhost:5432/testdb?ssl=true&sslmode=verify-ca&sslcert=./test-cert.pem&;sslkey=./test-key.pem&sslrootcert=./test-server-ca.pem"Oracle
"jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(PORT=1522)(HOST=myhost))
(CONNECT_DATA=(SERVICE_NAME=myorcldbservicename))
(SECURITY=(ssl_server_cert_dn="CN=testcert.oracle.com, O=Oracle Corporation,L=Redwood City,ST=California,C=US")))"Cockroach
"jdbc:postgresql://localhost:26257/testdb?sslmode=verify-full\&sslrootcert=./ca.crt\&sslcert=./client.root.crt\&sslkey=./client.root.key"D. Assign Other Database Properties for the Operational Database
Property | Description |
|---|---|
DB_JDBC_PATH_ENV | Mandatory if using an Oracle or MySQL database. Filename and absolute path of the Oracle or MySQL JDBC drive. For example, /opt/ojdbc.jar or /opt/mysql-connector.jar. |
E. Assign the API Server's URL
The following property is required.
Property | Description |
|---|---|
API_SERVER_URL | The host name and port number of the API Server. |
F. Assign Out-of-band Authentication Properties for the default Tenant
Optional. If you plan to use out-of-band (OOB) authentication for the default tenant, uncomment the properties listed below and configure them. You can also configure these properties later. See Out-of-band.
Property | Description |
|---|---|
OOB_REG_URL_ENV | URL for OOB registration. If you use a load balancer, this should be something like: https://<load-balancer-hostname>.<domain-name>:<port>/nnlgateway/nnl/reg. This URL exists after you install the API Server. |
OOB_AUTH_URL_ENV | URL for OOB authentication. If you use a load balancer, this should be something like: https://<load-balancer-hostname>.<domain-name>:<port>/nnlgateway/nnl/auth. This URL exists after you install the API Server. |
G. Assign the UAF Application ID for the default Tenant
Optional if you aren't using the UAF protocol for the default tenant. Nok Nok strongly recommends that you assign the URL to facets.uaf, your organization's list of trusted apps, as the App ID.
For a detailed explanation of what the App ID is, how it is used, and recommendations, see Assigning the App ID.
Property | Description |
|---|---|
UAF_APPLICATION_ID | The UAF App ID for the default tenant. Assign the URL to the file facets.uaf. For example: https://<publicly_accessible_server>.<domain-name>:<port>/<path_to_file>/facets.uaf or https://www.example.com/facets/facets.uaf. |
H. Assign FIDO2 Properties for the default Tenant
Optional if you aren't using the FIDO2 protocol for the default tenant.
The FIDO protocol requires that the RP ID and facet IDs must satisfy specific requirements. If you are not familiar with these requirements, please read section FIDO2: RP IDs and Facet IDs.
Property | Description |
|---|---|
WEB_RP_ID | Specifies the FIDO/WebAuthn RP ID for the default tenant. Assign the domain for your organization. For example, example.com. |
WEB_FACET_ID | Specifies the WebAuthn facet ID for the default tenant. For example, https://example.com:8443. |
I. List Optional Web Applications
The S3 Suite ships with two optional Nok Nok utility apps, nnlsignin and nnlfedapp. Use nnlsignin together with a Nok Nok Federation Adapter to bring FIDO authentication into a Federation Server. Use nnlfedapp to support Federated Credential Management accessible through an OIDC flow. For more information about these apps, see Utility Apps.
Property | Description |
|---|---|
DEPLOY_OPTIONAL_WEB_APP_LIST | Optional. Specifies the list of Nok Nok utility apps that the installer deploys during installation. Comma separated list of app names. For example: DEPLOY_OPTIONAL_WEB_APP_LIST=nnlfedapp,nnlsignin |
If you are deploying a Crypto plugin and/or a Secrets plugin, then configure properties for the plugin(s) at this time. See Crypto and Secrets for instructions.