Configuring Kerberos Authentication

Kerberos is a trusted third-party authentication system that relies on shared secrets and presumes that the third party is secure.

Introduction to Kerberos on Oracle Database

Kerberos is a networked authentication system that Oracle uses authenticate Oracle Database users.

Kerberos Components in a Typical Oracle Database Configuration

The components in a typical Kerberos-authenticated configuration include the client, the Key Distribution Center (KDC), and an Oracle Database server.

The major configuration files are as follows:

Tickets Used in the Kerberos Configuration

Oracle Database uses both the Kerberos client ticket granting ticket (TGT) and the client service ticket.

Kerberos Client Ticket Granting Ticket

The client ticket granting ticket (TGT) describes the authorization to request services for the Kerberos connection.

The client reads the krb 5.conf file to find the Kerberos server so that it can receive this TGT (krbtgt). The TGT that is sent to the client enables the client to access the appropriate services in the Kerberos Realm without having to re-authenticate each time the user wants to access a different service in that realm.

Refer to How to Securely Use Database Links with Kerberos and Microsoft Active Directory for information on securely configuring TGT with Active Directory.

For example, in a Windows Active Directory domain, the Kerberos Realm is the same as the user’s Windows domain. After the user has logged into Active Directory, the user’s Windows credentials (Active Directory Kerberos tickets) can allow the user to access services in that Active Directory domain, if those services permit it.

The following oklist output shows an example of the tickets, which are automatically granted when a user first logs on as an Active Directory authenticated Windows user:

oklist
Kerberos Utilities for 32-bit Windows: Version 23.0.0.0.0 - Production on 15-MAY-2023 11:50:39
Copyright (c) 1996, 2023 Oracle Corporation. All rights reserved.
Ticket cache: win2kcc
Default principal: user_name@host_name
Valid Starting Expires Principal
22-Oct-2004 12:10:05 15-MAY-2023 22:10:05 krbtgt /host_name@realm_name renew until 29-Oct-2004 12:10:05
22-Oct-2004 12:10:05 15-MAY-2023 22:10:05 ldap/Active_Directory_host_name/host_name@realm_name renew until 29-Oct-2004 12:10:05

22-Oct-2004 12:10:05 15-MAY-2023 22:10:05 host/Active_Directory_host_name@host_name renew until 29-Oct-2004 12:10:05

This is similar to the Oracle Application Server single sign-on (SSO) application in that when the user receives SSO authentication, the user can access all applications in the SSO server’s “realm” (that is, those external and partner applications that have been registered with the SSO server) without having to authenticate. In the preceding example, the Active Directory TGT for realm_name was automatically populated by Active Directory in the Windows Ticket cache when the user logged into Domain controller realm_name.

When Active Directory issues a ticket, there are two places where Oracle Database can retrieve the Kerberos credential on a Windows client. You can specify which location to use by setting the KERBEROS5_CC_NAME parameter in the sqlnet.ora file. If you want them placed in a file called krb5.cc in your temp directory, then set KERBEROS5_CC_NAME as follows:

SQLNET.KERBEROS5_CC_NAME = temp

If you specify the cache location to be a directory, then you must manually populate it with the okinit utility, an Oracle-supplied Kerberos utility.

If you wanted to use the Windows Native credential cache (the one that is automatically populated with the krbtgt when you log on) you would use the following setting:

SQLNET.KERBEROS5_CC_NAME=OSMSFT://

Because this is a native cache, automatically populated with the user’s credentials when they log in to a Windows AD domain, the user does not need to use okinit. This location is normally fixed in an Active Directory environment.

You can use the Oracle-supplied utility okinit to populate the cache. To see the contents of the cache populated by okinit, run oklist utility. For example:

C:\> okinit user_name
Kerberos Utilities for 32-bit Windows: Version 23.0.0.0.0 - Production on 15-MAY-2023 12:32:53
Copyright (c) 1996, 2023 Oracle Corporation. All rights reserved.
Password for mailto:user_name@Realm : realm_name

C:\> oklist
Kerberos Utilities for 32-bit Windows: Version 23.0.0.0.0 - Production on 15-MAY-2023 12:33:02
Copyright (c) 1996, 2023 Oracle Corporation. All rights reserved.

Ticket cache: CC_path
Default principal: user_name@host_name
Valid Starting Expires Principal
15-MAY-2023 12:32:57 15-MAY-2023 20:32:54 krbtgt/host_name@realm_name

This output shows that the directory cache now has the TGT.

Kerberos Client Service Ticket

The client service ticket is generated after the user has successfully connected to the Oracle database.

From the client configuration side the configuration is complete. All the user needs to do is connect to the database using the following syntax (assuming the user has a TNS alias defined in the tnsnames.ora file):

sqlplus /@tns_alias

In this case the / slash does not mean an external operating system authentication, but an external Kerberos authentication.

To view the client service ticket, run the oklist command. For example:

oklist
....
Valid Starting Expires Principal

22-Oct-2022 12:32:57 22-Oct-2022 20:32:54 krbtgt/host_name@realm_name
22-Oct-2022 12:43:19 22-Oct-2022 20:32:54 server_principal/Active_Directory_host_name@realm_name

Kerberos Server Key Distribution Center

The server key distribution center (KDC) coordinates the Kerberos components that work with an Oracle database.

The KDC is comprised of a database that stores all the system’s principals and their associated encryption keys, a server to handle authentication, and the ticket granting server. With regard to Oracle Database, the KDC enables the following actions to take place:

How Oracle Database Works with Kerberos

To configure an Oracle database to work with Kerberos, you must set the userPrincipalName and servicePrincipalName attributes for the Oracle database in the Kerberos server.

On Windows, the userPrincipalName and servicePrincipalName are created by the ktpass utility; on Linux, they are created by the kadmin utility. These utilities create a keytab file (v5srvtab), which Oracle Database uses to authenticate the user. This file also stores the service name. When the client connects, it uses the SQLNET.AUTHENTICATION_KERBEROS5_SERVICE parameter to request the service name (which for Oracle Database, is oracle), and the SQLNET.KERBEROS5_KEYTAB parameter to find the keytab file. Oracle provides a set of sqlnet.ora parameters that you can use to configure an Oracle database to authenticate with Kerberos using the Kerberos attributes.

You can check the contents of the keytab file by running the following command:

oklist -k

Output similar to the following appears:

Kerberos Utilities for 32-bit Windows: Version 23.0.0.0.0 - Production on 15-MAY-2023 13:25:32
Copyright (c) 1996, 2023 Oracle Corporation. All rights reserved.
Service Key Table: <Keytab file with oath>
Ver Timestamp Principal

15-MAY-2023 16:00:00 server_principal/Active_Directory_host@host_name

Related Topics

How to Securely Use Database Links with Kerberos and Microsoft Active Directory

When using Windows Active Directory, the [KERBEROS5_DELEGATION_MODE](/pls/topic/lookup?ctx=en/database/oracle/oracle-database/26/dbseg&id=NETRF-GUID-8F659C4E-F9FB-47DD-9528-F8DC42FC7452) sqlnet.ora parameter introduced in Oracle AI Database 23.26.1 and Oracle Database 19.30 allows you to constrain ticket granting ticket (TGT) forwarding. This allows for a more secure configuration, but requires additional configuration in Active Directory if you use database links.

The KERBEROS5_DELEGATION_MODE parameter only applies when the key distribution center (KDC) is Microsoft Active Directory. It can be set to either UNCONSTRAINED or CONSTRAINED.

Within Active Directory you can also set delegation to constrained or unconstrained. When delegation in Active Directory is constrained, you will likely need to add your database’s service principal name (SPN) to the list of allowed delegations.

KERBEROS5_DELEGATION_MODE=UNCONSTRAINED

Setting KERBEROS5_DELEGATION_MODE=UNCONSTRAINED is the default configuration. When set to UNCONSTRAINED, TGT forwarding is not restricted.

However, if the client is using the Microsoft’s Windows-specific MSLSA credential cache, which can be found on Windows 11 (22H2) and Windows Server 2025, a Windows feature called Credential Guard blocks TGT forwarding regardless of the KERBEROS5_DELEGATION_MODE parameter.

In older configurations of Windows database clients using MSLSA, check the value of the AllowTgtSessionKey registry key to determine if TGT forwarding was restricted. If set to 0 then TGT forwarding will also be restricted.

Active Directory delegation is unconstrained

When Active Directory delegation is unconstrained, TGT forwarding is unrestricted. However, as mentioned above it is likely to be blocked by Microsoft Credential Guard or the setting of AllowTgtSessionKey which would cause database link connections to fail.

Active Directory delegation is constrained

When Active Directory delegation is constrained and the database has been added to the allow list in Active Directory following the steps in Microsoft’s documentation, How to configure Kerberos Constrained Delegation for Web Enrollment proxy pages, then a database link connection will work as Active Directory will accept the TGT. You will want to make sure the configuration for the service account that issued the database server’s keytab file looks similar to the following: Shows the configuration required in Active Directory. Delegation should be set to Trust this user for delegation to specified services only followed by Use Kerberos only.

If the database is not properly added to the allow list in Active Directory, then Active Directory will block the TGT and a database link connection will fail.

KERBEROS5_DELEGATION_MODE=CONSTRAINED

Setting KERBEROS5_DELEGATION_MODE=CONSTRAINED is the more secure configuration as it prevents TGT forwarding to the server.

However, when TGT forwarding is constrained, it prevents CONNECT USER database links from working which are common for Active Directory and Kerberos authenticated sessions. For database links to work you will need to add the database to the allow list in Active Directory.

If Active Directory delegation is constrained and the database has already been added to the allow list in Active Directory following the steps in Microsoft’s documentation, How to configure Kerberos Constrained Delegation for Web Enrollment proxy pages, then you only need to set KERBEROS5_DELEGATION_MODE=CONSTRAINED in the sqlnet.ora file.

Tip:

Oracle recommends setting the delegation to constrained in both Active Directory and sqlnet.ora for the most secure configuration.

If Active Directory delegation is not yet set to constrained or the database has not been added to the allow list in Active Directory follow the steps for configuring constrained delegation for the first time:

  1. Temporarily set KERBEROS5_DELEGATION_MODE=UNCONSTRAINED in sqlnet.ora.

    For more information see KERBEROS5_DELEGATION_MODE in Oracle AI Database Net Services Reference.

  2. Follow the steps in Microsoft’s documentation, How to configure Kerberos Constrained Delegation for Web Enrollment proxy pages, to add the database as a trusted user for delegation. You will want to make sure the configuration for the service account that issued the database server’s keytab file looks similar to the following:\

    Shows the configuration required in Active Directory. Delegation should be set to Trust this user for delegation to specified services only followed by Use Kerberos only.

  3. Confirm the database was properly added to the allow list in Active Directory.

  4. Set KERBEROS5_DELEGATION_MODE=CONSTRAINED in sqlnet.ora.

    This results in a secure connection while still allowing for connection through database links.

    For more information see KERBEROS5_DELEGATION_MODE in Oracle AI Database Net Services Reference.

If the database is not properly added to the allow list in Active Directory, then a database link connection will fail as TGT forwarding is restricted by both the client and server.

Oracle Database Parameters Used in a Kerberos Configuration

Oracle Database provides client and server parameters for using Kerberos authentication.

The following table lists parameters to insert into the configuration files for clients and servers using Kerberos.

File Name Configuration Parameters
sqlnet.ora SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5): Set on both client and server.
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE=oracle: Set on both client and server.
SQLNET.KERBEROS5_CC_NAME=/usr/tmp/DCE-CC: Not normally required on the server. If your client is on Microsoft Windows and is part of a domain, you may want to consider using the in-memory ticket cache and set this parameter to OSMSFT:// or MSLSA:.
SQLNET.KERBEROS5_CLOCKSKEW=1200: Set on both client and server.
SQLNET.KERBEROS5_CONF=/krb5/krb.conf: Set on both client and server. (Normally, this path in the client is different from the path in the server.)
SQLNET.KERBEROS5_CONF_MIT=(TRUE): Set this to TRUE on both the client and the server.
SQLNET.KERBEROS5_REALMS=/krb5/krb.realms: This setting is not usually required for the client or the server.
SQLNET.KERBEROS5_KEYTAB=/krb5/v5srvtab: Only set this parameter on the server, not the client.
SQLNET.FALLBACK_AUTHENTICATION=FALSE: Set on both client and server.
initialization parameter file OS_AUTHENT_PREFIX="": Set this parameter only on the server, not the client.

Related Topics

How Authentication Works in an Oracle Database Kerberos Configuration

The Kerberos authentication flow relies on the Kerberos-specific parameters that you set in the sqlnet.ora file and the krb5.conf file settings.

Authentication Flow

  1. The user logs in to the client, which then obtains a ticket granting ticket (TGT).

    • If the Oracle database is using the native windows cache, then the TGT is automatically obtained when the user logs in. The sqlnet.ora file must have the following setting so that the TGT can be obtained:

      SQLNET.KERBEROS5_CC_NAME=OSMSFT://

      Alternatively, you can set it to MSLSA:.

    • If the Oracle database is using a directory cache, then the sqlnet.ora file must have the following parameter set so that the database can find the location of the Kerberos server:

      SQLNET.KERBEROS5_CC_NAME=CC_file_name_path

      In addition, you must use the okinit utility to populate the cache with the TGT. The oklist utility will display the contents of the cache, okdstry will clear it, and the sqlnet.ora parameter (TRACE_LEVEL_OKINIT=16) will allow you to trace problems with an sqlnet.ora trace.

      However, this type is not normally used on the server. If your client is on Microsoft Windows and is part of a domain, you may want to consider using the in-memory ticket cache and set the SQLNET.KERBEROS5_CC_NAME parameter to OSMSFT:// or MSLSA:.

  2. The client connects to the database:

    sqlplus /@tns_alias

    The Oracle database then performs the following actions:

    • Retrieves the TGT from the location specified by the SQLNET.KERBEROS5_CC_NAME parameter

    • Reads the Kerberos service name from the SQLNET.AUTHENTICATION_KERBEROS5_SERVICE parameter

    • Packages the information from these parameters and sends it to the Kerberos server key distribution center (KDC), which will send back to the client a service ticket that is encrypted with the Oracle database’s key

  3. The client writes the encrypted service ticket to the credential cache and sends it to the Oracle database, which will decrypt the message by using a key from the keytab file.

  4. The Oracle database receives the client request, and performs the following actions.

    • Decodes the service ticket, extracting the following information: the requesting user’s principal, the service principal, the list of IP addresses, the date and time when the service ticket was issued

    • Matches the service principal with the principal that is stored in the stored in the keytab file

    • Searches the user name table in the database for the user name that was extracted from the TGT. If the user exists and there is an authentication match, then the user is granted access.

  5. If the preceding steps are successful, then the client connects.

Client Configuration Files Used to Complete the Connection

krb5.conf file settings:

#

[libdefaults]
default_realm = realm name
kdc = KDC_host:port
}

realm name = {
kdc = KDC_host:port
}

[domain_realm]
.domain = host_name

Client sqlnet.ora file settings:

NAMES.DIRECTORY_PATH= (TNSNAMES)
NAMES.DEFAULT_DOMAIN = default_domain
trace_level_server=16
trace_level_client=16
trace_file_client=client_prefix
trace_directory_client=directory_path
trace_unique_client=true
trace_level_okinit=16
SQLNET.KERBEROS5_CONF=krb5.conf_path
SQLNET.KERBEROS5_CONF_MIT=TRUE
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE=server_principal
SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5)
SQLNET.KERBEROS5_CC_NAME=CC_filename_path
# SQLNET.KERBEROS5_CC_NAME=OSMSFT://
trace_level_okinit=16

Server Parameter Configuration

sqlnet.ora file settings on the Oracle Database server:

NAMES.DIRECTORY_PATH= (TNSNAMES)
NAMES.DEFAULT_DOMAIN = default_domain
trace_level_server=16
trace_level_client=16
trace_file_client=file_name_prefix
trace_directory_client=directory_path
trace_unique_client=true
SQLNET.KERBEROS5_CONF=krb5.conf_path
SQLNET.KERBEROS5_KEYTAB=keytab_file_path
SQLNET.KERBEROS5_CONF_MIT=TRUE
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE=server_principal
SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5)
SQLNET.KERBEROS5_CC_NAME=CC_file_name_path
# SQLNET.KERBEROS5_CC_NAME=OSMSFT://