Oracle Kerberos setup

Configure DataStar to authenticate to Oracle using the Windows logged-on user's Kerberos credentials — no passwords, no kinit, no MIT Kerberos for Windows.

This page covers Oracle only. SQL Server uses Windows Authentication directly through the Database Connection dialog and needs none of this configuration.

How it works

DataStar's Oracle driver (Oracle.ManagedDataAccess.Core) ships with a built-in Kerberos plug-in (Oracle.ManagedDataAccess.Kerberos + Kerberos.NET). When a connection is opened with external authentication, the plug-in asks the Windows LSA (Local Security Authority) for a Kerberos service ticket for the Oracle database's service principal, using the ticket-granting ticket (TGT) that Windows already obtained at logon. That ticket is sent to the database, which maps the Kerberos principal to a database user and establishes the session.

The line that selects "use the Windows logon session" is one entry in sqlnet.ora:

SQLNET.KERBEROS5_CC_NAME = MSLSA:

Use MSLSA:, not OSMSFT://

OSMSFT:// is the credential-cache token recognised by ODP.NET, Managed Driver (the .NET Framework build). DataStar's Oracle driver does not recognise it — it interprets the value as a relative file path and fails with an error like:

The filename, directory name, or volume label syntax is incorrect. : '...\OSMSFT:\'

Use MSLSA: (note the trailing colon, no slashes).

Prerequisites

Client machine

Joined to the Active Directory domain.
The user (or service account) running DataStar logs on with their domain account, so Windows holds a valid TGT. Verify with klist — you should see a krbtgt/<REALM> entry that has not expired.

You do not need:

MIT Kerberos for Windows
A populated FILE: credential cache or kinit
The AllowTgtSessionKey registry change

The plug-in asks Windows for a service ticket directly, so none of those apply.

Active Directory and database side

These are one-time tasks for a DBA / AD admin:

A Service Principal Name matching the Oracle Kerberos service is registered on the database's service account, e.g. oracle/<oracle-host>@<REALM>. The oracle portion must match SQLNET.AUTHENTICATION_KERBEROS5_SERVICE.
The database is configured for Kerberos: SQLNET.AUTHENTICATION_SERVICES includes KERBEROS5, plus OS_AUTHENT_PREFIX etc. as needed.
The Oracle login exists as an externally-identified user, e.g.
```
CREATE USER "<USER@REALM>" IDENTIFIED EXTERNALLY;
```
with the appropriate role grants.

`sqlnet.ora`

A common location is C:\oracle\network\admin\sqlnet.ora. The folder is pointed to from DataStar via either the TNS_ADMIN environment variable or the TnsAdmin Location field in the Database Connection dialog.

NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)

# Kerberos authentication.
# Use the Windows logon-session (LSA) ticket cache so the app picks up the
# current user's TGT automatically - no kinit, no file ccache to refresh.
SQLNET.AUTHENTICATION_SERVICES = (BEQ, KERBEROS5)
SQLNET.KERBEROS5_CC_NAME = MSLSA:
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE = oracle

# Only needed if the OS cannot resolve the realm/KDC on its own (rare on
# a domain-joined box, which uses DNS SRV records). Harmless to leave in.
SQLNET.KERBEROS5_CONF = C:\ProgramData\Kerberos\krb5.conf
SQLNET.KERBEROS5_CONF_MIT = TRUE

Setting	Purpose
`SQLNET.AUTHENTICATION_SERVICES = (BEQ, KERBEROS5)`	Enables Kerberos as an authentication method. `BEQ` is for local bequeath connections and is ignored over TCP — `(KERBEROS5)` alone also works.
`SQLNET.KERBEROS5_CC_NAME = MSLSA:`	The credential cache to read tickets from. `MSLSA:` means the Windows logon session — this is the line that makes "the app just uses Windows" work.
`SQLNET.AUTHENTICATION_KERBEROS5_SERVICE = oracle`	The service-name portion of the database's SPN (`oracle/<host>@<REALM>`). Must match what AD has registered.
`SQLNET.KERBEROS5_CONF` / `SQLNET.KERBEROS5_CONF_MIT`	Point at an MIT-style `krb5.conf`. On a domain-joined machine the OS resolves the realm and KDCs via DNS, so these are usually unnecessary; left in as a fallback.

`tnsnames.ora`

Define a TNS alias for the Kerberos-enabled service. Replace the placeholders with your own hostname, service name, and chosen alias:

MYORCL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = <oracle-host>)(PORT = 1521))
    (CONNECT_DATA = (SERVICE_NAME = <service-name>))
    (SECURITY = (AUTHENTICATION_KERBEROS5_SERVICE = oracle))
  )

The (SECURITY = ...) clause can also be set globally in sqlnet.ora instead — either location works.

Connecting from DataStar

Via the Database Connection dialog

Set Connection Type to DataSource.
Set Data Source to the TNS alias (e.g. MYORCL).
Set Authentication to Windows Authentication.
Set TnsAdmin Location to the folder containing sqlnet.ora (e.g. C:\oracle\network\admin).
Connect. The driver picks up your Windows ticket and negotiates Kerberos with Oracle.

Via a Custom connection string

If you use Connection Type: Custom, the connection string must request external (OS) authentication — User Id=/, with no user name and no password:

User Id=/;Data Source=MYORCL;

If a user name and password are supplied, the driver uses password authentication and Kerberos is never attempted.

Verifying

Check the Windows ticket cache:
```
klist
```
You should see a krbtgt/<REALM> entry with a future expiry. After connecting once, you should also see an oracle/<oracle-host>@<REALM> service ticket.
Use Test in the Database Connection dialog to verify the configuration without making the connection active.
Restart DataStar after editing sqlnet.ora — the driver reads it on process start / first connection, not continuously.

Troubleshooting

Symptom	Likely cause	Fix
`The filename, directory name, or volume label syntax is incorrect. : '...\OSMSFT:\'`	`SQLNET.KERBEROS5_CC_NAME` set to `OSMSFT://`, which DataStar's driver doesn't understand	Change to `SQLNET.KERBEROS5_CC_NAME = MSLSA:`
Worked once, now "ticket expired" / credential errors	`SQLNET.KERBEROS5_CC_NAME` points at a static `FILE:...` cache that nothing refreshes	Switch to `MSLSA:` so the live Windows TGT is used
`ORA-12641: Authentication service failed to initialize`	Kerberos config not loaded — wrong/missing TnsAdmin Location or `TNS_ADMIN`, app not reading this `sqlnet.ora`, or realm/KDC unresolvable	Confirm TnsAdmin Location points at the folder holding `sqlnet.ora`; run `klist` to confirm OS Kerberos works
`ORA-12638: Credential retrieval failed`	No valid TGT in the Windows cache, clock skew greater than 5 minutes, or the SPN is missing / registered on the wrong AD account	`klist` (re-login if no TGT); check time sync against the domain; have AD admin verify the `oracle/<host>` SPN
`ORA-01017: invalid username/password; logon denied`	Config is correct but the database has no externally-identified user for this Kerberos principal	Have a DBA run `CREATE USER "<USER@REALM>" IDENTIFIED EXTERNALLY;` plus the necessary grants
Connection uses a password instead of Kerberos	Connection string supplies user/password	Set Authentication to Windows Authentication, or use `User Id=/;` with no password in a Custom connection string

The same sqlnet.ora works for DataStar.Tools on build and deployment agents; see the CI/CD overview for how to point the CLI at it.

How it works​

Prerequisites​

Client machine​

Active Directory and database side​

sqlnet.ora​

tnsnames.ora​

Connecting from DataStar​

Via the Database Connection dialog​

Via a Custom connection string​

Verifying​

Troubleshooting​