Kerberos Security Properties

To set up the Kerberos security properties, you can set them in a login file or through the KVStoreConfig class.

The minimal configuration needed to set up Kerberos includes the following properties:

• oracle.kv.auth.username

  Specifies the Kerberos user name in Oracle NoSQL Database. It must match the principal name in KDC and match the Kerberos user account name created in the database. The client will use the value of this option to create the credential which is used in the client-server authentication. If the short name of principal is specified in this field, you must also specify oracle.kv.auth.kerberos.realm.

  If KerberosCredentials is not used, this field has to be specified in the login file or security properties field of KVStoreConfig.

• oracle.kv.auth.kerberos.services

  Specifies the Kerberos principals for services associated with each helper host. Setting this property is required if, as recommended, each host uses a different principal that includes its own principal name. All principals should specify the same service and realm. If this property is not set, the client will use oraclenosql as the principal name for services on all helper hosts.

  Each entry should specify the helper host name followed by the Kerberos service name, and optionally an instance name and realm name. The entries are separated by commas, ignoring spaces. If any entry does not specify a realm, each entry will use the default realm specified in Kerberos configuration file. If any entry specifies a realm name, then all entries must specify the same one. The syntax is:

  host:service[:instance[@realm]][, host:service[:instance[@realm]]]* 

  For example:

  host37:nosql/[e-mail], 
  host53:nosql/[e-mail] 

• oracle.kv.auth.kerberos.keytab

  The default location of the keytab file is specified by the Kerberos configuration file. If the keytab is not specified there, then the system looks for the file user.home/krb5.keytab.

• oracle.kv.auth.kerberos.realm

  Specifies the Kerberos realm for the user principal if using a short name to specify the client login principal.

• oracle.kv.auth.kerberos.ccache

  Specifies the path of the Kerberos ticket cache. This field is optional. The default ticket cache is "/tmp/krbcc_<uid>". If the credential cache is not found, the system will look for the file user.home/krb5cc_user.name. If you want to use your own ticket cache, set this field to the path of the ticket cache.

• oracle.kv.auth.kerberos.mutualAuth

  Specifies whether the client should use mutual authentication. If this value is set to true, the client will authenticate the server's identity in the login results.

  The default value is false, so mutual authentication is disabled.

Setting Security Properties in a security login file

To set the properties in a security file, specify the location of the login file by setting the oracle.kv.security Java system property. For example:

java -Doracle.kv.security=kerberoslogin.txt HelloWorld 

where the file kerberoslogin.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=[e-mail]
oracle.kv.auth.external.mechanism=kerberos
oracle.kv.auth.kerberos.keytab=/kerberos/krb5.keytab
oracle.kv.auth.kerberos.services=
                 node01:oraclenosql/[e-mail]
oracle.kv.auth.kerberos.mutualAuth=false 

You can specify the location of the Kerberos configuration file by specifying the java.security.krb5.conf Java system property. For example:

java -Djava.security.krb5.conf=/kerberos/krb5.conf \
-Doracle.kv.security=kerberoslogin.txt HelloWorld 

You can also set the default realm using java.security.krb5.realm. To set the default KDC, use java.security.krb5.kdc.

Note:

Set the Java system properties for both the realm and the KDC or neither of them. These properties override the default realm and KDC values specified in the krb5.conf file.

Setting Security Properties through KVStoreConfig

You can also set security properties using KVStoreConfig. For example:

Properties securityProps = new Properties();
securityProps.setProperty("oracle.kv.auth.username", 
                                           "[e-mail]");
securityProps.setProperty("oracle.kv.auth.external.mechanism", 
                                           "kerberos");
securityProps.setProperty("oracle.kv.auth.kerberos.keytab", 
                                            "/kerberos/krb5.keytab");
securityProps.setProperty("oracle.kv.auth.kerberos.services", 
                "node01:oraclenosql/[e-mail]");
securityProps.setProperty("oracle.kv.auth.kerberos.ccache", 
                                              "/kerberos/krbcc_501");
securityProps.setProperty("oracle.kv.auth.kerberos.mutualAuth", 
                                              "false");

KVStoreConfig kvConfig = new KVStoreConfig("mystore", "node01:5000");
kvConfig.setSecurityProperties(securityProps); 

Using Security Properties to Log In

To log in to Oracle NoSQL Database using security properties, you can use credential cache, a keytab file or the principal password.

Note:

When connecting through the Admin CLI, if credential cache or keytabs login attempts fail, Oracle NoSQL Database prompts for the principal's password.

Using Credential Cache

To login to Oracle NoSQL Database using credential cache:

1. Run the kinit  Kerberos tool to save the credential in the credential cache.

   For example, to authenticate the client principal [e-mail] to KDC:

   kinit [e-mail]
   Password for [e-mail]: ******** 

   The granted ticket-granting ticket (TGT) will be saved in the default credential cache for later authentication.

2. You can also generate a separate cache. To do this run the following command:

   kinit [e-mail] -c krbcc_krbuser

3. Perform the login by specifying oracle.kv.auth.kerberos.ccache in a security login file or through KVStoreConfig. In this case, a security login file is used:

   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.ccache=/kerberos/krbcc_krbuser
   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 credential cache and logins to Kerberos without needing a password.

Using credential cache

To login to Oracle NoSQL Database using credential cache:

1. Run the kinit Kerberos tool to save the credential in the credential cache.

   For example, to authenticate the client principal [e-mail] to KDC:

   kinit [e-mail]
   Password for [e-mail]: ******** 

   The granted ticket-granting ticket (TGT) will be saved in the default credential cache for later authentication.

2. You can also generate a separate cache. To do this run the following command:

   kinit [e-mail] -c krbcc_krbuser

3. Perform the login by specifying oracle.kv.auth.kerberos.ccache in a security login file or through KVStoreConfig. In this case, a security login file is used:

   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.ccache=/kerberos/krbcc_krbuser
   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 credential cache and logins to Kerberos without needing a password.

Using a keytab

To login to Oracle NoSQL Database using a keytab:

1. Run the kinit Kerberos tool to extract the keytab:

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

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

3. 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 (login) is used. To login, specify the keytab location by using oracle.kv.auth.kerberos.keytab. You must also specify the username using oracle.kv.auth.username. For example, the login 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.