Using Oracle NoSQL Database with Kerberos and Microsoft Active Directory (AD)

To use Oracle NoSQL Database with Kerberos and Microsoft Active Directory:

Update Kerberos Configuration krb5.conf with AD.

The Microsoft Guide (see here) details how to update the Kerberos configuration file on a Unix host in step 3: Edit the file (/etc/krb5.conf) to refer to the Windows 2000 domain controller as the Kerberos KDC. After changing the Kerberos configuration file, run kinit using a user account in AD to verify that the configuration is correct.

For example, suppose you have user account krbuser08 on domain TEST08 of AD, and the KDC realm name is TEST08.LOCAL:
```
$ kinit krbuser08@TEST08.LOCAL
Password for krbuser08@TEST08.LOCAL
```
After you provide the password, the command should return without error. An error indicates there are probably configuration issues. If the kinit command ran successfully, then run klist to check that the ticket cache contains the TGT of krbuser08.
```
$ klist
Ticket cache: FILE:/tmp/krb5cc_500
Default principal: krbuser08@TEST08.LOCAL

Valid starting     Expires            Service principal
08/12/16 11:45:03  08/12/16 21:45:11 krbtgt/TEST08.LOCAL@TEST08.LOCAL
       renew until 08/19/16 11:45:03
```
The klist shows the tickets in your ticket cache. Perform this step to check if the ticket-granting ticket has been properly obtained using the principal krbuser08 described by "Default Principal." The "Service Principal" describes each ticket, the ticket-granting ticket has the primary krbtgt, and the instance name is the KDC realm name. Also check if the lifetime indicated by "Valid Starting" and "Expires" is correct.
Create service instance account and generate keytab on AD.

The Microsoft Guide (see https://technet.microsoft.com/en-us/library/bb742433.aspx#EEAA) details how to support a service running on a Unix system when using Active Directory. Follow the steps in this document to generate the service principal and keytab file for Oracle NoSQL Database. Note that you do not need to perform step 3 in the Microsoft Guide to merge keytab files if you plan to use same keytab file on every host.

For example, you can set the instance name to nosql and use this keytab on every node.
- Use the Active Directory Management tool to create a user account named oraclenosql.
  
  In the user creation interface, you can choose which Kerberos encryption type this account can support. The user account may use Data Encryption Standard (DES) encryption as default. To enable other encryption types for this account, you need to manually configure in the "Properties" interface, or by using ktpass utility. Note that you need to disable the "User must change password at next logon" setting.
- Use ktpass tool on Windows Server to set up an identity mapping.
```
c:\ktpass -princ oraclenosql/nosql@TEST08.LOCAL 
-mapuser oraclenosql -pass "*"-cypto DES-CBC-MD5 -ptype 
KRB5_NT_PRINCIPAL -out c:\store.keytab
```
  You may need to add allow_weak_crypto = true to the krb5.conf file on the Unix host, as well as default_tkt_enctypes and default_tgs_enctypes, if you use the DES decryption type. The default name of the keytab for Oracle NoSQL Database is store.keytab and the default service name of the service principal is oraclenosql.
- Copy the keytab file to your Unix hosts used by Oracle NoSQL Database.
  
  Typically, you can use Secure Copy Protocol (scp) or PuTTY Secure Copy (PSCP) to transfer this file securely, or upload this file to an FTP server shared by Windows Server and Unix hosts. After creating the service principal and keytab, run kinit tests on your Unix hosts (described next) to confirm that they are configured properly.
Test if the user account can acquire service tickets for the service principal, and if the service keytab is generated correctly by running kinit:
- Test if the user account can acquire service tickets for service principal oraclenosql.
```
$ kinit -S oraclenosql/nosql@TEST08.LOCAL krbuser08@TEST08.LOCAL
Password for krbuser08@TEST08.LOCAL:
$ klist
Ticket cache: FILE:/tmp/krb5cc_500
Default principal: krbuser08@TEST08.LOCAL

Valid starting     Expires            Service principal
08/12/16 11:50:55  08/12/16 21:51:00  oraclenosql/nosql@TEST08.LOCAL
       renew until 08/19/16 11:50:55
```
  If the ticket cache does not contains a service ticket for oraclenosql/nosql, or if any errors are reported in the first command, then check if the account was created properly.
- Test if the service keytab was generated correctly by running kinit oraclenosql.
```
$ kinit -k -t store.keytab oraclenosql/nosql@TEST08.LOCAL
$ klist
Ticket cache: FILE:/tmp/krb5cc_500
Default principal: oraclenosql/nosql@TEST08.LOCAL

Valid starting     Expires            Service principal
08/12/16 11:51:44  08/12/16 21:51:45 krbtgt/TEST08.LOCAL@TEST08.LOCAL
       renew until 08/19/16 11:51:44
```
  As with the previous tests, any errors need to be fixed before attempting to configure Oracle NoSQL Database. Some versions of the kinit utility may need to explicitly specify default_tkt_enctypes and default_tgs_enctypes with the encryption type you configured for the service account oraclenosql in Active Directory, otherwise kinit cannot successfully obtain tickets from AD.

Begin to configure Oracle NoSQL Database.

Oracle NoSQL Database utilizes the Unix kadmin tool to help users create service principal and generate keytab file. However, AD does not have remote admin utility support, so it is necessary to skip this step in AD Kerberos environment.

For Oracle NoSQL Database releases prior to 4.2, you must specify none as the value for both the -kadmin-path and -admin-principal makebootconfig command line options.

java -Xmx64m -Xms64m \
-jar $KVHOME/lib/kvstore.jar makebootconfig -root kvroot \
-port 5000 \
-host node01.example.com -harange 5010,5020 \
-store-security configure -kspwd password \
-external-auth kerberos \
-kadmin-path none \
-admin-principal none \
-instance-name nosql
Adding principal oraclenosql/nosql
IO error encountered: Cannot run program "none": error=13,
Permission denied
Created files
   KVROOT/security/client.security
   KVROOT/security/client.trust
   KVROOT/security/security.xml
   KVROOT/security/store.wallet/cwallet.sso
   KVROOT/security/store.keys
   KVROOT/security/store.trust

The IO error can be ignored in this example, because we did not specify a correct kadmin path.

For Oracle NoSQL Database 4.2 and later releases, you only need to specify none as the value for the -kadmin-path flag:

java -Xmx64m -Xms64m \
-jar $KVHOME/lib/kvstore.jar makebootconfig -root kvroot \
-port 5000 \
-host node01.example.com -harange 5010,5020 \
-store-security configure -kspwd password \
-external-auth kerberos \
-kadmin-path none \
-instance-name nosql

The kadmin path was specified as NONE, so this example is not creating a keytab for the database server. The keytab must be generated and copied to the security configuration directory manually.

Created files
   KVROOT/security/client.security
   KVROOT/security/client.trust
   KVROOT/security/security.xml
   KVROOT/security/store.wallet/cwallet.sso
   KVROOT/security/store.keys
   KVROOT/security/store.trust

After the security directory is created, it is worth checking that the Kerberos parameters are configured as expected.

Check security.xml in kvroot/security and look for the following parameters:

krbInstanceName
krbRealmName

For Oracle NoSQL Database 4.2 and later releases, you can use the securityconfig tool to view the parameters:

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar securityconfig \
config show -secdir kvroot/security
...
krbInstanceName=nosql
krbRealmName=TEST08.LOCAL

Manage service principals in a multi-node environment.
- In a multi-node environment, if you want to use a single service principal oraclenosql/nosql for all nodes, you can simply copy the contents of the first security directory to the other nodes. 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/
```
  You may need to use a remote copying command, like scp, to do the copying if the files for the different nodes are not visible on the current node.
  
  Run makebootconfig on the other two nodes to enable Kerberos authentication.
```
java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar makebootconfig \
-root KVROOT -port 5000 \
-host node02 -harange 5010,5020 \
-store-security enable

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar makebootconfig \
-root KVROOT -port 5000 \
-host node03 -harange 5010,5020 \
-store-security enable
```
  Note:
  
  The service principal for node02 and node03 will be configured as oraclenosql/nosql@TEST08.LOCAL. Also they will use the same keytab file generated in step two.
- To set up individual service principals for each node, run step two to create a service account on AD and generate a new keytab for each node. For example, each node uses host name as instance name of service principal and their corresponding keytab files.
```
oracelnosql/node01@TEST08.LOCAL
oracelnosql/node02@TEST08.LOCAL
oracelnosql/node03@TEST08.LOCAL
```
  Copy the security directory created on node01 to other nodes. For example, the following commands assume that the different nodes are accessible using ssh from the current node (host01):
```
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 scp, to copy the files for the different nodes if they are not visible on the current node.
  
  Replace keytab files of node2 and node3 generated in step two with the one in their security configuration directory. For example:
```
cp store.keytab node02/KVROOT/security
cp store.keytab node03/KVROOT/security
```
  Note:
  
  The name of all of the keytab files generated in step two is store.keytab by default. Make sure that you have given each node the proper keytab file. Use the klist tool to check keytab file on each node to make sure they contain the correct key of service principal for the node.
  
  Run the securityconfig tool on node02 and node03 to modify instance name of security configuration:
```
security -> config update -secdir KVROOT/security \
-param krbInstanceName=node02

security -> config update -secdir KVROOT/security \
-param krbInstanceName=node03
```
  Run makebootconfig on the other two nodes to enable Kerberos authentication.
```
java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar makebootconfig \
-root KVROOT -port 5000 \
-host node02 -harange 5010,5020 \
-store-security enable

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar makebootconfig \
-root KVROOT -port 5000 \
-host node03 -harange 5010,5020 \
-store-security enable
```
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. 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, perform the following steps 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.

Start runadmin in security mode on the KVStore server host (node01). To do this:

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

Use the configure -name command to specify the name of the KVStore that you want to configure, and then complete store deployment. For more information, see the Oracle NoSQL Database Administrator's Guide:
```
kv-> configure -name mystore
Store configured: mystore
... 
```
Create a user account on Microsoft Active Directory. In this example, krbuser is created on Active Directory.
Create mapping 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@TEST08.LOCAL" 
IDENTIFIED EXTERNALLY' 
```
For more information on user creation and administration, see User Management.
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.
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
krbuser@TEST08.LOCAL's kerberos password:
Logged in admin as krbuser@TEST08.LOCAL
kv-> 
```
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.username = krbuser@TEST08.LOCAL 
oracle.kv.auth.external.mechanism=kerberos
oracle.kv.auth.kerberos.services=node01:oraclenosql/nosql@TEST08.LOCAL
oracle.kv.transport=ssl
oracle.kv.ssl.trustStore=KVROOT/security/client.trust
oracle.kv.ssl.protocols=TLSv1.2
oracle.kv.ssl.hostnameVerifier=dnmatch(CN\=NoSQL)
```
In this example, the store nodes are using the single service principal oraclenosql/nosql. Without specifying keytab or credential cache, Admin CLI prompts for principal password.

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