Skip to main content
Version: 17.x

Database Access with AWS 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:

  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 cluster version 17.4.6 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • 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@example.com to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=email@example.com
    tctl status
    Cluster  teleport.example.com
    Version  17.4.6
    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 AWS RDS Oracle Kerberos Setup guide to enable Kerberos authentication on your instance.
  2. Enable TLS on your Oracle RDS instance by following the AWS 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 "ALICE@EXAMPLE.COM" IDENTIFIED EXTERNALLY;
GRANT CREATE SESSION TO "ALICE@EXAMPLE.COM";
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 admin@EXAMPLE.COM example.com
... * Successfully enrolled machine in realm
warning

Note that the realm name in admin@EXAMPLE.COM 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:

kinit admin@EXAMPLE.COM

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 alice@EXAMPLE.COM (aes256-cts-hmac-sha1-96)   2 bob@EXAMPLE.COM (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 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.

  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

On older Teleport versions:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  2. 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=example.teleport.com:443
    TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Otherwise, get the version of your Teleport cluster:

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

  3. Install Teleport on your Linux server:

    curl https://cdn.teleport.dev/install.sh | bash -s ${TELEPORT_VERSION} edition

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

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 TELEPORT@EXAMPLE.COM user that will fetch audit events from Oracle Audit Trail:

CREATE USER "TELEPORT@EXAMPLE.COM" IDENTIFIED EXTERNALLY;
GRANT CREATE SESSION TO "TELEPORT@EXAMPLE.COM";
GRANT SELECT ON SYS.DBA_AUDIT_TRAIL TO "TELEPORT@EXAMPLE.COM";
GRANT SELECT ON SYS.V_$SESSION TO "TELEPORT@EXAMPLE.COM";

Create the corresponding TELEPORT@EXAMPLE.COM 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 "ALICE@EXAMPLE.COM" 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​

The Teleport Database Service needs connectivity to your database endpoints. That may require enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Verify the connection using SQLcl or another database client.

sql -L test/test@oracle-instance.aabbccddeegg.eu-central-1.rds.amazonaws.com:2484

Teleport can reach RDS Oracle instance, but TLS negotiation fails (handshake failure)​

Ensure that SQLNET.SSL_VERSION parameter enables TLS 1.2 version. TLS 1.0 is rejected by Teleport due to known weaknesses. See AWS RDS Oracle SSL Setup documentation for more information.

Teleport also rejects the following weak cipher suites:

  • SSL_RSA_WITH_AES_256_CBC_SHA
  • SSL_RSA_WITH_AES_256_CBC_SHA256
  • SSL_RSA_WITH_AES_256_GCM_SHA384

Ensure that SQLNET.CIPHER_SUITE parameter contains at least one supported cipher suite. We recommend using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 cipher suite. Note that this parameter can contain multiple suites separated by a comma, so the compatible cipher suite can always be appended to the list.

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.: ALICE@EXAMPLE.COM)

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

Further reading​