Previous Next JavaScript must be enabled to correctly display this content

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

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

1. 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.

2. 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.

3. 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.

4. 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

5. 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

6. 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 the data store. 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.

7. Start `runadmin` in security mode on the data store 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

8. Use the `configure -name` command to specify the name of the data store 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
       ...

9. Create a user account on Microsoft Active Directory. In this example, `krbuser` is created on Active Directory.

10. 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.

11. 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.

12. 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.