$ sudo apt-get update
$ sudo apt-get -y install krb5-user krb5-pkinit

$ sudo yum -y update
$ sudo yum -y install krb5-workstation krb5-pkinit

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 to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

$ tsh login --proxy= --user=
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

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.

1/7단계. Teleport 사용자 생성#

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

2/7단계. Teleport 연결을 허용하는 GPO 구성#

Teleport 데이터베이스 세션을 허용하도록 GPO를 구성해야 합니다. 여기에는 컴퓨터가 Teleport의 CA를 신뢰하도록 설정하고 인증서 기반 스마트 카드 인증을 허용하는 것이 포함됩니다.

Teleport CA 및 CRL 내보내기#

1. 다음을 실행하여 Teleport 데이터베이스 CA 인증서를 가져옵니다:

   $ tctl auth export --type=db-client-der > db-ca.cer
   

2. 다음을 실행하여 Teleport 데이터베이스 CRL을 가져옵니다:

   $ tctl auth crl --type=db_client > db-ca.crl
   

   HSM을 사용하는 경우 내보내야 할 CRL이 여러 개 있습니다. 다음을 실행하여 수행할 수 있습니다:

   $ tctl auth crl --type=db_client --out=<file_prefix>
   

3. db-ca.cer 및 db-ca.crl 파일을 그룹 정책을 관리할 수 있는 Windows 머신으로 전송합니다.

GPO 생성 및 Teleport CA 가져오기#

1. Teleport DB Access라는 GPO를 생성합니다.

   $GPOName="Teleport DB Access"
   New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
   

2. Group Policy Management 프로그램을 열고 왼쪽 창에서 $FOREST > Domains > $DOMAIN > Group Policy Objects로 이동합니다.

3. 방금 만든 GPO(Teleport DB Access)를 마우스 오른쪽 버튼으로 클릭하고 Edit...를 선택합니다.

4. 그룹 정책 편집기에서 다음을 선택합니다:

   Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
   

5. Trusted Root Certification Authorities를 마우스 오른쪽 버튼으로 클릭하고 Import를 선택합니다.

6. 마법사를 통해 CA 파일(db-ca.cer)을 선택합니다.

스마트 카드 서비스 활성화#

Teleport는 스마트 카드를 에뮬레이션하여 인증서 기반 인증을 수행합니다.

1. Teleport DB Access를 편집하는 상태에서 다음을 선택합니다:

   Computer Configuration > Policies > Windows Settings > Security Settings > System Services
   

2. Smart Card를 더블 클릭하고 Define this policy setting을 선택한 다음 Automatic으로 전환하고 OK를 클릭합니다.

Teleport CA 게시#

이 단계는 도메인 컨트롤러가 Teleport CA를 신뢰하도록 활성화하여 Teleport를 통한 스마트 카드 로그인이 성공하도록 합니다.

도메인에 참여하고 Domain Administrators 그룹의 계정으로 로그인한 머신에서 PowerShell 프롬프트에서 다음 두 명령을 실행하여 Teleport CA를 Active Directory 도메인에 게시합니다 (위에서 복사한 내보낸 Teleport db-ca.cer 파일 경로 사용):

certutil –dspublish –f 


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

6/7단계. SQL Server AD 사용자 생성#
Note
SQL Server에 이미 Active Directory 로그인이 있는 경우 이 단계를 건너뛸 수 있습니다.

관리 계정(예: sa)으로 SQL Server에 연결하고 Active Directory 인증을 사용할 로그인을 생성합니다:
master> CREATE LOGIN [EXAMPLE\alice] FROM WINDOWS WITH DEFAULT_DATABASE = [master], DEFAULT_LANGUAGE = [us_english];

7/7단계. 연결#
Teleport 클러스터에 로그인합니다. SQL Server 데이터베이스가 사용 가능한 데이터베이스 목록에 표시되어야 합니다:
Self-HostedTeleport Enterprise Cloud

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



$ tsh login --proxy=mytenant.teleport.sh --user=alice
$ tsh db ls
# Name      Description         Labels
# --------- ------------------- -------
# sqlserver                     env=dev



데이터베이스에 대한 자격 증명을 검색하고 연결하려면:
$ tsh db connect --db-user=teleport sqlserver




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

문제 해결#
Teleport CA 및 CRL이 올바르게 가져오지 않음#
데이터베이스에 연결할 때 Error message: authentication failed 오류가 발생하고
Teleport Database Service 로그에 Failed to authenticate with KDC: kinit: Client not trusted while getting initial credentials 오류 메시지가 있습니다. 이는 Teleport Database CA가 올바르게 가져오지 않았거나
아직 전파되지 않은 경우 발생합니다. certutil -pulse를 실행하고 데이터베이스에 다시 연결을 시도하여
전파를 강제할 수 있습니다.
잘못된 KDC 호스트명#
데이터베이스에 연결 중 Error message: authentication failed 오류가 발생하고
Teleport Database Service 로그에 Failed to authenticate with KDC: Password for user@AD.TELEPORT.DEV: \nkinit: Cannot read password while getting initial credentials 오류가 있으면, KDC 호스트명이 잘못된 것입니다. 도메인 컨트롤러의 SPN이 올바르게 설정되어 있는지 확인하고 데이터베이스 구성의 kdc_hostname 필드 값을 업데이트합니다.
누락된 SID로 인한 PKINIT 인증 실패#
PKINIT 인증이 실패하고 Teleport Database Service 로그에 누락된 사용자 SID 또는 실패한 LDAP 쿼리 관련 오류가 표시되면,
ldap_service_account_name 및 ldap_service_account_sid 필드가 데이터베이스 구성에 올바르게 설정되어 있는지 확인합니다.
ldap_cert 필드의 잘못된 인증서로 인한 오류가 없는지 확인합니다.
서비스 계정이 존재하고 올바른 이름과 SID를 가지며 지정된 속성에 접근 권한이 있는지 확인합니다.
Teleport가 데이터베이스 CA를 검증할 수 없음#
데이터베이스에 Teleport가 모르는 CA가 있는 경우, 연결 시 다음 오류를 반환합니다:
Error message: TLS Handshake failed: x509: certificate signed by unknown authority (possibly because of "x509: invalid signature: parent certificate cannot sign this kind of certificate" while trying to verify candidate authority certificate "SSL_Self_Signed_Fallback").
이를 해결하려면 Teleport Database Service 인스턴스에 다음 구성을 추가합니다:
...
db_service:
  databases:
    - name: sqlserver
      protocol: sqlserver
+     tls:
+       # 데이터베이스 CA PEM 인증서를 가리킵니다.
+       ca_cert_file: "rdsca.pem"
+       # 데이터베이스 인증서의 CN 필드가 비어 있는 경우
+       # CA만 검증하도록 TLS 모드를 변경해야 합니다.
+       mode: verify-ca
      ad:
       ...

데이터베이스 CA를 얻을 수 없는 경우 구성 tls.mode: "insecure"를 제공하여 TLS 검증을 건너뛸 수 있습니다. 그러나 프로덕션 환경에서는 TLS 검증을 건너뛰는 것을 권장하지 않습니다.
다음 단계#



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.



추가 참고자료#

Kerberos PKINIT 인증.
PKINIT 인증을 사용한 Microsoft SQL Server 접근
원문 보기
번역일: 2026-05-14
요약
Teleport can provide secure access to Microsoft SQL Server via the Teleport Database Service. In this guide, you will: Teleport Database Service는 SQL Server 데이터베이스와 동일한 Active Directory 도메인에 참여하고 Kerberos 프로토콜을 사용하여 SQL Server로 인증합니다.

Teleport can provide secure access to Microsoft SQL Server via the  Teleport Database
Service. This allows for
fine-grained access control through Teleport's RBAC.
In this guide, you will:

Configure your Microsoft SQL Server database with PKINIT authentication.
Add the database to your Teleport cluster.
Connect to the database via Teleport.


동작 원리#
Teleport Database Service는 SQL Server 데이터베이스와 동일한 Active Directory 도메인에 참여하고
Kerberos 프로토콜을 사용하여 SQL Server로 인증합니다.
Teleport 인증 기관을 신뢰하도록 Active Directory 도메인이 구성됩니다. 사용자가 Teleport를 통해
SQL Server에 연결하면 Database Service는 PKINIT을
사용하여 Active Directory에서 티켓 부여 티켓을 얻습니다. 인증 후 Teleport Database Service는
사용자 트래픽을 데이터베이스로 전달합니다.
Self-HostedTeleport Enterprise Cloud







이 가이드는 셀프 호스팅 Active Directory 인증을 사용하는 SQL Server에 초점을 맞춥니다.
사전 요구사항#



A running Teleport 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


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')"



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

  
  









Active Directory 인증이 활성화된 SQL Server 데이터베이스.


Subject Alternative Names를 사용하는 인증서로 구성된 SQL Server 네트워크 리스너.


데이터베이스와 동일한 Active Directory 도메인에 참여한 Windows 머신.


Active Directory 설치에 네트워크 접근이 가능하고 PKINIT 확장이 설치된 kinit 명령이 있는 Linux 노드:
UbuntuRHEL / CentOS 7



$ sudo apt-get update
$ sudo apt-get -y install krb5-user krb5-pkinit



$ sudo yum -y update
$ sudo yum -y install krb5-workstation krb5-pkinit




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
 to the domain name of the Teleport Proxy Service
in your cluster and  to your Teleport username:
$ tsh login --proxy= --user=
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

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.

1/7단계. Teleport 사용자 생성#








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.




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

2/7단계. Teleport 연결을 허용하는 GPO 구성#
Teleport 데이터베이스 세션을 허용하도록 GPO를 구성해야 합니다. 여기에는
컴퓨터가 Teleport의 CA를 신뢰하도록 설정하고 인증서 기반 스마트 카드 인증을 허용하는 것이 포함됩니다.
Teleport CA 및 CRL 내보내기#
Database CA 순환
Teleport의 데이터베이스 인증 기관을 순환하는 경우 이 단계를 반복해야 합니다.



다음을 실행하여 Teleport 데이터베이스 CA 인증서를 가져옵니다:
$ tctl auth export --type=db-client-der > db-ca.cer



다음을 실행하여 Teleport 데이터베이스 CRL을 가져옵니다:
$ tctl auth crl --type=db_client > db-ca.crl

HSM을 사용하는 경우 내보내야 할 CRL이 여러 개 있습니다.
다음을 실행하여 수행할 수 있습니다:
$ tctl auth crl --type=db_client --out=<file_prefix>



db-ca.cer 및 db-ca.crl 파일을 그룹 정책을 관리할 수 있는 Windows 머신으로 전송합니다.


GPO 생성 및 Teleport CA 가져오기#
도메인 전체 정책
이 가이드에서는 방금 만든 GPO를 전체 AD 도메인에 적용합니다. AD 도메인 내의 특정 컴퓨터 하위 집합만
Teleport를 통해 접근하게 하려면 해당 컴퓨터만 포함하는 OU에 GPO를 적용해야 합니다.



Teleport DB Access라는 GPO를 생성합니다.
$GPOName="Teleport DB Access"
New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)



Group Policy Management 프로그램을 열고 왼쪽 창에서
$FOREST > Domains > $DOMAIN > Group Policy Objects로 이동합니다.


방금 만든 GPO(Teleport DB Access)를 마우스 오른쪽 버튼으로 클릭하고 Edit...를 선택합니다.


그룹 정책 편집기에서 다음을 선택합니다:
Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies



Trusted Root Certification Authorities를 마우스 오른쪽 버튼으로 클릭하고 Import를 선택합니다.


마법사를 통해 CA 파일(db-ca.cer)을 선택합니다.



스마트 카드 서비스 활성화#
Teleport는 스마트 카드를 에뮬레이션하여 인증서 기반 인증을 수행합니다.


Teleport DB Access를 편집하는 상태에서 다음을 선택합니다:
Computer Configuration > Policies > Windows Settings > Security Settings > System Services



Smart Card를 더블 클릭하고 Define this policy setting을 선택한 다음
Automatic으로 전환하고 OK를 클릭합니다.



gpupdate.exe
GPO를 수정하고 있으며, GPO 수정이 모든 호스트에 전파되는 데 시간이 걸릴 수 있습니다. PowerShell 프롬프트를 열고
gpupdate.exe /force를 실행하여 현재 호스트에서 변경 사항을 즉시 적용할 수 있습니다(다만 변경 사항이 도메인의 다른 머신에 전파되는 데는 여전히 시간이 걸릴 수 있습니다).

Teleport CA 게시#
이 단계는 도메인 컨트롤러가 Teleport CA를 신뢰하도록 활성화하여 Teleport를 통한 스마트 카드 로그인이 성공하도록 합니다.
도메인에 참여하고 Domain Administrators 그룹의 계정으로 로그인한 머신에서
PowerShell 프롬프트에서 다음 두 명령을 실행하여 Teleport CA를 Active Directory 도메인에 게시합니다
(위에서 복사한 내보낸 Teleport db-ca.cer 파일 경로 사용):
certutil –dspublish –f 


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

6/7단계. SQL Server AD 사용자 생성#
Note
SQL Server에 이미 Active Directory 로그인이 있는 경우 이 단계를 건너뛸 수 있습니다.

관리 계정(예: sa)으로 SQL Server에 연결하고 Active Directory 인증을 사용할 로그인을 생성합니다:
master> CREATE LOGIN [EXAMPLE\alice] FROM WINDOWS WITH DEFAULT_DATABASE = [master], DEFAULT_LANGUAGE = [us_english];

7/7단계. 연결#
Teleport 클러스터에 로그인합니다. SQL Server 데이터베이스가 사용 가능한 데이터베이스 목록에 표시되어야 합니다:
Self-HostedTeleport Enterprise Cloud

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



$ tsh login --proxy=mytenant.teleport.sh --user=alice
$ tsh db ls
# Name      Description         Labels
# --------- ------------------- -------
# sqlserver                     env=dev



데이터베이스에 대한 자격 증명을 검색하고 연결하려면:
$ tsh db connect --db-user=teleport sqlserver




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

문제 해결#
Teleport CA 및 CRL이 올바르게 가져오지 않음#
데이터베이스에 연결할 때 Error message: authentication failed 오류가 발생하고
Teleport Database Service 로그에 Failed to authenticate with KDC: kinit: Client not trusted while getting initial credentials 오류 메시지가 있습니다. 이는 Teleport Database CA가 올바르게 가져오지 않았거나
아직 전파되지 않은 경우 발생합니다. certutil -pulse를 실행하고 데이터베이스에 다시 연결을 시도하여
전파를 강제할 수 있습니다.
잘못된 KDC 호스트명#
데이터베이스에 연결 중 Error message: authentication failed 오류가 발생하고
Teleport Database Service 로그에 Failed to authenticate with KDC: Password for user@AD.TELEPORT.DEV: \nkinit: Cannot read password while getting initial credentials 오류가 있으면, KDC 호스트명이 잘못된 것입니다. 도메인 컨트롤러의 SPN이 올바르게 설정되어 있는지 확인하고 데이터베이스 구성의 kdc_hostname 필드 값을 업데이트합니다.
누락된 SID로 인한 PKINIT 인증 실패#
PKINIT 인증이 실패하고 Teleport Database Service 로그에 누락된 사용자 SID 또는 실패한 LDAP 쿼리 관련 오류가 표시되면,
ldap_service_account_name 및 ldap_service_account_sid 필드가 데이터베이스 구성에 올바르게 설정되어 있는지 확인합니다.
ldap_cert 필드의 잘못된 인증서로 인한 오류가 없는지 확인합니다.
서비스 계정이 존재하고 올바른 이름과 SID를 가지며 지정된 속성에 접근 권한이 있는지 확인합니다.
Teleport가 데이터베이스 CA를 검증할 수 없음#
데이터베이스에 Teleport가 모르는 CA가 있는 경우, 연결 시 다음 오류를 반환합니다:
Error message: TLS Handshake failed: x509: certificate signed by unknown authority (possibly because of "x509: invalid signature: parent certificate cannot sign this kind of certificate" while trying to verify candidate authority certificate "SSL_Self_Signed_Fallback").
이를 해결하려면 Teleport Database Service 인스턴스에 다음 구성을 추가합니다:
...
db_service:
  databases:
    - name: sqlserver
      protocol: sqlserver
+     tls:
+       # 데이터베이스 CA PEM 인증서를 가리킵니다.
+       ca_cert_file: "rdsca.pem"
+       # 데이터베이스 인증서의 CN 필드가 비어 있는 경우
+       # CA만 검증하도록 TLS 모드를 변경해야 합니다.
+       mode: verify-ca
      ad:
       ...

데이터베이스 CA를 얻을 수 없는 경우 구성 tls.mode: "insecure"를 제공하여 TLS 검증을 건너뛸 수 있습니다. 그러나 프로덕션 환경에서는 TLS 검증을 건너뛰는 것을 권장하지 않습니다.
다음 단계#



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.



추가 참고자료#

Kerberos PKINIT 인증.