6
Configuring Kerberos Authentication

This chapter contains information on how to configure Oracle for use with Kerberos authentication and to configure Kerberos to authenticate Oracle users.

This chapter covers the following topics:

• Enabling Kerberos Authentication

• Utilities for the Kerberos Authentication Adapter

• Troubleshooting the Configuration of Kerberos Authentication

Enabling Kerberos Authentication

Kerberos authentication is enabled by performing the following tasks, each of which is described in this section.

Perform the following tasks in the order listed below.

Task 1: Install Kerberos

Task 2: Configure a Service Principal for an Oracle Server

Task 3: Extract a Service Table from Kerberos

Task 4: Install an Oracle Server and an Oracle Client

Task 5: Install Net8 and Oracle Advanced Security

Task 6: Configure Net8 and Oracle

Task 7: Configure Kerberos Authentication

Task 8: Create a Kerberos User

Task 9: Create an Externally-Authenticated Oracle User

Task 10: Get an Initial Ticket for the Kerberos/Oracle User

Task 1: Install Kerberos

Install Kerberos on the machine that functions as the authentication server

More Information: For information on how to install Kerberos, see "Related Publications" in the Preface.

Task 2: Configure a Service Principal for an Oracle Server

For the Oracle Server to validate the identity of clients that authenticate themselves using Kerberos, you must first create a service principal for Oracle.

The name of the principal should have the following format:

kservice/kinstance@REALM

kservice	a case-sensitive string that represents the Oracle service. This can be the same as the database service name.
kinstance	typically the fully-qualified name of the machine on which Oracle is running.
REALM	the domain of the server. REALM must always be uppercase, and is typically the DNS domain name.

Note: The utility names in this section are actual programs that are run. However, the Kerberos user name krbuser and the realm SOMECO.COM are examples only.

For example, if kservice is oracle, the fully-qualified name of the machine on which Oracle is running is dbserver.someco.com, and the realm is SOMECO.COM, the principal name is as follows:

oracle/[e-mail]

It is a common convention to use the DNS domain name as the name of the realm.

To create the service principal, run kadmin.local. The following example is UNIX specific. Enter the following as root user:

# cd /kerberos-install-directory/sbin
# ./kadmin.local

To add a principal named oracle/[e-mail] to the list of server principals known by Kerberos, enter the following:

kadmin.local:addprinc -randkey oracle/[e-mail]

Task 3: Extract a Service Table from Kerberos

Extract the service table from Kerberos and copy it to the Oracle server/Kerberos client machine.

For example, to extract a service table for dbserver.someco.com, perform the following steps.

1. Enter the following:

   kadmin.local:  ktadd -k /tmp/keytab oracle/dbserver.someco.com
   Entry for principal oracle/dbserver.someco.com with kvno 2, encryption 
   DES-CBC-CRC added to the keytab WRFILE: 'WRFILE:/tmp/keytab
   kadmin.local:  exit
   oklist -k -t /tmp/keytab
   

2. After the service table has been extracted, verify that the new entries are in the table in addition to the old ones. If they are not, or you need to add more, use kadmin.local to append the additional entries.

   If you do not enter a realm when using ktadd, it uses the realm of the current host and displays it in the command output, as shown above.

3. If the Kerberos service table is on the same machine as the Kerberos client, you can move it. If the service table is on a different machine from the Kerberos client, you must transfer the file with a program such as FTP. If using FTP, transfer the file in binary mode.

   The following example is UNIX specific.

   # mv /tmp/keytab /etc/v5srvtab
   
   

   The default name of the service file is /etc/v5srvtab. If a different name is used, that name should be substituted for the default name.

4. Verify that the owner of the Oracle Server executable can read the service table (/etc/v5srvtab in the previous example). To do so, set the file owner to the Oracle user or make the file readable by the group to which Oracle belongs.

   Caution: Do not make the file readable to all users. This can allow a security breach.

Task 4: Install an Oracle Server and an Oracle Client

Install the Oracle server and client software.

More Information: See the operating system-specific documentation.

Task 5: Install Net8 and Oracle Advanced Security

Install Net8 and Oracle Advanced Security on the Oracle server and Oracle client machines.

More Information: See the platform-specific installation documentation.

Task 6: Configure Net8 and Oracle

Configure Net8 on the Oracle server and client.

More Information: See the operating system-specific documentation. See also the Net8 Administrator's Guide.

Task 7: Configure Kerberos Authentication

Perform the following tasks to set certain parameters in the Oracle server and client sqlnet.ora files:

• Configure Kerberos on the Client and on the Server

• Set the Initialization Parameters

• Optionally Set sqlnet.ora Parameters

Configure Kerberos on the Client and on the Server

Perform the following steps to configure Kerberos authentication service parameters on the client and on the server:

1. Start Net8 Assistant:
   • On UNIX, run netasst from $ORACLE_HOME/bin.

   • On Windows NT, choose Start > Programs > Oracle - HOME_NAME > Network Administration > Net8 Assistant.

2. In the navigator's pane, expand Local > Profile.

3. From the list in the right pane, select Oracle Advanced Security.

   The Oracle Advanced Security tabbed pages appear.

4. Click the Authentication tab.

   
   

5. From the Available Methods list, select KERBEROS5.

6. Move KERBEROS5 to the Selected Methods list by clicking the right-arrow button [>].

7. Arrange the selected methods in order of use. To do this, select a method in the Selected Methods list, then click Promote or Demote to position it in the list. For example, if you want KERBEROS5 to be the first service used, move it to the top of the list.

8. Click the Other Params tab.

   
   

9. From the Authentication Service list, select KERBEROS(V5).

10. In the Service field, enter kerberos in lowercase. You must provide the value for this parameter. When you do this, the other fields are enabled.

    This field specifies the name of the service Oracle uses to obtain a Kerberos service ticket. Substitute a value for the kservice part of the service name.

11. Optionally provide values for the following fields:
    • Credential Cache File

    • Configuration File

    • Realm Translation File

    • Key Table

    • Clock Skew

      More Information: Net8 Assistant online help and "Optionally Set sqlnet.ora Parameters" in this section for more information about the fields and the parameters they configure.

12. Choose File > Save Network Configuration.

    The sqlnet.ora file updates with the following entries:

    SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5)
    SQLNET.AUTHENTICATION_KERBEROS5_SERVICE=kservice
    

Set the Initialization Parameters

Perform the following steps to set parameters in the initialization parameter file.

1. Add the following parameter to the initialization parameter file:

   REMOTE_OS_AUTHENT=FALSE
   

   Attention: Setting REMOTE_OS_AUTHENT to TRUE can allow a security breach, because it allows someone using a non-secure protocol, such as TCP, to perform an operating system-authorized login (formerly referred to as an OPS$ login).

2. Because Kerberos user names can be long and Oracle user names are limited to 30 characters, Oracle Corporation strongly recommends that the value of OS_AUTHENT_PREFIX be set to null as follows:

   OS_AUTHENT_PREFIX=""
   

   
   Setting OS_AUTHENT_PREFIX to a null value overrides the default value of OPS$.

Optionally Set sqlnet.ora Parameters

In addition to the above required parameters, you can optionally set the following sqlnet.ora parameters on the client or on the server.

Parameter:	SQLNET.KERBEROS5_CC_NAME=pathname_to_credentials_cache_file
Description:	Specifies the complete pathname to the Kerberos credentials cache (CC) file. The default value is operating system-dependent. For UNIX, it is /tmp/krb5cc_user id. Note: You can also set this parameter by using the KRB5CCNAME environment variable. The value set for the SQLNET.KERBEROS5_CC_NAME parameter in the sqlnet.ora file takes precedence over the value set in the KRB5CCNAME environment variable.
Example:	SQLNET.KERBEROS5_CC_NAME=/usr/tmp/krbcache

Parameter:	SQLNET.KERBEROS5_CLOCKSKEW=number_of_seconds_accepted_as_network_delay
Description:	This parameter specifies how many seconds can pass before a Kerberos credential is considered out-of-date. It is used when a credential is actually received by either a client or a server. An Oracle server also uses it to decide if a credential needs to be stored to protect against a replay attack. The default is 300 seconds.
Example:	SQLNET.KERBEROS5_CLOCKSKEW=1200

Parameter:	SQLNET.KERBEROS5_CONF=pathname_to_Kerberos_ configuration_file
Description:	This parameter specifies the complete pathname to the Kerberos configuration file. The configuration file contains the realm for the default KDC (key distribution center) and maps realms to KDC hosts. The default is operating system-dependent. For UNIX, it is /krb5/krb.conf.
Example:	SQLNET.KERBEROS5_CONF=/krb/krb.conf

Parameter:	SQLNET.KERBEROS5_CONF_MIT=[Boolean = True/False]
Description:	This parameter specifies whether the new MIT Kerberos configuration format will be used. If the value is set to Yes, it will parse the file according to the new configuration format rules. When the value is set to False, the default (non-MIT) configuration is used. The default is False.
Example:	SQLNET.KERBEROS5_CONF_MIT=False

Parameter:	SQLNET.KERBEROS5_KEYTAB= pathname_to_Kerberos_principal/key_table
Description:	This parameter specifies the complete pathname to the Kerberos principal/secret key mapping file. It is used by the Oracle server to extract its key and decrypt the incoming authentication information from the client. The default is operating system-dependent. For UNIX, it is /etc/v5srvtab.
Example:	SQLNET.KERBEROS5_KEYTAB=/etc/v5srvtab

Parameter:	SQLNET.KERBEROS5_REALMS= pathname_to_Kerberos_realm_translation_file
Description:	This parameter specifies the complete pathname to the Kerberos realm translation file. The translation file provides a mapping from a host name or domain name to a realm. The default is operating system-dependent. For UNIX, it is /etc/krb.realms.
Example:	SQLNET.KERBEROS5_REALMS=/krb5/krb.realms

Task 8: Create a Kerberos User

To create Oracle users that Kerberos can authenticate, perform this task on the Kerberos authentication server where the administration tools are installed.

It is assumed that the realm already exists.

Note: The utility names in this section are actual programs that you run. However, the Kerberos user name "krbuser" and realm "SOMECO.COM" are examples only; they can vary among systems.

Run /krb5/admin/kadmin.local as root to create a new Kerberos user, such as krbuser.

The following example is UNIX specific:

# ./kadmin.local
kadmin.local: addprinc krbuser
Enter password for principal: "[e-mail]": <password not echoed>
Re-enter password for principal: "[e-mail]": <password not echoed>
kadmin.local: exit

More Information: See "Related Publications" in the Preface.

Task 9: Create an Externally-Authenticated Oracle User

Run SQL*Plus on the Oracle server to create the Oracle user that corresponds to the Kerberos user. In the following example, OS_AUTHENT_PREFIX is set to null (""). The Oracle user name must be in uppercase and double-quoted, such as "[e-mail]".

SQL> CONNECT INTERNAL;
SQL> CREATE USER "[e-mail]" IDENTIFIED EXTERNALLY; 
SQL> GRANT CREATE SESSION TO "[e-mail]"; 

Task 10: Get an Initial Ticket for the Kerberos/Oracle User

Before you can connect to the database, you must ask the Key Distribution Center (KDC) for an initial ticket. To do so, run the following on the client:

% okinit user_name

If, when making a database connection, a reference such as the following follows a database link, you must use the forwardable flag (-f ) option:

sqlplus /@oracle

Executing okinit -f enables credentials that can be used across database links. You should be on the Oracle client before running the following commands:

% okinit -f
Password for [e-mail]:password

Utilities for the Kerberos Authentication Adapter

Table 6-1 describes utilities that are shipped with the Oracle Kerberos authentication adapter.

Table 6-1 Oracle Kerberos Adapter Utilities for the Client

Command	Description
okinit	Gets an initial ticket
oklist	Displays a list of currently-owned tickets
okdstry	Removes all tickets from the credentials cache

These utilities are intended for use on an Oracle client with Oracle Kerberos authentication support installed.

Note: Solaris is shipped with Kerberos version 4. Ensure that the Kerberos version 5 utilities are in the path so that the version 4 utilities are not inadvertently used.

Use okinit to Obtain the Initial Ticket

The okinit utility obtains and caches Kerberos tickets. This utility is typically used to obtain the ticket-granting ticket, using a password entered by the user to decrypt the credential from the key distribution center (KDC). The ticket-granting ticket is then stored in the user's credential cache.

The options available with okinit are listed in Table 6-2.

Table 6-2 Options for the okinit Utility

Option	Description
-f	Ask for a forwardable ticket-granting ticket. This option is necessary to follow database links.
-l	Specify the lifetime of the ticket-granting ticket and all subsequent tickets. By default, the ticket-granting ticket is good for eight (8) hours, but shorter or longer-lived credentials may be desired. Note that the KDC can ignore this option or put site-configured limits on what can be specified. The lifetime value is a string that consists of a number qualified by w (weeks), d (days), h (hours), m (months), or s (seconds), as in the following example. okinit -l 2wld6h20m30s The example requests a ticket-granting ticket that has a life time of 2 weeks, 1 day, 6 hours, 20 minutes, and 30 seconds.
-c	Specify an alternative credential cache. For UNIX, the default is /tmp/krb5cc_uid. You can also specify the alternate credential cache by using the SQLNET.KERBEROS5_CC_NAME parameter in the sqlnet.ora file.
-?	List command line options.

Use oklist to Display Credentials

Users can run the oklist utility to display the list of tickets they hold.

The options available with oklist are listed in Table 6-3.

Table 6-3 Options for the oklist Utility

Option	Description
-f	Show flags with credentials. Relevant flags are I, credential is a ticket-granting ticket, F, credential is forwardable, and f, credential is forwarded.
-c	Specify an alternative credential cache. In UNIX, the default is /tmp/krb5cc_uid. The alternate credential cache can also be specified by using the SQLNET.KERBEROS5_CC_NAME parameter in the sqlnet.ora file.
-k	List the entries in the service table (default /etc/v5srvtab) on UNIX. The alternate service table can also be specified by using the SQLNET.KERBEROS5_KEYTAB parameter in the sqlnet.ora file.

The show flag option (-f) displays additional information, as shown in the following example:

% oklist -f
27-Jul-1999 21:57:51   28-Jul-1999 05:58:14
krbtgt/[e-mail]
Flags: FI

Use okdstry to Remove Credentials from Cache File

Use the okdstry utility to remove credentials from the credentials cache file as follows

To use the okdstry utility, enter the following:

$ okdstry -f

Table 6-4 provides information on the -f command option.

Table 6-4 Option for the okdstry Utility

Option	Description
-f	Specify an alternative credential cache. For UNIX, the default is /tmp/krb5cc_uid. You can also specify the alternate credential cache by using the SQLNET.KRB5_CC_NAME parameter in the sqlnet.ora file.

Connecting to an Oracle Server Authenticated by Kerberos

You can now connect to an Oracle Server without using a user name or password. Enter a command similar to the following:

$ sqlplus /@net_service_name

where net_service_name is a Net8 service name. For example:

$ sqlplus /@oracle_dbname

More Information: For information on external authentication, see Chapter 1 and Oracle8i Distributed Database Systems.

Troubleshooting the Configuration of Kerberos Authentication

This section lists some common configuration problems and explains how to resolve them.

If you cannot get your ticket-granting ticket using okinit:

• Ensure that the default realm is correct by examining the krb.conf file.

• Ensure that the KDC is running on the host specified for the realm.

• Ensure that the KDC has an entry for the user principal and that the passwords match.

• Ensure that the krb.conf and krb.realms files are readable by Oracle.

If you have an initial ticket, but still cannot connect:

• After trying to connect, check for a service ticket.

• Check that the sqlnet.ora file on the server side has a service name that corresponds to a service known by Kerberos.

• Check that the clocks on all machines involved are within a few minutes of each other (or change the SQLNET.KERBEROS5_CLOCKSKEW parameter in the
  sqlnet.ora file).

If you have a service ticket and you still cannot connect:

• Check the clocks on the client and server.

• Check that the v5srvtab file exists in the correct location and is readable by Oracle (remember to see the sqlnet.ora parameters).

• Check that the v5srvtab file has been generated for the service named in the sqlnet.ora file on the server side.

If everything seems to work fine, but then you issue another query and it fails:

• Check that the initial ticket is forwardable. (You must have obtained the initial ticket by running the okinit utility.)

• Check the expiration date on the credentials.

• If the credentials have expired, close the connection and run okinit to get a new initial ticket.