Performing a Secure Oracle NoSQL Database Installation with Kerberos

It is possible to add Kerberos to a new or an existing Oracle NoSQL Database secure installation.

At a high-level, to configure a Oracle NoSQL Database installation to use Kerberos, you first need to register Oracle NoSQL Database as a service principal in KDC and extract corresponding keytab files on each database server node. Then, to allow client login, a user principal must be added in KDC and a mapped user account with the same name of principal needs to be created in the database. Finally, login can be performed through the CLI or the kvclient driver.

Adding Kerberos to a New Installation

To install Oracle NoSQL Database with Kerberos authentication:

Note:

The following example assumes you have configured an admin/admin principal on the KDC and that you distributed its keytab (kadm5.keytab) to the Oracle NoSQL Database Storage Nodes. For more information, see Configuring the Kerberos Administrative Utility.

1. Run the makebootconfig utility with the -store-security configure and -external-auth kerberos flags to set up the basic store configuration with Kerberos security:

   java -Xmx64m -Xms64m \
   -jar KVHOME/lib/kvstore.jar makebootconfig \
   -root KVROOT -port 5000 \
   -host node01 -harange 5010,5020 \
   -capacity 3 \
   -store-security configure \
   -external-auth kerberos \
   -instance-name node01.example.com \
   -kadmin-keytab /kerberos/kadm5.keytab \
   -admin-principal admin/admin 

2. In this example, -store-security configure is used, so the security configuration utility is run as part of the makebootconfig process and you are prompted for a password to use for your keystore file:

   Enter a password for the Java KeyStore: 

3. Enter a password for your store and then reenter it for verification. In this case, Oracle Wallet is used. Oracle Wallet and Kerberos support are only available in the Oracle NoSQL Database EE version.

   Enter a password for the Java KeyStore: ***********
   Re-enter the KeyStore password for verification: *********** 

4. In this case, -kadmin-keytab points to the admin/admin keytab file you distributed earlier. Once authenticated, the configuration tool will automatically generate some security related files:

   Login Kerberos admin via 
   keytab /kerberos/kadm5.keytab
   Adding principal oraclenosql/[e-mail]
   Authenticating as principal admin/admin with
   keytab /kerberos/kadm5.keytab
   Extracting keytab KVROOT/security/store.keytab
   Created files:
   security/security.xml
   security/store.keys
   security/store.trust
   security/store.wallet/cwallet.sso 
   security/store.keytab
   security/client.security 
   security/client.trust 

5. In a multi-host store environment, the security directory and all files contained in it should be copied from the first node to each server that will host a Storage Node, to setup internal cluster authentication. For example, the following commands assume that the different nodes are visible and accessible on the current node (node01):

   cp -R node01/KVROOT/security node02/KVROOT/
   cp -R node01/KVROOT/security node03/KVROOT/

   Note:

   You may need to use a remote copying command, like Secure Copy Protocol (SCP), to do the copying if the files for the different nodes are not visible on the current node.

6. Run makebootconfig on the other two nodes:

   • Add Kerberos and create their individual service principal and keytab:

     java -Xmx64m -Xms64m \
     -jar KVHOME/lib/kvstore.jar makebootconfig \
     -root KVROOT -port 6000 \ 
     -host node02 -harange 6010,6020 \
     -capacity 3 \
     -store-security configure \
     -external-auth kerberos \
     -instance-name node02.example.com \
     -kadmin-keytab /kerberos/kadm5.keytab \
     -admin-principal admin/admin 

     java -Xmx64m -Xms64m \
     -jar KVHOME/lib/kvstore.jar makebootconfig \
     -root KVROOT -port 7000 \
     -host node03 -harange 7010,7020 \
     -capacity 3 \
     -store-security configure \
     -external-auth kerberos \
     -instance-name node03.example.com \
     -kadmin-keytab /kerberos/kadm5.keytab \
     -admin-principal admin/admin

     Note:

     The service principal name of node2 and node3 are using the same service name "oraclenosql", but different instance names. Their keytab files are different, which contains the key for principal "oraclenosql/node2.example.com" and "oraclenosql/node3.example.com" respectively.

   • To enable Kerberos authentication if the store is using the same service principal on every node:

     java -Xmx64m -Xms64m \
     -jar KVHOME/lib/kvstore.jar makebootconfig \
     -root KVROOT -port 6000 \
     -host node02 -harange 6010,6020 \
     -capacity 3 \
     -store-security enable

     java -Xmx64m -Xms64m \
     -jar KVHOME/lib/kvstore.jar makebootconfig \
     -root KVROOT -port 6000 \
     -host node03 -harange 6010,6020 \
     -capacity 3 \
     -store-security enable

     Note:

     The service principal created in step one is "oraclenosql/node01.example.com". The instance name can be replaced with any more general one like "nosql". In above example, node02 and node03 are all using the same service principal and keytab file without creating new one individually.

7. Start the Storage Node Agent (SNA) on each node:

   Note:

   Before starting the SNA, set the environment variable MALLOC_ARENA_MAX to 1. Setting MALLOC_ARENA_MAX to 1 ensures that the memory usage is restricted to the specified heap size.

   nohup java -Xmx64m -Xms64m \
   -jar KVHOME/lib/kvstore.jar start -root KVROOT&

   When a newly created store with a secure configuration is first started, there are no user definitions available against which to authenticate access. In order to reduce risk of unauthorized access, an admin will only allow you to connect to it from the host on which it is running. This security measure is not a complete safeguard against unauthorized access. It is important that you do not provide local access to machines running KVStore. In addition, you should perform the following steps soon after this step in order to minimize the time period in which the admin might be accessible without full authentication. For more information on maintaining a secure store see Guidelines for Securing the Configuration.

8. Start runadmin in security mode on the KVStore server host (node01). To do this, use the following command:

   java -Xmx64m -Xms64m \
   -jar KVHOME/lib/kvstore.jar \
   runadmin -port 5000 -host node01 \
   -security KVROOT/security/client.security
   Logged in admin as anonymous 

9. Use the configure -name command to specify the name of the KVStore that you want to configure:

   kv-> configure -name mystore
   Store configured: mystore 

10. Register the user principal on the KDC. To do this, use kadmin or kadmin.local:

    kadmin.local: addprinc  [e-mail]
    Enter password for principal: "[e-mail]": ***********
    Re-enter password for principal: "[e-mail]": ********** 

11. After user principal is registered on KDC, create the user in Oracle NoSQL Database. The username needs to match the full principal name in the KDC (includes realm name). In this case, user krbuser is defined:

    kv-> execute 'CREATE USER "[e-mail]" IDENTIFIED EXTERNALLY' 

    For more information on user creation and administration, see User Management.

12. At this point, it is possible to connect to the store as the krbuser. To login, you can use credential cache, a keytab file or enter the principal password.

    In this example, a keytab file is used. To do this, first extract the keytab of principal [e-mail] on the KDC host by using kadmin.local.

    kadmin.local:  ktadd -k /tmp/mykeytab  [e-mail]
    Entry for principal [e-mail] added to 
    keytab WRFILE:/tmp/mykeytab. 

13. Copy the keytab file to client machines that will use the [e-mail] principal to login automatically to Oracle NoSQL Database.

14. Set the Kerberos security properties, including the keytab file location, on each client by specifying them in a security file or through the KVStoreConfig class.

    In this example, a security file (mylogin.txt) is used. To login, specify the file location by using the oracle.kv.security property. For example:

    java -Xmx64m -Xms64m \
    -Doracle.kv.security=mylogin.txt \
    -jar KVHOME/lib/kvstore.jar runadmin -port 5000 -host localhost
    Logged in admin as krbuser

    The file mylogin.txt should be a copy of the client.security file with additional properties settings for Kerberos authentication. The file would then contain content like this:

    oracle.kv.auth.kerberos.keytab = kerberos/mykeytab
    oracle.kv.auth.username = [e-mail] 
    oracle.kv.auth.external.mechanism=kerberos
    oracle.kv.auth.kerberos.services=
                     node01:oraclenosql/[e-mail]
    oracle.kv.auth.kerberos.mutualAuth=false 

    In this case, Oracle NoSQL Database reads the keytab and logins to Kerberos without needing a password.

    For more information on Kerberos security properties, see Kerberos Security Properties.

Adding Kerberos to an Existing Secure Installation

To add Kerberos to an existing Oracle NoSQL Database secure installation:

Note:

The following example assumes you have configured an admin/admin principal on the KDC and that you distributed its keytab (kadm5.keytab) to the Oracle NoSQL Database Storage Nodes. For more information, see Configuring the Kerberos Administrative Utility.

Note:

If your Kerberos installation/keytab will be configured to use a strong encryption type — for example, AES with 256-bit keys — the JCE Unlimited Strength Jurisdiction Policy Files must be obtained and installed in the JDK/JRE. Be aware that these files might already exist in your installation. If so, they must be updated.

1. Shut down the KVStore instance:

   java -Xmx64m -Xms64m \
   -jar KVHOME/lib/kvstore.jar stop \
   -root KVROOT

2. Use the config add-kerberos command to add Kerberos authentication:

   java -Xmx64m -Xms64m \
   -jar KVHOME/lib/kvstore.jar securityconfig \
   config add-kerberos -root KVROOT \
   -secdir security \
   -admin-principal admin/admin
   
   Adding principal [e-mail]
   Password for admin/admin: *******
   Created files:
      security/store.keytab
   Updated Kerberos configuration 

   Note:

   When running this command, the securityconfig tool will verify the existence of the referenced files and will update the specified bootstrap configuration file to refer to the security configuration. This process is normally done with the KVStore instance stopped, and must be performed on each Storage Node of the store.

3. Start the Storage Node Agent (SNA) on each node:

   Note:

   Before starting the SNA, set the environment variable MALLOC_ARENA_MAX to 1. Setting MALLOC_ARENA_MAX to 1 ensures that the memory usage is restricted to the specified heap size.

   nohup java -Xmx64m -Xms64m \
   -jar KVHOME/lib/kvstore.jar start -root KVROOT&

4. Start runadmin in security mode on the KVStore server host (node01). To do this, use the following command:

   java -Xmx64m -Xms64m \
   -jar KVHOME/lib/kvstore.jar \
   runadmin -port 5000 -host node01 \
   -security KVROOT/security/client.security 
   Logged in admin as anonymous.

   This command sets SSL as a connection method and names a copy of the generated truststore file (client.security). For more information on SSL properties, see SSL communication properties.

5. Register the user principal on the KDC. To do this, use kadmin or kadmin.local:

   kadmin.local: addprinc  [e-mail]
   Enter password for principal: "[e-mail]": ***********
   Re-enter password for principal: "[e-mail]": ********** 

6. After user principal is registered on KDC, create the user in Oracle NoSQL Database. The username needs to match the full principal name in the KDC (includes realm name). In this case, user krbuser is defined:

   kv-> execute 'CREATE USER "[e-mail]" IDENTIFIED EXTERNALLY' 

   For more information on user creation and administration, see User Management.

7. At this point, it is possible to connect to the store as the krbuser. To login, you can use credential cache, a keytab file or enter the principal password.

   In this example, a keytab file is used. To do this, first extract the keytab of principal [e-mail] on the KDC host by using kadmin.local.

   kadmin.local:  ktadd -k /tmp/mykeytab  [e-mail]
   Entry for principal [e-mail] added to 
   keytab WRFILE:/tmp/mykeytab. 

8. Copy the keytab file to any client machine that will use the [e-mail] principal to login automatically to Oracle NoSQL Database.

9. Set the Kerberos security properties, including the keytab file location, on each client by specifying them in a security file or through the KVStoreConfig class.

   In this example, a security file (mylogin.txt) is used. To login, specify the file location by using the oracle.kv.security property. For example:

   java -Xmx64m -Xms64m \
   -Doracle.kv.security=mylogin.txt \
   -jar KVHOME/lib/kvstore.jar runadmin -port 5000 -host localhost
   Logged in admin as krbuser

   The file mylogin.txt should be a copy of the client.security file with additional properties settings for Kerberos authentication. The file would then contain content like this:

   oracle.kv.auth.kerberos.keytab = kerberos/mykeytab
   oracle.kv.auth.username = [e-mail] 
   oracle.kv.auth.external.mechanism=kerberos
   oracle.kv.auth.kerberos.services=
                    node01:oraclenosql/[e-mail]
   oracle.kv.auth.kerberos.mutualAuth=false 

   In this case, Oracle NoSQL Database reads the keytab and logins to Kerberos without needing a password.

   For more information on Kerberos security properties, see Kerberos Security Properties.