The following instructions are for customers who deploy the S3 Suite on Linux. They do not apply to customers who use the Nok Nok Cloud Deployment Toolkit. If you are deploying the S3 Suite using the Nok Nok Cloud Deployment Toolkit, please contact Nok Nok Customer Support before continuing.
When you install the Crypto or the Secrets Plugin on a production Server, the steps to follow depend on whether you are implementing both. If you are implementing the Crypto Plugin only, then follow the steps in Installing Crypto Plugin Only. If you are implementing the Secrets Plugin only, then follow the steps in Installing Secrets Plugin Only. If you implemented both plugins, install them using the following instructions.
Installing Both Crypto and Secrets Plugin
Before installing the Nok Nok Server, set up your external secrets manager with your operational database password along with its handle. You can choose to load any remaining passwords and their handles into your external secrets manager after installation.
Begin by completing Steps 1, 2 and 3 of Install the Nok Nok Servers on Linux. If you plan to store any passwords in encrypted form in the Nok Nok database, then also complete Step 4 of Install the Nok Nok Servers on Linux.
Next, uncomment and update the properties below in nnl-install.properties.
Property | Expected Value |
|---|---|
NNL_CRYPTO_PLUGIN_CLASS_NAME | The name of your class that implements the interface CryptoPlugin. |
NNL_SECRETS_PLUGIN_CLASS_NAME | The name of your class that implements the interface SecretsPlugin. |
NNL_EXT_DIR_PATHS | The directory paths to your Crypto plugin, Secrets plugin, and other required JAR files. |
What you do next depends on if you plan to use a handle to retrieve the password or store the encrypted password in the database.
Use a handle to the external secrets manager
If you will not be storing any encrypted passwords in the database, i.e. you will always use a handle to the external secrets manager, then make the following changes to the nnl-install.properties file:
Comment out DB_ENCRYPTED_USER_PASSWD_ENV
Uncomment and configure DB_SECRET_HANDLE_ENV={handle}<The handle for the operational database password from the external secrets manager>
Note that "{handle}" is prefixed literally.
Store the encrypted password in the database
In certain circumstances you will install the Secrets plugin and continue to store an encrypted password in the database. In this case, make the following changes to the nnl-install.properties file:
Uncomment and configure DB_ENCRYPTED_USER_PASSWD_ENV
Comment out DB_SECRET_HANDLE_ENV
In either case:
After you have completed the configuration of the Secrets plugin, go to Step 6. Install the Server and its Components to run the installation script and then return here.
If you completed installation successfully, you see the following:
Inside the tomcat/bin/setenv.sh file:
CATALINA_OPTS="${CATALINA_OPTS}-Dnnl.crypto.plugin.class.name=<The name of your class that implements the interface CryptoPlugin>"JARs from the paths specified in NNL_EXT_DIR_PATHS are copied into the web applications' lib directories. For example: tomcat/webapps/nnl/WEB-INF/lib/
Use the following nnl-mgmt.sh command to list the SYSTEM tenant's properties so you can verify the values. For details, see Properties Commands.
./nnl-mgmt.sh properties list -tenantid systemVerify the values for the properties listed below:
nnl.default.external.encryption.key.jce.provider.name=NokNokCryptoProvider
nnl.jce.providers=com.noknok.crypto.provider.NokNokCryptoProvider,org.bouncycastle.jce.provider.BouncyCastleProviderInside the tomcat/bin/setenv.sh file :
CATALINA_OPTS="${CATALINA_OPTS}-Dnnl.secrets.plugin.class.name=<The name of your class that implements the interface SecretsPlugin>"The JARs from the paths specified in NNL_EXT_DIR_PATHS are copied into the correct server and web applications' lib directories. For example, for the Authentication Server, these libraries are in tomcat/webapps/nnl/WEB-INF/lib/.
The handle for the Operational database password in the external secrets manager is updated in the following files:
<TOMCAT_HOME>/bin/setenv.sh
<MFAS_HOME>/admin/conf/nnl-db.properties
<MFAS_HOME>/admin/conf/application.properties
Verify the installation by running the <NNL_HOME>/install/nnl-postinstall-checks.sh script. Examine the output to uncover any configuration issues.
After you verify the installation, perform the Post Installation tasks.
For the Crypto plugin, configure an alias for the encryption key for default and Admin tenants. If required, also configure an alias for the encryption key for other tenants. You can enter the aliases using the Admin Console or using the command line interface. See Rotate Encryption Keys.
Installing Crypto Plugin Only
Use the instructions below to install and configure just a Crypto plugin in the Nok Nok Server. Do not use these instructions if you are planning on installing both the Crypto and the Secrets plugin.
Begin by completing Steps 1, 2, 3 and 4 of Install on Linux.
Next, update the Crypto plugin properties in nnl-install.properties
NNL_CRYPTO_PLUGIN_CLASS_NAME = <The name of your class that implements the interface CryptoPlugin>
NNL_EXT_DIR_PATHS = <The directory paths to your Crypto plugin and other required jar files>
You are now ready to install, go to Step 6. Install the Server and its Components to run the installation script and then return here.
If you completed installation successfully, you see the following
Inside the tomcat/bin/setenv.sh file :
CATALINA_OPTS="${CATALINA_OPTS} -Dnnl.crypto.plugin.class.name=<The name of your class that implements the interface CryptoPlugin>"Jars from the paths specified in NNL_EXT_DIR_PATHS are copied into the web applications' lib directories. For example: tomcat/webapps/nnl/WEB-INF/lib/
The following properties are configured for the SYSTEM tenant:
nnl.default.external.encryption.key.jce.provider.name=NokNokCryptoProvider
nnl.jce.providers=com.noknok.crypto.provider.NokNokCryptoProvider,org.bouncycastle.jce.provider.BouncyCastleProvider
Verify the installation by running the <NNL_HOME>/install/nnl-postinstall-checks.sh script. Examine the output to uncover any configuration issues.
After you verify the installation, perform the Post Installation tasks.Configure an alias for the encryption key for default and Admin tenants. If required, also configure an alias for the encryption key for other tenants. You can enter the aliases using the Admin Console or using the command line interface.
If you are using the command line interface, enter the following commands and respond to the resulting prompts by entering your alias:
./nnl-mgmt.sh key add -tenantid default -autogenerate no
./nnl-mgmt.sh key add -tenantid Admin -autogenerate noInstalling Secrets Plugin Only
Before installing the Nok Nok Server, set up your external secrets manager with your operational database password along with its handle. You can choose to load any remaining passwords and their handles into your external secrets manager after installation.
Use these instructions to install and configure the Secrets plugin alone. Do not use these instructions if you are going to deploy both the Secrets plugin and the Crypto plugin.
Begin by completing Steps 1, 2 and 3 of Install on Linux. If you plan to store any passwords in encrypted form in the Nok Nok database, then also complete Step 4 of Installing the Nok Nok Servers.
Next, uncomment and update the Secrets plugin properties in nnl-install.properties.
NNL_SECRETS_PLUGIN_CLASS_NAME=<The name of your class that implements the interface SecretsPlugin>
NNL_EXT_DIR_PATHS=<The directory paths to your Secrets plugin and other required jar files>
What you do next depends on if you plan to use a handle to retrieve the password or store the encrypted password in the database.
Use a handle to the external secrets manager
If you will not be storing any encrypted passwords in the database, i.e. you will always use a handle to the external secrets manager, then make the following changes to the nnl-install.properties file:
Comment out DB_ENCRYPTED_USER_PASSWD_ENV
Uncomment and configure DB_SECRET_HANDLE_ENV={handle}<The handle for the operational database password from the external secrets manager>
Note that "{handle}" is prefixed literally.
Store the encrypted password in the database
In certain circumstances you will install the Secrets plugin and continue to store an encrypted password in the database. In this case, make the following changes to the nnl-install.properties file:
Uncomment and configure DB_ENCRYPTED_USER_PASSWD_ENV
Comment out DB_SECRET_HANDLE_ENV
In either case:
After you have completed the configuration of the Secrets plugin, go to Step 6. Install the Server and its Components to run the installation script and then return here.
If you completed installation successfully, you see the following:
Inside the tomcat/bin/setenv.sh file:
CATALINA_OPTS="${CATALINA_OPTS}-Dnnl.secrets.plugin.class.name=<The name of your class that implements the interface SecretsPlugin>"The jars from the paths specified in NNL_EXT_DIR_PATHS are copied into the web applications' lib directories. For example, for the authentication server these libraries will be in tomcat/webapps/nnl/WEB-INF/lib/
The handle for the operational database password in the external secrets manager is updated in the following files:
<TOMCAT_HOME>/bin/setenv.sh
<MFAS_HOME>/admin/conf/nnl-db.properties
<MFAS_HOME>/admin/conf/application.properties
Verify the installation by running the <NNL_HOME>/install/nnl-postinstall-checks.sh script. Examine the output to uncover any configuration issues.
After you verify the installation, perform the Post Installation tasks.