Database Access with Amazon RDS Oracle with Kerberos Authentication
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:
- Configure your Amazon RDS for Oracle database with Kerberos authentication.
- Add the database to your Teleport cluster.
- 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
andtsh
clients.Installing
tctl
andtsh
clients-
Determine the version of your Teleport cluster. The
tctl
andtsh
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:443TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" -
Follow the instructions for your platform to install
tctl
andtsh
clients:- Mac
- Windows - Powershell
- Linux
Download the signed macOS .pkg installer for Teleport, which includes the
tctl
andtsh
clients:curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkgIn Finder double-click the
pkg
file to begin installation.dangerUsing 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.
curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zipUnzip the archive and move the `tctl` and `tsh` clients to your %PATH%
NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
All of the Teleport binaries in Linux installations include the
tctl
andtsh
clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our installation page.curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gztar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gzcd teleportsudo ./installTeleport binaries have been copied to /usr/local/bin
-
- 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 runtctl
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:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 18.2.4
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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:
- Follow the Amazon RDS Oracle Kerberos Setup guide to enable Kerberos authentication on your instance.
- Enable TLS on your Oracle RDS instance by following the Amazon RDS Oracle SSL Setup documentation. Ensure
SQLNET.SSL_VERSION
is set to1.2
for optimal security. Make note of the SSL port choice; in the rest of the guide we will assume it is 2484. Also ensureSQLNET.CIPHER_SUITE
parameter includes a supported value, for exampleTLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
.
Verify connectivity between your Teleport Database Service host and the Oracle RDS instance before proceeding.
Step 2/9. Create Oracle AD users
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]";
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
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:
- Ubuntu
- RHEL / CentOS 7
sudo apt-get updatesudo apt-get -y install sssd realmd krb5-user samba-common packagekit adcli
sudo yum -y updatesudo yum -y install sssd realmd krb5-workstation samba-common-tools
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:
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 listexample.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:
- Ubuntu 18.04
- Ubuntu 20.04
- Ubuntu 22.04
- RHEL 8
- RHEL 9
- Other
curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asccurl https://packages.microsoft.com/config/ubuntu/18.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.listsudo apt-get updatesudo ACCEPT_EULA=Y apt-get install -y adutil
curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asccurl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.listsudo apt-get updatesudo ACCEPT_EULA=Y apt-get install -y adutil
curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asccurl https://packages.microsoft.com/config/ubuntu/22.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.listsudo apt-get updatesudo ACCEPT_EULA=Y apt-get install -y adutil
sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/8/prod.reposudo ACCEPT_EULA=Y yum install -y adutil
sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/9/prod.reposudo ACCEPT_EULA=Y yum install -y adutil
If adutil
is not available for your distribution, you can use ktutil
instead. It should be available as a standard Kerberos utility.
Adjust usage based on the username and kvno
for the given user.
ktutilktutil: addent -password -p [email protected] -k 1 -e aes256-cts-hmac-sha1-96Password for [email protected]: [enter password here]ktutil: wkt teleport.keytabktutil: quit
Log in to Active Directory using the kinit
command:
kinit [email protected]
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 aliceadutil 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.
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.keytabKeytab name: FILE:teleport.keytabKVNO Principal---- -------------------------------------------------------------------------- 5 [email protected] (aes256-cts-hmac-sha1-96) 2 [email protected] (aes256-cts-hmac-sha1-96)
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=textabcd123-insecure-do-not-use-this
To install a Teleport Agent on your Linux server:
The easiest installation method, for Teleport versions 17.3 and above, is the cluster install script. It will use the best version, edition, and installation mode for your cluster.
-
Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).
-
Run your cluster's install script:
curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
On older Teleport versions:
-
Assign edition to one of the following, depending on your Teleport edition:
Edition Value Teleport Enterprise Cloud cloud
Teleport Enterprise (Self-Hosted) enterprise
Teleport Community Edition oss
-
Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:
TELEPORT_DOMAIN=teleport.example.com:443TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"Otherwise, get the version of your Teleport cluster:
TELEPORT_DOMAIN=teleport.example.com:443TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')" -
Install Teleport on your Linux server:
curl https://cdn.teleport.dev/install.sh | bash -s ${TELEPORT_VERSION} editionThe installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.
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:
Flag | Description |
---|---|
--ad-keytab-file | Path to Kerberos keytab file generated above. |
--ad-domain | Active 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.
- Package Manager
- TAR Archive
On the host where you will run the Teleport Database Service, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run the Teleport Database Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo 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
To modify an existing user to provide access to the Database Service, see Database Access Controls
- Teleport Community Edition
- Teleport Enterprise/Enterprise Cloud
Create a local Teleport user with the built-in access
role:
tctl users add \ --roles=access \ --db-users="*" \ --db-names="*" \ alice
Create a local Teleport user with the built-in access
and requester
roles:
tctl users add \ --roles=access,requester \ --db-users="*" \ --db-names="*" \ alice
Flag | Description |
---|---|
--roles | List of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport. |
--db-users | List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user. |
--db-names | List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database. |
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=alicetsh db lsName 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 oracleRemove 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 --tunnelStarted 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
- Learn how to restrict access to certain users and databases.
- View the High Availability (HA) guide.
- Take a look at the YAML configuration reference.
- See the full CLI 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
- Amazon RDS Oracle Kerberos Setup.
- Amazon RDS Oracle SSL Setup.
- Amazon RDS Oracle auditing.
- Manually join a Linux instance in the AWS documentation.
- Introduction to
adutil
in the Microsoft documentation.