To install Oracle NoSQL Database with Kerberos authentication:

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 data store 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/node01.example.com@EXAMPLE.COM
   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  krbuser@EXAMPLE.COM
    Enter password for principal: "krbuser@EXAMPLE.COM": ***********
    Re-enter password for principal: "krbuser@EXAMPLE.COM": ********** 

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 "krbuser@EXAMPLE.COM" 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 krbuser@EXAMPLE.COM on the KDC host by using kadmin.local.

    kadmin.local:  ktadd -k /tmp/mykeytab  krbuser@EXAMPLE.COM
    Entry for principal krbuser@EXAMPLE.COM added to 
    keytab WRFILE:/tmp/mykeytab. 

13. Copy the keytab file to client machines that will use the krbuser@EXAMPLE.COM 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 = krbuser@EXAMPLE.COM 
    oracle.kv.auth.external.mechanism=kerberos
    oracle.kv.auth.kerberos.services=
                     node01:oraclenosql/node01.example.com@EXAMPLE.COM
    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.

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

1. Shut down the data store 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 oraclenosql@EXAMPLE.COM
   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 data store 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 data store 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  krbuser@EXAMPLE.COM
   Enter password for principal: "krbuser@EXAMPLE.COM": ***********
   Re-enter password for principal: "krbuser@EXAMPLE.COM": ********** 

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 "krbuser@EXAMPLE.COM" 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 krbuser@EXAMPLE.COM on the KDC host by using kadmin.local.

   kadmin.local:  ktadd -k /tmp/mykeytab  krbuser@EXAMPLE.COM
   Entry for principal krbuser@EXAMPLE.COM added to 
   keytab WRFILE:/tmp/mykeytab. 

8. Copy the keytab file to any client machine that will use the krbuser@EXAMPLE.COM 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 = krbuser@EXAMPLE.COM 
   oracle.kv.auth.external.mechanism=kerberos
   oracle.kv.auth.kerberos.services=
                    node01:oraclenosql/node01.example.com@EXAMPLE.COM
   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.