4
Configuring the Kerberos Authentication Adapter

This chapter contains information on how to configure Oracle for use with the Kerberos authentication adapter. Also included are brief descriptions of the steps to follow to configure Kerberos to authenticate Oracle users.

This information includes the following:

Section 4.1, "Steps to Perform to Enable Kerberos Authentication"

Section 4.2, "Configure the Kerberos Authentication Adapter Using the Oracle Net8 Assistant"

Section 4.3, "Description of Configuration File Parameters on Oracle Server and Client"

Section 4.4, "Troubleshooting the Configuration of the Kerberos Authentication Adapter"

4.1 Steps to Perform to Enable Kerberos Authentication

The following tasks are required to enable Kerberos authentication. Perform the following tasks in the order listed.

1. "Install Kerberos on the Machine that will Act as the Authentication Server"
2. "Configure a Service Principal for an Oracle Server"
3. "Extract a Service Table from Kerberos"
4. "Install an Oracle Server and an Oracle Client"
5. "Install Net8"
6. "Configure Net8 and Oracle on the Oracle Server and Client"
7. "Create a Kerberos User on the Kerberos Authentication Server"
8. "Create an Externally-Authenticated User on the Oracle Database"
9. "Get an Initial Ticket for the Kerberos/Oracle User"

4.1.1 Install Kerberos on the Machine that will Act as the Authentication Server

For information on how to install Kerberos on your machine, refer to the Kerberos documentation listed in the "Preface" of this guide.

4.1.2 Configure a Service Principal for an Oracle Server

For the Oracle Server to be able 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

where

String	Definition
kservice	a string that represents the Oracle service. This may or may not be the same as the database service name. It is case-sensitive.
kinstance	typically the fully-qualified name of the machine on which Oracle is running.
REALM	the domain of the server. It must always be capitalized.

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

oracle/dbserver.someco.com@SOMECO.COM

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

To create the service principal, run kdb5_edit. The following example is UNIX specific.

# cd /krb5/admin
# ./kdb5_edit

To add a principal called "oracle/dbserver.someco.com@SOMECO.COM" to the list of server principals known by Kerberos, type the following:

kdb5_edit:ark oracle/dbserver.someco.com@SOMECO.COM

4.1.3 Extract a Service Table from Kerberos

You now need to 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, do the following:

kdb5_edit:  xst dbserver.someco.com oracle 
'oracle/dbserver.someco.com@SOMECO.COM' added to keytab 
'WRFILE:dbserver.someco.com-new-srvtab' 
kdb5_edit:  exit
oklist -k -t dbserver.someco.com-new-srvtab

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 kdb5_edit to append the additional entries.

If you do not enter a realm (for example, SOMECO.COM) when using xst, it uses the realm of the current host and displays it in the command output, as shown above.

If the Kerberos service table is on the same machine as the Kerberos client, you can simply move it. If the service table is on a different machine from the Kerberos client, you must transfer the file with a program like binary FTP. The following example is UNIX specific.

# mv dbserver.someco.com-new-srvtab /etc/v5srvtab

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

4.1.3.1 Ensure that the Oracle Server Can Read the Service Table

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

4.1.4 Install an Oracle Server and an Oracle Client

Install an Oracle Server and an Oracle Client. Refer to your operating system-specific documentation for information.

4.1.5 Install Net8

Install Net8 on the Oracle server and client machines.

4.1.6 Configure Net8 and Oracle on the Oracle Server and Client

For information on how to configure the Oracle server and client machines, see your operating system-specific documentation. Also refer to the Oracle Net8 Administrator's Guide.

4.1.7 Create a Kerberos User on the Kerberos Authentication Server

Perform the following steps on the Kerberos authentication server, where the administration tools are installed, to create Oracle users so that they can be authenticated by the Kerberos adapter.

It is assumed that the realm already exists. Refer to the Kerberos documentation listed in the "Preface" if the realm needs to be created.

Run /krb5/admin/kdb5_edit as root to create the new Kerberos user, for example, "krbuser". The following example is UNIX specific.

# ./kdb5_edit
kdb5_edit: ank krbuser
Enter password:  <password not echoed to screen>
Re-enter password for verification:  <password...>
kdb5_edit: quit

4.1.8 Create an Externally-Authenticated User on the Oracle Database

Run Server Manager 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 "".

SVRMGR> connect internal;
SVRMGR> create user "KRBUSER@SOMECO.COM" identified externally; 
SVRMGR> grant create session to "KRBUSER@SOMECO.COM"; 

Remember that the Oracle user name must be in upper-case and double-quoted: for example, "KRBUSER@SOMECO.COM".

4.1.9 Get an Initial Ticket for the Kerberos/Oracle User

Users need to run the following:

okinit (user name)

on the client to ask the Key Distribution Center (KDC) for an initial ticket before they can connect to the database. If, when making a database connection, a reference such as

sqlplus /@oracle

will follow a database link, you must use the forwardable flag (-f option). 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 krbuser@SOMECO.COM:<password not echoed to screen>

4.1.10 Utilities to Use with the Kerberos Authentication Adapter

The following three utilities are shipped with the Oracle Kerberos authentication adapter. You should be on the Oracle client before running these commands.

• 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 customers who are running an Oracle client with an Oracle Kerberos authentication adapter installed.

4.1.10.1 Use okinit to Obtain the Initial Ticket

okinit obtains and caches Kerberos tickets. okinit is typically used to obtain your 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 following options are available with okinit.

Available okinit Options

-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). For example, okinit -l 2wld6h20m30s means ask for a ticket-granting ticket that has a lifetime 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.

4.1.10.2 Use oklist to Display Credentials

Users can run oklist to display the list of tickets they hold. The show flag option (-f) displays additional information.

% oklist -f
27-Jul-1995 21:57:51   28-Jul-1995 05:58:14
krbtgt/SOMECO.COM@SOMECO.COM
Flags: FI 

Available oklist Options

-f	Show flags with credentials. The important ones for Oracle are `I' (credential is a ticket-granting ticket), `F' (credential is forwardable), and `f' (credential is forwarded).
-c	Specify an alternative credential cache. For 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.

4.1.10.3 Use okdstry to Remove Credentials from Cache File

Use okdstry to remove credentials from the credentials cache file.

$ okdstry -f

Available okdstry Options

-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 a profile (SQLNET.ORA).

4.1.11 Connecting to an Oracle Server Authenticated by Kerberos

You can now connect to an Oracle Server without using a username or password. Enter a command like the following:

$ sqlplus /@service_name

where service_name is a Net8 service name. For example:

$ sqlplus /@oracle_dbname

Refer to Chapter 1, "Network Security and Single Sign-On" and to Oracle8 Server Distributed Systems for more information on external authentication.

4.2 Configure the Kerberos Authentication Adapter Using the Oracle Net8 Assistant

The following steps show you how to use the Net8 Assistant to configure the Kerberos authentication adapter. Refer also to the Net8 Assistant on-line HELP system for instructions on how to configure the Kerberos Authentication adapter.

Configure Clients, and Servers, to use encryption as follows. Refer to Figure 4-1, "Oracle Net8 Assistant Profile Encryption Tab".

1. Click the Profile folder.
2. Select Advanced Networking Options from the drop-down list box.
3. Click the Encryption tab.
4. Click the Encryption drop-down list box, and click CLIENT or SERVER.
5. Click the Encryption Type drop-down list box, and click one of the following values: requested, required, accepted, rejected.
6. Type between 10 and 70 random characters for the Encryption Seed.
7. Move services to and from the Available Services and Selected Services lists by selecting a service and clicking the arrow keys.

   Figure 4-1 Oracle Net8 Assistant Profile Encryption Tab

   

Next, you must configure an authentication service on your network. Refer to Figure 4-2, "Oracle Net8 Assistant Profile Authentication Tab".

1. Click the Profile folder.
2. Click the Authentication tab.
3. Click to select the authentication service you want from the Available Services list.
4. Click the [<] button to move the service over to the Selected Services list.
5. Repeat steps 4 and 5, above, until you have selected all of your required authentication services.
6. Arrange the selected services in order of desired use. Click on a service to select it, then click [Promote] or [Demote] to arrange the services in the list. For example, put KERBEROS5 at the top of the list if you want that service to be the first one used.

   Figure 4-2 Oracle Net8 Assistant Profile Authentication Tab

   

You now must configure the authentication parameters. Refer to Figure 4-3, "Oracle Net8 Assistant Profile Parameter Tab". You must provide the value for the following parameters.

• Service
• Credential Cache File
• Configuration File
• Realm Translation File
• Key Table
• Clock Skew

  Figure 4-3 Oracle Net8 Assistant Profile Parameter Tab

  

4.3 Description of Configuration File Parameters on Oracle Server and Client

This section describes the parameters that need to exist in configuration files on Oracle servers and clients for Kerberos to authenticate users.

4.3.1 Oracle Client Configuration Parameters

4.3.1.1 Required Profile Parameters

Make sure the following line is present in the profile (SQLNET.ORA) on the client:

sqlnet.authentication_services=(KERBEROS5)

4.3.2 Oracle Server Configuration Parameters

4.3.2.1 Required Profile Parameters

Make sure the following parameters are present in the profile (SQLNET.ORA) on the server:

sqlnet.authentication_services=(KERBEROS5)
sqlnet.authentication_kerberos5_service=kservice





Note:



The second parameter specifies the name of the service Oracle will use to obtain a Kerberos service ticket. You must substitute a value for the kservice part of the service name.

  

Example:

sqlnet.authentication_kerberos5_service=oracle

There is no default; you must define one.

4.3.2.2 Required Initialization Parameters

You must add the following parameter to the INIT.ORA file used for the database instance:

REMOTE_OS_AUTHENT=FALSE





Attention:



Setting REMOTE_OS_AUTHENT to TRUE may create a security hole, because it allows someone using a non-secure protocol (for example, TCP) to perform an operating system-authorized login (formerly referred to as an OPS$ login).

  

Because Kerberos user names can be long and Oracle user names are limited to 30 characters, it is strongly recommended that the following null value be used for the value of OS_AUTHENT_PREFIX:

OS_AUTHENT_PREFIX=""

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

After modifying the configuration files, restart the Oracle server so that the changes will take effect. (For information on how to restart the Oracle server refer to your operating system-specific documentation and to the Oracle8 Administrator's Guide.)

4.3.2.3 Optional Profile Parameters

In addition to the above required parameters, you can optionally set the parameters described below on the client or server. The string:

SQLNET.KERBEROS5_CC_NAME=pathname_to_credentials_cache_file

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.

For example:

SQLNET.KERBEROS5_CC_NAME=/usr/tmp/krbcache





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.

SQLNET.KERBEROS5_CLOCKSKEW=number_of_seconds_accepted_as_network_delay

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. It is also used by an Oracle server to decide if a credential needs to be stored to protect against a replay attack. The default is 300 seconds. For example:

SQLNET.KERBEROS5_CLOCKSKEW=1200

SQLNET.KERBEROS5_CONF=pathname_to_Kerberos_configuration_file

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. For example:

SQLNET.KERBEROS5_CONF=/krb5/krb.conf

SQLNET.KERBEROS5_KEYTAB=pathname_to_Kerberos_principal/key_table

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. For example:

SQLNET.KERBEROS5_KEYTAB=/etc/v5srvtab

SQLNET.KERBEROS5_REALMS=pathname_to_Kerberos_realm_translation_file

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. For example:

SQLNET.KERBEROS5_REALMS=/krb5/krb.realms

4.4 Troubleshooting the Configuration of the Kerberos Authentication Adapter

Some common configuration problems are listed below followed by tips on how to resolve them.

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

• Make sure the default realm is correct by looking at krb.conf.
• Make sure the KDC is running on the host specified for the realm.
• Make sure that the KDC has an entry for your user principal and that the passwords match.
• Make sure 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 exists in the correct location and is readable by Oracle (remember the SQLNET.ORA parameters).
• Check that the v5srvtab 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 okinit -f.)
• Check the expiration date on the credentials.
• If your credentials have expired, you must close your connection and run okinit to get a new initial ticket.

---