Skip to main content
Version: 18.x

Database Access with Amazon RDS Oracle with Kerberos Authentication

Report an issue with this page

Teleport can provide secure access to Amazon RDS for Oracle via the Teleport Database Service. This allows for fine-grained access control through Teleport's RBAC.

In this guide, you will:

  1. Configure your Amazon RDS for Oracle database with Kerberos authentication.
  2. Add the database to your Teleport cluster.
  3. Connect to the database via Teleport.

How it works​

The Teleport Database Service joins the same Active Directory domain as the Oracle database and uses the Kerberos protocol to authenticate with Oracle. When a user connects to Oracle via Teleport, the Database Service obtains a service ticket from Active Directory, then uses a long-term key for the database user to decrypt the ticket and connect to Oracle. At that point, the Database Service forwards user traffic to the database.

Prerequisites​

  • A running Teleport (v17.4.0 or higher) cluster. If you do not have one, read Getting Started.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • An Amazon RDS for Oracle database instance.
  • An AWS Directory Service Managed Microsoft AD.
  • A Linux node joined to the same Active Directory domain as the database. This guide will walk you through the joining steps if you don't have one.
  • Oracle client. The default option is SQLcl, but alternative clients are discussed below.
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  18.2.4
    CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/9. Prepare the Oracle RDS Instance​

Before configuring Teleport, ensure your Oracle RDS instance has Kerberos authentication and TLS properly configured:

  1. Follow the Amazon RDS Oracle Kerberos Setup guide to enable Kerberos authentication on your instance.
  2. Enable TLS on your Oracle RDS instance by following the Amazon RDS Oracle SSL Setup documentation. Ensure SQLNET.SSL_VERSION is set to 1.2 for optimal security. Make note of the SSL port choice; in the rest of the guide we will assume it is 2484. Also ensure SQLNET.CIPHER_SUITE parameter includes a supported value, for example TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384.
note

Verify connectivity between your Teleport Database Service host and the Oracle RDS instance before proceeding.

Step 2/9. Create Oracle AD users​

note

You can skip this step if you already have Active Directory logins in your Oracle database.

Connect to your Oracle database as an administrative account (e.g. admin) and create users that will use Active Directory authentication:

CREATE USER "[email protected]" IDENTIFIED EXTERNALLY;
GRANT CREATE SESSION TO "[email protected]";
note

The username expected by Oracle RDS will be in uppercase followed by the realm name. Alternative spellings are likely to cause issues.

Step 3/9. Join the Linux node to Active Directory​

note

You can skip this step if you already have a Linux node joined to the same Active Directory domain as your Oracle instance.

The Linux node where the Database Service will run must be joined to the same Active Directory domain as the Oracle database.

Note that in order to be able to join, the Linux node must be able to resolve your Active Directory fully-qualified domain name. For example, for AWS-managed AD, use nameservers provided under "Networking details" on the directory's overview page.

Install necessary packages:

sudo apt-get update
sudo apt-get -y install sssd realmd krb5-user samba-common packagekit adcli

Edit /etc/krb5.conf to disable reverse DNS resolution and set the default realm. Make sure that the [realms] section contains your domain definition and has admin_server and kdc fields set pointing to the domain controllers:

[libdefaults]
default_realm = EXAMPLE.COM
rdns = false

[realms]
  EXAMPLE.COM = {
    kdc = example.com
    admin_server = example.com
  }

Join the realm:

sudo realm join -v -U [email protected] example.com
... * Successfully enrolled machine in realm
warning

Note that the realm name in [email protected] must be capital case, otherwise the node might not be able to join.

To confirm the node has joined the realm, use the realm list command:

sudo realm list
example.com  type: kerberos  realm-name: EXAMPLE.COM  domain-name: example.com  configured: kerberos-member  server-software: active-directory  client-software: sssd  ...

Step 4/9. Create keytab file​

Teleport requires a keytab file to obtain Kerberos service tickets from Active Directory for authentication with Oracle database. The easiest way to generate it is to use the adutil Linux CLI utility.

Install adutil on the Linux node you have joined to your Active Directory domain:

curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc
curl https://packages.microsoft.com/config/ubuntu/18.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y adutil

Log in to Active Directory using the kinit command:

Use the adutil keytab create command to generate keytab entries for each Active Directory user that will be connecting to the Oracle database:

adutil keytab create teleport.keytab alice
adutil keytab create teleport.keytab bob

You will be prompted to enter each user's password. All keytab entries will be merged into the same teleport.keytab file.

Assign Service Principal Names

For the adutil keytab create command to work, each user account must be assigned a Service Principal Name, otherwise the command will not be able to determine its kvno (key version number).

To check if the user has any SPNs assigned, go to the user's page in AWS Console and locate the "Account settings - optional" section.

Alternatively, run the following command on the Windows machine joined to your Active Directory domain:

setspn -L alice

To assign an SPN to a user account, use the following command:

setspn -s user/alice alice

You can verify entries in the keytab file using klist command:

klist -ke teleport.keytab
Keytab name: FILE:teleport.keytabKVNO Principal---- --------------------------------------------------------------------------   5 [email protected] (aes256-cts-hmac-sha1-96)   2 [email protected] (aes256-cts-hmac-sha1-96)
warning

You must update the keytab file after updating a user's password to avoid authentication failures.

Step 5/9. Set up the Teleport Database Service​

The Database Service requires a valid join token to join your Teleport cluster. Run the following tctl command and save the token output in /tmp/token on the server that will run the Database Service:

tctl tokens add --type=db --format=text
abcd123-insecure-do-not-use-this

To install a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

  1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).

  2. Run your cluster's install script:

    curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
note

Teleport Database Service must run on a Linux server joined to the same Active Directory domain as the Oracle instance.

Configure the Teleport Database Service. Make sure to update --proxy to point to your Teleport Proxy Service address and --uri to the Oracle endpoint. Note the specified port must be one configured as part of SSL configuration, which defaults to 2484.

sudo teleport db configure create \    -o file \    --token=/tmp/token \    --proxy=teleport.example.com:443 \    --name=oracle \    --protocol=oracle \    --uri=oracle-instance.aabbccddeegg.eu-central-1.rds.amazonaws.com:2484 \    --ad-keytab-file=/etc/teleport/teleport.keytab \    --ad-domain=EXAMPLE.COM \    --labels=env=dev

Provide Active Directory parameters:

FlagDescription
--ad-keytab-filePath to Kerberos keytab file generated above.
--ad-domainActive Directory domain (Kerberos realm) that Oracle is joined.

Step 6/9. Start the Database Service​

Configure the Teleport Database Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Database Service.

On the host where you will run the Teleport Database Service, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

You can check the status of the Teleport Database Service with systemctl status teleport and view its logs with journalctl -fu teleport.

Step 7/9. Create a Teleport users​

tip

To modify an existing user to provide access to the Database Service, see Database Access Controls

Create a local Teleport user with the built-in access role:

tctl users add \  --roles=access \  --db-users="*" \  --db-names="*" \  alice
FlagDescription
--rolesList of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport.
--db-usersList of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user.
--db-namesList of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database.
warning

Database names are only enforced for PostgreSQL, MongoDB, and Cloud Spanner databases.

For more detailed information about database access controls and how to restrict access see RBAC documentation.

Step 8/9. (Optional) Configure Teleport to pull audit logs from Oracle Audit Trail​

Teleport can pull audit logs from Oracle Audit Trail. In order to enable this feature, you will need to configure Oracle Audit Trail and create a dedicated Teleport user that will be used to fetch audit events from Oracle Audit Trail.

Create an internal Oracle [email protected] user that will fetch audit events from Oracle Audit Trail:

CREATE USER "[email protected]" IDENTIFIED EXTERNALLY;
GRANT CREATE SESSION TO "[email protected]";
GRANT SELECT ON SYS.DBA_AUDIT_TRAIL TO "[email protected]";
GRANT SELECT ON SYS.V_$SESSION TO "[email protected]";

Create the corresponding [email protected] user in AD.

Enable standard auditing by modifying the RDS Oracle parameter group audit_trail to contain db,extended.

Reboot your Oracle instance to propagate audit trail changes.

Enable Oracle auditing for the alice user:

AUDIT ALL STATEMENTS by "[email protected]" BY access;

You must enable auditing for each Teleport user that will be used to connect to Oracle. Additionally you can create a different audit policy for each user.

Edit the Database Service configuration to specify the audit user you created earlier.

db_service:
  enabled: true
  databases:
  - name: "oracle"
    protocol: "oracle"
    uri: "oracle-instance.aabbccddeegg.eu-central-1.rds.amazonaws.com:2484"
    ad:
      keytab_file: "/etc/teleport/teleport.keytab"
      domain: "EXAMPLE.COM"
      krb5_file: "/etc/krb5.conf"
+   oracle:
+     audit_user: "teleport"

Teleport doesn't clean up audit trail events from Oracle Audit Trail. Make sure to configure an Oracle Audit Trail cleanup policy to avoid running out of disk space.

Step 9/9. Connect​

Log in to your Teleport cluster. Your Oracle database should appear in the list of available databases:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name   Description         Labels
------ ------------------- -------
oracle                     env=dev

Connect to the database. This requires SQLcl client available in PATH as sql.

tsh db connect --db-user=alice --db-name ORCL oracle

To log out of the database and remove credentials:

Remove credentials for a particular database instance.
tsh db logout oracle
Remove credentials for all database instances.
tsh db logout

As an alternative to SQLcl you can also use other clients together with the tsh proxy db command, which will open a tunnel for other clients to use. For example:

tsh proxy db --db-user=alice --db-name ORCL oracle --port 12345 --tunnel
Started authenticated tunnel for the Oracle database "oracle" in cluster "teleport.example.com" on 127.0.0.1:12345.
Use the following command to connect to the Oracle database server using CLI:  $ sql -L /@localhost:12345/ORCL
Other clients can use:  - a direct connection to 127.0.0.1:12345 without a username and password  - a custom JDBC connection string: 'jdbc:oracle:thin:@tcps://localhost:12345/ORCL?TNS_ADMIN=/home/alice/.tsh/keys/teleport.example.com/alice-db/teleport.example.com/oracle-wallet'

This method also enables use of various graphical clients, as explained in Oracle graphical clients section.

Next steps​

  • Take a look at the YAML configuration reference.

Troubleshooting​

Connection hangs or is refused​

A common issue when connecting to an Oracle database is a connection timeout or refusal. This typically indicates a networking problem where the Teleport Database Service cannot reach the Oracle database endpoint. Verify that network routing and access controls, such as firewalls and VPC security groups, allow traffic to flow from the Database Service host to the database endpoint.

You can validate connectivity using a native Oracle client, which helps confirm whether the issue is with Teleport or the underlying network configuration. For example, using Oracle SQLcl:

# Example: Oracle SQLcl
sql -L myuser/[email protected]:2484

Network connectivity issues are often detected by automated health checks.

To check the health status of all registered databases:

# All databases
tctl db ls --format=json | jq -r '.[] | [.metadata.name, .status.target_health]'

An unhealthy database will have output similar to the following:

...
  "oracle",
  {
    "address": "11.22.33.44:2484",
    "protocol": "TCP",
    "status": "unhealthy",
    "transition_timestamp": "2025-09-25T09:47:39.435973Z",
    "transition_reason": "threshold_reached",
    "transition_error": "dial tcp 11.22.33.44:2484: i/o timeout",
    "message": "1 health check failed"
  }
...

TLS negotiation fails​

Properly configuring TLS on an Oracle database can be challenging. Different underlying issues can result in the same error message, such as the following from Teleport:

Original Error: *tls.permanentError remote error: tls: handshake failure

Or you might see the following in the Oracle logs:

ORA-00609: could not attach to incoming connection
ORA-28860: Fatal SSL error

To identify the root cause, follow the debugging steps in the sections below. The output of the following openssl command can help diagnose many common TLS issues. Capture the output and use it as you follow the debugging steps.

> openssl s_client -connect oracle.example.com:2484 -showcerts

Wrong server certificate​

Teleport rejects connections to databases with untrusted server certificates. If you are using Teleport to issue certificates, ensure that the server certificate was issued by the Teleport Database CA. An invalid server certificate will prevent Teleport from establishing a secure connection.

You can view the Teleport Database CA certificate with the following command:

tctl auth export --type=db | openssl x509 -issuer -noout
...
issuer=O=teleport.example.com, CN=teleport.example.com, serialNumber=200129862304303044762346177566738813560

Compare the issuer in the server certificate with the issuer of the Teleport Database CA certificate. The openssl s_client command from the previous section will show you the server certificate:

# openssl s_client output:
...
Server certificate
subject=CN=oracle.example.com
issuer=O=teleport.example.com, CN=teleport.example.com, serialNumber=200129862304303044762346177566738813560
...

You can also inspect the Oracle wallet directly using the orapki utility to verify the server certificate.

# Prompt for wallet password
orapki wallet display -complete -wallet /path/to/wallet

The "User Certificates" section of the output should contain the server's certificate. Its Issuer should match the Subject of the Teleport Database CA.

User Certificates:
Subject:        CN=oracle.example.com
Issuer:         SERIALNUMBER=200129862304303044762346177566738813560,CN=teleport.example.com,O=teleport.example.com
Serial Number:  ...

Wrong client certificate​

If the Oracle server rejects client certificates presented by the Teleport Database Service, you should verify that the Oracle database trusts the Teleport Database User CA.

You can view the Teleport Database User CA with this command:

tctl auth export --type=db-client | openssl x509 -issuer -noout
issuer=O=teleport.example.com, CN=teleport.example.com, serialNumber=183359545647055551607366887578713393931

Compare the Teleport Database User CA with the list of CAs trusted by the Oracle database. The openssl s_client command from earlier will show the list of CAs the Oracle database trusts:

# openssl s_client output:
...
---
Acceptable client certificate CA names
O=teleport.example.com, CN=teleport.example.com, serialNumber=183359545647055551607366887578713393931

Ensure that the Teleport Database User CA certificate has been added to the correct wallet and that the Oracle server configuration references this wallet.

You can also inspect the Oracle wallet directly using the orapki utility to verify that the Teleport Database User CA is trusted.

# Prompt for wallet password
orapki wallet display -complete -wallet /path/to/wallet

The "Trusted Certificates" section of the output should contain the Teleport Database User CA. Its Issuer should match the issuer of the Teleport Database User CA.

Trusted Certificates:
Subject:        SERIALNUMBER=183359545647055551607366887578713393931,CN=teleport.example.com,O=teleport.example.com
Issuer:         SERIALNUMBER=183359545647055551607366887578713393931,CN=teleport.example.com,O=teleport.example.com
Serial Number:  ...

Wrong TLS version​

Teleport rejects connections that use TLS 1.0 or 1.1 due to known weaknesses. Ensure that the SSL_VERSION parameter in your Oracle configuration is set to 1.2 or higher to enable TLS 1.2 or a newer version.

No common cipher suites​

Ensure that the SQLNET.CIPHER_SUITE parameter in your Oracle configuration contains modern TLS cipher suites that match the configured TLS version. The following cipher suites are secure and widely supported across different Oracle versions.

For TLS 1.2:

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

For TLS 1.3:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384

Must be logged on to the server error​

The following error indicates that the login procedure has failed:

ORA-17430: Must be logged on to the server.

This is most commonly caused by the Oracle database enforcing native encryption or data-integrity checksums on a TCPS endpoint. Teleport uses TLS for transport security, and does not support native Oracle encryption.

To disable the redundant encryption requirement for the TCPS endpoint, add the following line to your sqlnet.ora file:

SQLNET.IGNORE_ANO_ENCRYPTION_FOR_TCPS=TRUE

Make sure to use an up-to-date version of the Oracle database. In older versions, this setting may not disable data-integrity checksums, which will lead to continued failures.

Invalid username​

An incorrectly specified username will result in the following error:

ORA-01017: invalid username/password; logon denied

When using TLS-based authentication, Oracle maps the Common Name (CN) from the client certificate to an external user in the database. Verify the EXTERNAL_NAME for your user in the dba_users table. It should be in the format cn=<name>, where <name> matches the value of the --db-user flag used in the tsh db login command.

You can query the dba_users table to check the EXTERNAL_NAME of your users:

SQL> SELECT username, authentication_type, external_name
  2  FROM   dba_users
  3  WHERE  authentication_type = 'EXTERNAL'
  4  ORDER  BY 1;

USERNAME      AUTHENTICATION_TYPE    EXTERNAL_NAME
_____________ ______________________ ________________
ALICE         EXTERNAL               cn=alice

Username not recognized​

If your logins are rejected, verify the username being used. Pay special attention to follow lowercase/uppercase conventions when referring to particular username. Typical setup will see:

  • Lowercase, domain-less user passed to tsh commands, for example: --db-user alice
  • Lowercase, domain-less user when creating keytab (e.g.: alice)
  • Uppercase, domain-qualified user in Oracle database (e.g.: [email protected])

Installation-specific configuration variations may lead to different values, however. Consult your local AD administrator for guidance.

Further reading​