# Database Access with AWS RDS Oracle with Kerberos Authentication Teleport can provide secure access to Amazon RDS for Oracle via the [Teleport Database Service](https://goteleport.com/docs/ver/17.x/enroll-resources/database-access.md). This allows for fine-grained access control through [Teleport's RBAC](https://goteleport.com/docs/ver/17.x/enroll-resources/database-access/rbac.md). 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 want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/ver/17.x/get-started/deploy-community.md). - 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: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip 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\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/ver/17.x/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport 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](https://www.oracle.com/database/sqldeveloper/technologies/sqlcl/download/), 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.7.20 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](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-kerberos-setting-up.html) to enable Kerberos authentication on your instance. 2. Enable TLS on your Oracle RDS instance by following the [AWS RDS Oracle SSL Setup documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.Options.SSL.html). 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: **Ubuntu** ``` $ sudo apt-get update $ sudo apt-get -y install sssd realmd krb5-user samba-common packagekit adcli ``` **RHEL / CentOS 7** ``` $ sudo yum -y update $ sudo 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: ``` $ 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: **Ubuntu 18.04** ``` $ 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 ``` **Ubuntu 20.04** ``` $ curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc $ curl https://packages.microsoft.com/config/ubuntu/20.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 ``` **Ubuntu 22.04** ``` $ curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc $ curl https://packages.microsoft.com/config/ubuntu/22.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 ``` **RHEL 8** ``` $ sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/8/prod.repo $ sudo ACCEPT_EULA=Y yum install -y adutil ``` **RHEL 9** ``` $ sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/9/prod.repo $ sudo ACCEPT_EULA=Y yum install -y adutil ``` **Other** 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. ``` $ ktutil ktutil: addent -password -p alice@EXAMPLE.COM -k 1 -e aes256-cts-hmac-sha1-96 Password for alice@EXAMPLE.COM: [enter password here] ktutil: wkt teleport.keytab ktutil: quit ``` 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. ![AWS AD Set SPN](/docs/assets/images/aws_ad_set_spn-e86708678908975414a83bd4eabc2449.png) 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.keytab KVNO 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: | Edition | Value | | --------------------------------- | ------------ | | Teleport Enterprise Cloud | `cloud` | | Teleport Enterprise (Self-Hosted) | `enterprise` | | Teleport Community Edition | `oss` | 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=teleport.example.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=teleport.example.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](https://goteleport.com/docs/ver/17.x/installation/linux.md). --- 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: | 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** On the host where you will run the Teleport Database Service, enable and start Teleport: ``` $ sudo systemctl enable teleport $ sudo systemctl start teleport ``` **TAR Archive** 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.service $ 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](https://goteleport.com/docs/ver/17.x/enroll-resources/database-access/rbac.md) --- **Teleport Community Edition** Create a local Teleport user with the built-in `access` role: ``` $ tctl users add \ --roles=access \ --db-users="*" \ --db-names="*" \ alice ``` **Teleport Enterprise/Enterprise Cloud** 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. | --- 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](https://goteleport.com/docs/ver/17.x/enroll-resources/database-access/rbac.md) 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`](https://aws.amazon.com/blogs/database/part-1-security-auditing-in-amazon-rds-for-oracle/#:~:text=standard%20auditing%20with%20amazon%20rds%20for%20oracle). 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](https://www.oracle.com/database/sqldeveloper/technologies/sqlcl/download/) 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](https://goteleport.com/docs/ver/17.x/connect-your-client/gui-clients.md#oracle-graphical-clients) section. ## Next steps - Learn how to [restrict access](https://goteleport.com/docs/ver/17.x/enroll-resources/database-access/rbac.md) to certain users and databases. * View the [High Availability (HA)](https://goteleport.com/docs/ver/17.x/enroll-resources/database-access/guides/ha.md) guide. - Take a look at the YAML configuration [reference](https://goteleport.com/docs/ver/17.x/reference/agent-services/database-access-reference/configuration.md). * See the full CLI [reference](https://goteleport.com/docs/ver/17.x/reference/agent-services/database-access-reference/cli.md). ## 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](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.Options.SSL.html) 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 - [AWS RDS Oracle Kerberos Setup](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-kerberos-setting-up.html). - [AWS RDS Oracle SSL Setup](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.Options.SSL.html). - [AWS RDS Oracle auditing](https://aws.amazon.com/blogs/database/part-1-security-auditing-in-amazon-rds-for-oracle/). - [Manually join a Linux instance](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/join_linux_instance.html) in the AWS documentation. - [Introduction to `adutil`](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-ad-auth-adutil-introduction) in the Microsoft documentation.