Previous Next JavaScript must be enabled to correctly display this content

## 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/host37@EXAMPLE.COM,
      host53:nosql/host53@EXAMPLE.COM

- `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=krbuser@EXAMPLE.COM
    oracle.kv.auth.external.mechanism=kerberos
    oracle.kv.auth.kerberos.keytab=/kerberos/krb5.keytab
    oracle.kv.auth.kerberos.services=
                     node01:oraclenosql/node01.example.com@EXAMPLE.COM
    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",
                                               "krbuser@EXAMPLE.COM");
    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/node01.example.com@EXAMPLE.COM");
    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 `krbuser@EXAMPLE.COM` to KDC:

       kinit krbuser@EXAMPLE.COM
       Password for krbuser@EXAMPLE.COM: ********

   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 krbuser@EXAMPLE.COM -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 = 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 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 krbuser@EXAMPLE.COM to KDC:

       kinit krbuser@EXAMPLE.COM
       Password for krbuser@EXAMPLE.COM: ********

   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 krbuser@EXAMPLE.COM -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 = 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 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 krbuser@EXAMPLE.COM
       Entry for principal krbuser@EXAMPLE.COM added to
       keytab WRFILE:/tmp/mykeytab.

2. Copy the keytab file to any client machine that will use the krbuser@EXAMPLE.COM 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 = 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.