5
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

You enable Kerberos authentication by performing the following tasks, each of which is fully described in the next few pages.

Perform the following tasks in the order listed.

Step 1: Install Kerberos

Do this on the machine that will act as the authentication server

More Information:
For information on how to install Kerberos on your machine, see "Related Publications" in the Preface of this guide.

Step 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

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.

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: the actual names may vary among systems.

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

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

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.

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

Step 4: Install an Oracle server and an Oracle client

More Information:
See your operating system-specific documentation.

Step 5: Install Net8

Do this on the Oracle server and Oracle client machines.

More Information:
See the Net8 installation documentation

Step 6: Configure Net8 and Oracle

Do this on the Oracle server and client.

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

Step 7: Configure Kerberos authentication

You must set certain parameters in the Oracle server and client sqlnet.ora files. The next few pages explain how to do the following tasks.

Unless otherwise indicated, you can configure Kerberos authentication either by using the Net8 Assistant, or by modifying the sqlnet.ora file with any text editor.

Using Net8 Assistant

This graphical interface tool makes it easy to set parameters in the sqlnet.ora file and other Oracle8i configuration files.

To launch Net8 Assistant:

On UNIX, run the script netasst at $ORACLE_HOME/bin.
On Windows platforms, click the Start button > Programs > Oracle for Windows NT--HOME_NAME > Net8 Assistant.

To begin configuring the Oracle Advanced Security option using Net8 Assistant:

In the Net8 Assistant's left pane, click the Profile folder. Then go to the drop down list box at the top of the right pane, and select Advanced Security Option. The tabbed pages for the Oracle Advanced Security option appear.

To save changes with Net8 Assistant:

Go to the menu bar and click File > Save Network Configuration.

Configure the authentication service on the client and the server

Do this by setting the SQLNET.AUTHENTICATION_SERVICES parameter.

Figure 5-1 Using Net8 Assistant to Configure Authentication

Use the Net8 Assistant... ...or modify SQLNET.ORA

Refer to Figure 5-1.

Select the Authentication tab.

Select KERBEROS5 from the Available Services list.

Click the [>] button to move the service over to the Selected Services list. Move any other methods you want to use in the same way.

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.

Set the following parameter:
SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5)

Use the Net8 Assistant...	...or modify SQLNET.ORA
Refer to Figure 5-1. Select the Authentication tab. Select `KERBEROS5` from the Available Services list. Click the [>] button to move the service over to the Selected Services list. Move any other methods you want to use in the same way. 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.	Set the following parameter: SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5)

Configure authentication parameters on the Oracle server and client

Do this by setting the SQLNET.AUTHENTICATION_KERBEROS5_SERVICE parameter. You may also set various optional parameters described in this section.

Figure 5-2 Using Net8 Assistant to Configure Authentication Parameters

Use the Net8 Assistant... ...or modify SQLNET.ORA

Refer to Figure 5-2.

Select the Other Params tab.

In the Service text box, type kerberos. Note: You must provide the value for this parameter. When you do this, the other text boxes are enabled.

You may provide values for the following parameters:

Credential Cache File

Configuration File

Realm Translation File

Key Table

Clock Skew

You must set the following parameter:
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE=kservice
Note: The above 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.
Note also: The value passed by the parameter SQLNET.AUTHENTICATION_KERBEROS5_SERVICE is case sensitive; it must be lower case.
You may set the following parameters, each of which is described in the section "Optional SQLNET.ORA Parameters"

SQLNET.KERBEROS5_CC_NAME

SQLNET.KERBEROS5_CONF

SQLNET.KERBEROS5_REALMS

SQLNET.KERBEROS5_KEYTAB

SQLNET.KERBEROS5_CLOCKSKEW

Use the Net8 Assistant...	...or modify SQLNET.ORA
Refer to Figure 5-2. Select the Other Params tab. In the Service text box, type kerberos. Note: You must provide the value for this parameter. When you do this, the other text boxes are enabled. You may provide values for the following parameters: Credential Cache File Configuration File Realm Translation File Key Table Clock Skew	You must set the following parameter: SQLNET.AUTHENTICATION_KERBEROS5_SERVICE=kservice Note: The above 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. Note also: The value passed by the parameter SQLNET.AUTHENTICATION_KERBEROS5_SERVICE is case sensitive; it must be lower case. You may set the following parameters, each of which is described in the section "Optional SQLNET.ORA Parameters" SQLNET.KERBEROS5_CC_NAME SQLNET.KERBEROS5_CONF SQLNET.KERBEROS5_REALMS SQLNET.KERBEROS5_KEYTAB SQLNET.KERBEROS5_CLOCKSKEW

Set INIT.ORA Parameter

Use a text editor to 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, Oracle Corporation strongly recommends 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$.

Optional SQLNET.ORA Parameters

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

Parameter:

SQLNET.KERBEROS5_CC_NAME=pathname_to_credentials_cache_file

Description:

This parameter 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.

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

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. For example:
SQLNET.KERBEROS5_CONF=/krb/krb.conf

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. For 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. For example:
SQLNET.KERBEROS5_REALMS=/krb5/krb.realms

Step 8: Create a Kerberos user

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

It is assumed that the realm already exists.

More Information:
See "Related Publications" in the Preface of this guide.

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; these may vary among systems.

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

Step 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 "".

Note:
The Oracle user name must be in upper-case and double-quoted. For example, "KRBUSER@SOMECO.COM".

SQL> CONNECT INTERNAL;
SQL> CREATE USER "KRBUSER@SOMECO.COM" IDENTIFIED EXTERNALLY; 
SQL> GRANT CREATE SESSION TO "KRBUSER@SOMECO.COM";

Step 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. You do this by running the following on the client:

okinit (user name)

More Information:
For information on using okinit, see "Utilities for the Kerberos Authentication Adapter".

If, when making a database connection, a reference such as

sqlplus /@oracle

follows 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>

More Information:
For information about okinit, see "Use okinit to Obtain the Initial Ticket".

Utilities for 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.

Command Description

okinit

Gets an initial ticket

oklist

Displays a list of currently-owned tickets

okdstry

Removes all tickets from the credentials cache

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

UNIX Only:
Solaris is shipped with Kerberos version 4. Make sure that the Kerberos version 5 utilities are in your path so that the version 4 utilities are not inadvertently used.

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.

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

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

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

Option Description

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

Use okdstry to Remove Credentials from Cache File

Use okdstry to remove credentials from the credentials cache file.

$ okdstry -f

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 a profile (sqlnet.ora).

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 like 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, "Introduction to Oracle Advanced Security" 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:

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.

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.

Option	Description
`-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.

5 Configuring Kerberos Authentication