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

The Teleport Database Service proxies traffic from database clients to self-hosted databases in your infrastructure. Teleport maintains a certificate authority (CA) for database clients. You configure your database to trust the Teleport database client CA, and the Teleport Database Service presents certificates signed by this CA when proxying user traffic. With this setup, there is no need to store long-lived credentials for self-hosted databases.

Meanwhile, the Teleport Database Service verifies self-hosted databases by checking their TLS certificates against either the Teleport database CA or a custom CA used with the database.

In this guide, you will:

1. Configure your Oracle database for Teleport access.
2. Add the database to your Teleport cluster.
3. Connect to the database via Teleport.

작동 방식#

The Teleport Database Service authenticates to your self-hosted Oracle database using mutual TLS. Oracle trusts the Teleport certificate authority for database clients, and presents a certificate signed by either the Teleport database CA or a custom CA. When a user initiates a database session, the Teleport Database Service presents a certificate signed by Teleport. The authenticated connection then proxies client traffic from the user.

사전 조건#

• A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• 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 with the web address of your Teleport Proxy Service:

     $ TELEPORT_DOMAIN=
     $ 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:

• Oracle 서버 인스턴스 18c 이상의 셀프 호스팅.
• sqlcl Oracle 클라이언트가 설치되어 시스템의 PATH 환경 변수에 추가되어 있거나, JDBC Oracle thin 클라이언트를 지원하는 GUI 클라이언트.
• 선택 사항: 셀프 호스팅 데이터베이스에 대한 인증서를 발급하는 인증 기관.

1/6단계. Teleport 토큰 및 사용자 생성#

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
(=presets.tokens.first=)

기본 제공 access 및 requester 역할로 로컬 Teleport 사용자를 생성합니다:

$ tctl users add \
  --roles=access,requester \
  --db-users=\* \
  --db-names=\* \
  alice

데이터베이스 접근 제어 및 접근 제한에 대한 자세한 정보는 RBAC 문서를 참조하세요.

2/6단계. 인증서/키 쌍 및 Teleport Oracle 지갑 생성#

Teleport uses mutual TLS authentication with self-hosted databases. These databases must be configured with Teleport's certificate authority to be able to verify client certificates. They also need a certificate/key pair that Teleport can verify.

To use issue certificates from your workstation with tctl, your Teleport user must be allowed to impersonate the system role Db.

Include the following allow rule in in your Teleport user's role:

allow:
  impersonate:
    users: ["Db"]
    roles: ["Db"]

데이터베이스에 대한 TLS 자격 증명을 생성하려면 아래 지침을 따르세요.

# Teleport의 인증 기관 및 호스트 db.example.com에 대해 3개월 유효 기간으로 생성된 인증서/키 쌍을 내보냅니다.
$ tctl auth sign --format=oracle --host=db.example.com --out=server --ttl=2190h

이 예시에서 db.example.com은 Teleport 데이터베이스 서비스가 Oracle 서버에 도달할 수 있는 호스트명입니다.

tctl이 로컬 환경에서 Orapki 도구를 찾으면, tctl auth sign --format=oracle --host=db.example.com --out=server --ttl=2190h 명령은 Oracle 지갑과 Teleport Oracle 지갑으로 Oracle TCPS 리스너를 구성하는 방법에 대한 지침을 생성합니다. 그렇지 않으면 tctl auth sign --format=oracle 명령은 p12 인증서와 Oracle 데이터베이스 인스턴스에서 Oracle 지갑을 생성하는 방법에 대한 지침을 생성합니다.

Oracle 데이터베이스가 기존 인증 기관에서 서명한 TLS 자격 증명을 제공하는 경우 다음 단계를 수행합니다:

1. Oracle이 Teleport 데이터베이스 서비스에서 오는 트래픽을 인증하기 위한 Teleport CA 인증서를 내보냅니다. 워크스테이션에서 다음 명령을 실행합니다:

   $ tctl auth export --type=db-client --auth-server=:443 > server.ca-client.crt
   

2. server.ca-client.crt를 Oracle 지갑에 사용할 Oracle 서버의 디렉터리로 이동합니다.

3. Oracle 서버에 대한 키와 인증서를 PKCS12 형식으로 발급하고 결과 P12 파일을 Oracle 지갑 디렉터리의 server.p12로 이동합니다.

4. Oracle 서버에서 orapki 도구를 사용하여 Oracle 지갑을 설정합니다:

   # 이 값을 패스워드로 할당합니다
   $ PKCS12_PASS=""
   $ WALLET_DIR="/path/to/oracleWalletDir"
   $ orapki wallet create -wallet "$WALLET_DIR" -auto_login_only
   $ orapki wallet import_pkcs12 -wallet "$WALLET_DIR" -auto_login_only -pkcs12file server.p12 -pkcs12pwd ${PKCS12_PASS?}
   $ orapki wallet add -wallet "$WALLET_DIR" -trusted_cert -auto_login_only -cert server.ca-client.crt
   

3/6단계. Oracle 데이터베이스 구성#

Teleport Oracle 통합을 활성화하려면 TCPS Oracle 리스너를 구성하고 이전 단계에서 생성한 Teleport Oracle 지갑을 사용해야 합니다.

listener.ora Oracle 구성 파일을 조정하고 다음 항목을 추가합니다:

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = 2484))
    )
  )

WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = /path/to/oracleWalletDir)))
SSL_CLIENT_AUTHENTICATION = TRUE

또한 sqlnet.ora Oracle 구성을 확장해야 합니다:

WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = /path/to/oracleWalletDir)))
SSL_CLIENT_AUTHENTICATION = TRUE
SQLNET.AUTHENTICATION_SERVICES = (TCPS)

또한 Oracle 데이터베이스 사용자 계정은 유효한 클라이언트 인증서를 요구하도록 구성되어야 합니다. 새 사용자를 생성하는 경우:

CREATE USER alice IDENTIFIED EXTERNALLY AS 'CN=alice';
GRANT CREATE SESSION TO alice;

4/6단계. 데이터베이스 서비스 구성 및 시작#

Teleport 데이터베이스 서비스를 실행할 위치에 Teleport를 설치하고 구성합니다:

$ sudo teleport db configure create \
   -o file \
   --token=/tmp/token \
   --proxy=:443 \
   --name=oracle \
   --protocol=oracle \
   --uri=oracle.example.com:2484 \
   --labels=env=dev 

$ sudo teleport db configure create \
   -o file \
   --token=/tmp/token \
   --proxy=:443 \
   --name=oracle \
   --protocol=oracle \
   --uri=oracle.example.com:2484 \
   --trust-system-cert-pool \
   --labels=env=dev

$ helm repo add teleport (=teleport.helm_repo_url=)

$ helm repo update

roles: db
proxyAddr:  name="example.teleport.sh" />
# Set to false if using Teleport Community Edition
enterprise: true
authToken: "JOIN_TOKEN" />"
databases:
  - name: oracle
    uri: oracle.example.com:2484
    protocol: oracle
    static_labels:
      env: dev

(!docs/pages/includes/database-access/multiple-instances-tip.mdx !)

5/6단계. (선택 사항) Oracle 감사 추적에서 감사 로그를 가져오도록 Teleport 구성#

Teleport는 Oracle 감사 추적에서 감사 로그를 가져올 수 있습니다. 이 기능을 활성화하려면 Oracle 감사 추적을 구성하고 Oracle 감사 추적에서 감사 이벤트를 가져오는 데 사용할 전용 Teleport 사용자를 생성해야 합니다.

Oracle 감사 추적에서 감사 이벤트를 가져올 내부 Oracle teleport 사용자를 생성합니다:

CREATE USER teleport IDENTIFIED EXTERNALLY AS 'CN=teleport';
GRANT CREATE SESSION TO teleport;
GRANT SELECT ON SYS.DBA_AUDIT_TRAIL TO teleport;
GRANT SELECT ON SYS.V_$SESSION TO teleport;

Oracle 감사 추적에서 테이블을 활성화합니다:

ALTER system SET audit_trail=db,extended scope=spfile;

감사 추적 변경 사항을 적용하려면 Oracle 인스턴스를 재시작합니다.

alice 사용자에 대한 Oracle 감사를 활성화합니다:

AUDIT ALL STATEMENTS by alice BY access;

Oracle에 연결하는 데 사용될 각 Teleport 사용자에 대해 감사를 활성화해야 합니다. 또한 각 사용자에 대해 다른 감사 정책을 생성할 수 있습니다.

Oracle 감사 추적에서 감사 로그를 가져오도록 이전에 생성한 데이터베이스 서비스 구성을 편집합니다:

db_service:
  enabled: true
  databases:
  - name: "oracle"
    protocol: "oracle"
    uri: "oracle.example.com:2484"
    oracle:
      audit_user: "teleport"

Teleport는 Oracle 감사 추적에서 감사 추적 이벤트를 정리하지 않습니다. 디스크 공간이 부족하지 않도록 Oracle 감사 추적 정리 정책을 구성해야 합니다.

6/6단계. 연결#

데이터베이스 서비스가 클러스터에 합류하면 로그인하여 사용 가능한 데이터베이스를 확인합니다:

$ tsh login --proxy= --user=alice
$ tsh db ls
# Name   Description    Allowed Users Labels  Connect
# ------ -------------- ------------- ------- -------
# oracle Oracle Example [*]                   env=dev

데이터베이스에 연결합니다:

$ tsh db connect --db-user=alice --db-name=XE oracle
#
#
# SQLcl: Release 22.4 Production on Fri Mar 31 20:48:02 2023
#
# Copyright (c) 1982, 2023, Oracle.  All rights reserved.
#
# Connected to:
# Oracle Database 21c Express Edition Release 21.0.0.0.0 - Production
# Version 21.3.0.0.0
#
# SQL>

데이터베이스에서 로그아웃하고 자격 증명을 제거하려면:

# 특정 데이터베이스 인스턴스의 자격 증명 제거.
$ tsh db logout oracle
# 모든 데이터베이스 인스턴스의 자격 증명 제거.
$ tsh db logout

(선택 사항) 추가 호스트명 구성#

In some deployments the same logical database is reachable via multiple hostnames with different characteristics, for example:

• replicated databases
• hostnames that traverse different network paths

If this applies to your setup, list all hosts in order of preference to improve connection resiliency.

If a TCP dial error occurs for a host, the next host in the list is tried automatically. Non-network errors (e.g., certificate or authentication failures) are not retried and do not advance to the next host.

By default, hosts are attempted in the listed order. Retries cycle through the list and wrap to the start as needed (e.g., host1 → host2 → host3 → host1 → ...). To randomize the sequence per connection attempt, set shuffle_hostnames; the same cyclic pattern then applies to that randomized order.

retry_count controls the number of retries per host after the initial attempt on a network error. The default is 2, so there are 3 total attempts per host (1 initial + 2 retries) before moving to the next host in sequence.

This setup supports failover and basic load-balancing for new connections: enabling shuffle_hostnames spreads initial connection attempts across hosts (load-balancing), while retries automatically move to the next host if the current one is unreachable (failover).

- name: oracle
  protocol: oracle
  uri: host1:2484,host2:2484,host3:2484  # Multiple hosts; dials in sequence and wraps (host1 → host2 → host3 → host1 ...). Dialing sequence can be randomized with `shuffle_hostnames`.
  static_labels:
    env: dev
  oracle:
    # Randomize host order per connection attempt to spread load. Optional.
    shuffle_hostnames: true
    # Retries per host on network errors only; non-network errors stop (default: 2). Optional.
    retry_count: 5            

문제 해결#

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/mypassword@oracle-instance.example.com: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

다음 단계#

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

• Oracle 문서에서 sqlnet.ora 및 listener.ora 구성에 대해 자세히 알아보세요: sqlnet.ora 파일 매개변수 및 listener.ora 파일의 Oracle Net 리스너 매개변수.
• Oracle 감사 추적