InfoGrab Docs

인증 기관 교체

요약

Teleport 클러스터의 구성 요소들은 X.509 또는 SSH 인증서를 사용하여 서로 인증합니다. 단계를 따르기 전에 전체 가이드를 숙지하는 것을 권장합니다. Teleport는 CA를 독립적으로 유지하며, 하나의 CA를 교체해도 다른 CA의 교체 상태에 영향을 주지 않습니다.

Teleport 클러스터의 구성 요소들은 X.509 또는 SSH 인증서를 사용하여 서로 인증합니다. 인증서를 발급하기 위해 Teleport는 여러 인증 기관을 유지합니다. Teleport CA를 교체하면 악의적인 행위자가 Teleport 클러스터의 일부를 가장하는 것을 방지할 수 있습니다. 이 가이드는 Teleport가 유지하는 CA와 교체 방법을 설명합니다.

단계를 따르기 전에 전체 가이드를 숙지하는 것을 권장합니다. 예상대로 진행되지 않을 경우 CA 교체를 롤백할 준비가 되어 있어야 합니다.

작동 방식#

Teleport는 CA를 독립적으로 유지하며, 하나의 CA를 교체해도 다른 CA의 교체 상태에 영향을 주지 않습니다. 교체 프로세스는 운영자가 인프라를 업데이트하고 필요한 경우 CA 교체를 롤백할 시간을 주는 단계로 진행됩니다.

Teleport CA 교체는 각 CA에 대해 5단계로 이루어집니다. 단계의 순서는 다음과 같습니다:

  1. standby: 교체 진행 중 없음. 아무 작업도 시작되지 않음.
  2. init: 새 인증 기관이 발급되었지만 사용되지 않음.
  3. update_clients: Teleport Auth Service는 새 CA를 사용하여 새 인증서에 서명하지만 원래 CA가 서명한 인증서도 계속 신뢰함.
  4. update_servers: 클라이언트로부터 들어오는 연결을 수락하는 클러스터의 모든 서버 구성 요소가 아이덴티티를 다시 로드하고 새 CA가 발급한 인증서를 제공하기 시작함. 이 단계에서 클라이언트는 원래 CA 또는 새 CA가 발급한 서버 인증서를 수락합니다. host CA를 교체할 때 Teleport 에이전트, Auth Service 및 Proxy Service 인스턴스는 자동으로 아이덴티티를 다시 로드합니다. 이 단계에서 OpenSSH 호스트에 새 SSH 호스트 인증서를 발급해야 합니다.
  5. standby: 교체 진행 중 없음. 모든 작업이 완료됨. 모든 구성 요소가 이전 CA 신뢰를 중단하고 새 CA만 신뢰합니다.

최종 standby 단계 이전에 rollback 단계로 교체를 중단하고 원래 인증 기관으로 돌아갈 수도 있습니다. rollback 단계 후에는 standby 단계로 진행합니다.

CA 교체는 수동 또는 반자동으로 진행할 수 있습니다. 수동 모드에서는 관리자가 Teleport Auth Service에 한 단계에서 다음 단계로 진행하도록 지시해야 합니다. 단계 사이에 관리자는 각 변경 사항에 맞게 인프라를 준비할 수 있습니다. 반자동 모드에서는 Teleport Auth Service가 각 단계 사이에 유예 기간을 두고 자동으로 각 단계를 순환합니다.

17.0.5 이상 버전에서는 tctl auth rotate(인수 없이)를 실행하면 CA 교체를 위한 대화형 터미널 UI가 시작됩니다. 대화형 UI는 실시간 클러스터 상태를 표시하고, 교체할 CA를 선택하고, 각 단계를 안내하며, 클러스터가 다음 단계로 준비되었는지 자동으로 확인하고, 완료해야 하는 수동 단계를 나열합니다.

사전 요구 사항#

  • 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

    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:

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.

  • 사용자는 certificate_authority 리소스에 대해 create 및 update 권한이 있는 역할이 필요합니다.

    kind: role
version: v8
metadata:
  name: rotate-cas
spec:
  allow:
    rules:
    - resources: [ certificate_authority ]
      verbs: [ create, update ]

1/4단계. 교체할 CA 선택#

CA를 교체할 때 각 단계에서 해당 CA에 의존하는 인프라가 연결성을 잃지 않았는지 확인해야 합니다. 또한 새 CA를 인프라로 내보내거나 자체 호스팅 서비스에 새 인증서를 발급해야 할 수 있습니다. 마이그레이션 중 최신 상태를 유지하는 방법을 결정하려면 아래 CA 중 하나를 선택하세요.

CA 유형 인증서 주체
host Teleport 에이전트. Auth Service 및 Proxy Service 인스턴스.
user Teleport 사용자.
db Teleport로 보호되는 자체 호스팅 데이터베이스(사용자는 데이터베이스에 인증서를 배포해야 함).
db_client Teleport Database Service.
openssh Teleport 클러스터에 등록된 OpenSSH 서버.
jwt 웹 애플리케이션에 접근하는 Teleport 사용자.
saml_idp Teleport SAML IdP.
oidc_idp Teleport OIDC IdP 연동.
windows Windows 데스크톱에 연결하는 Teleport 사용자.
awsra Teleport AWS IAM Roles Anywhere 연동.
spiffe 워크로드 아이덴티티(SPIFFE) 클라이언트.
bound_keypair Bound Keypair JWT 검증.

host#

host CA는 Teleport 클라이언트와 Teleport Auth Service가 검증할 수 있도록 Teleport 에이전트 및 Auth Service와 Proxy Service 인스턴스에 인증서를 발급합니다. host CA는 등록된 에이전트 없는 OpenSSH 서버에 SSH 호스트 인증서도 발급합니다.

Teleport 에이전트와 Proxy Service 인스턴스는 하트비트를 사용하여 주기적으로 Teleport Auth Service에 상태를 보고하고 Auth Service가 보유한 데이터를 반영하여 내부 데이터를 업데이트합니다. 이 내부 데이터에는 진행 중인 경우 host CA 교체 상태가 포함됩니다.

에이전트 또는 Proxy Service 인스턴스의 교체 상태를 확인하려면 다음 명령의 변형을 실행하고, 에 에이전트 또는 Proxy Service 인스턴스의 이름을 할당하세요:

$ tctl get  --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}'
{
  "hostname": "terminal",
  "rotation": "in_progress",
  "phase": "init"
}

이 예에서 terminal이라는 Teleport 인스턴스는 상태를 init 단계로 업데이트했습니다. 이는 새 CA 공개 키를 다운로드하고 상태 전환 준비가 되었음을 의미합니다.

다음 리소스로 tctl get 명령을 사용하여 각 에이전트 종류에서 host CA의 교체 상태를 확인할 수 있습니다:

역할 tctl get 값
Application Service app_server
Auth Service auth_server
Database Service db_server
Kubernetes Service kube_server
Proxy Service proxies
SSH Service nodes
Windows Desktop Service windows_desktop_service

host CA 교체의 각 단계에서 다음 단계로 진행하기 전에 모든 에이전트와 Proxy Service 인스턴스가 대상 단계로 전환을 완료했는지 확인하세요. 단계는 2단계에서 설명합니다.

모든 OpenSSH 호스트는 host CA 교체의 update_servers 단계 동안 새 호스트 인증서를 발급받아야 합니다.

Auth Service에 직접 연결하는 Teleport 프로세스는 Auth Service가 제시하는 TLS 인증서를 신뢰하기 위해 CA 핀이 필요합니다. 여기에는 모든 Proxy Service 인스턴스와 Auth Service에 직접 연결하는 자체 호스팅 클러스터의 모든 에이전트가 포함됩니다. CA 교체 중에 tctl status는 CA 핀이 2개 있다고 보고합니다. CA 교체 중에 새 Teleport 에이전트를 클러스터에 추가하는 경우, 보고된 두 CA 핀 모두를 신뢰하도록 구성해야 합니다. 교체가 완료된 후에는 새 CA 핀만 보고됩니다.

참고: Proxy Service에 연결하는 Teleport 에이전트는 Proxy의 TLS 인증서가 신뢰할 수 있는 CA에 의해 발급되어야 하므로 CA 핀이 필요하지 않습니다.

windows#

windows CA는 Windows 데스크톱에 연결하는 사용자를 위한 인증서를 발급합니다. Teleport로 보호되는 Windows 데스크톱은 이 인증서를 사용합니다. v18.7.0 이전 Teleport 버전에서는 user CA가 windows CA의 기능을 수행했습니다.

windows CA를 교체할 때, init 단계에서 Windows 호스트가 새 CA 인증서를 신뢰하도록 구성해야 합니다. Windows Desktop Service가 RDP 호스트에 인증할 수 있도록 Teleport windows CA를 내보내려면 가이드를 따르세요.

update_clients로 진행한 후 교체 전반에 걸쳐 등록된 데스크톱에 연결할 수 있는지 확인하세요.

user#

user CA는 사용자가 Teleport에 인증할 때 인증서를 발급합니다. 또한 Teleport SSH 서버에 연결하는 사용자를 위한 클라이언트 인증서에 서명합니다. Teleport로 보호되는 서버는 이 인증서를 사용합니다.

교체를 완료하고 최종 standby 단계에 도달하기 전에, Teleport에 로그인한 사용자는 새 CA에서 사용자 인증서를 받기 위해 재인증해야 합니다. 그렇지 않으면 웹 세션과 Teleport 클라이언트 명령이 실패하고 사용자가 로그아웃 후 다시 로그인해야 할 수 있습니다. 이를 방지하려면 update_clients와 standby 단계 사이에 최대 사용자 세션 TTL보다 더 오래 기다릴 수 있습니다. 이렇게 하면 이전 CA가 서명한 모든 사용자 인증서가 이미 만료되어 재로그인이 필요하게 됩니다.

db와 db_client#

db와 db_client CA는 Teleport Database Service가 자체 호스팅 데이터베이스와 통신하는 데 사용하는 인증서를 발급합니다.

Teleport Database Service는 자체 호스팅 데이터베이스와 통신할 때 db_client CA가 서명한 인증서를 제시하며, 관리자는 이 CA가 발급한 인증서를 신뢰하도록 데이터베이스를 구성합니다.

관리자는 자체 호스팅 데이터베이스가 db CA가 서명한 인증서를 제시하도록 구성할 수 있으며, Database Service는 이를 사용하여 데이터베이스 서버가 진짜 Teleport로 보호된 리소스인지 확인합니다. 또는 자체 호스팅 데이터베이스는 사용자 지정 CA가 서명한 인증서를 제시할 수 있으며, 관리자는 Teleport Database Service가 해당 CA를 신뢰하도록 구성할 수 있습니다.

데이터베이스 CA 교체#

이 단계에서는 db와 db_client CA를 함께 교체하는 지침을 제공하지만, 하나만 교체하고 동일한 단계를 따르는 것도 가능합니다.

먼저 db와 db_client CA 모두를 init 단계로 교체하기 시작합니다. init 단계에서 tctl auth sign은 새 db CA 키로 서명된 데이터베이스 서버 인증서를 발급하고, 이전 db_client CA 인증서와 새 db_client CA 인증서를 모두 포함하는 CA 파일을 출력합니다. init 단계에서 자체 호스팅 데이터베이스를 새 인증서와 신뢰할 수 있는 CA로 재구성하여 어느 시점에서도 데이터베이스에 대한 접근을 잃지 않도록 해야 합니다.

Note

tctl auth sign --format db는 init 교체 단계의 일반적인 동작에 대한 예외입니다. db CA가 init 단계에 있을 때, tctl auth sign --format db는 새 CA 키로 서명된 데이터베이스 서버 인증서를 발급합니다. 이는 CA 교체 중에 자체 호스팅 데이터베이스를 두 번만 재구성하면 되도록 하기 위한 것입니다: 첫 번째는 init 단계에서 새 db CA가 서명한 인증서를 받고 새 db_client CA를 신뢰하기 시작할 때, 두 번째는 최종 standby 단계에서 이전 db_client CA 신뢰를 중단할 때입니다.

update_clients 교체 단계로 진행하기 전에 데이터베이스 구성에 대한 적절한 문서를 참조하세요.

update_clients 단계로 진행하자마자, Teleport Database Service는 새 db_client CA가 발급한 클라이언트 인증서를 사용하여 데이터베이스에 연결하기 시작합니다. 두 CA를 모두 update_clients 단계로 전환하기 전후에 데이터베이스에 계속 접근할 수 있는지 확인하세요.

모두 정상이면 두 CA를 update_servers 및 standby 단계로 계속 교체합니다. standby 단계에 도달한 후, 이제 교체된 이전 CA 인증서 신뢰를 중단하도록 데이터베이스를 다시 구성할 수 있습니다.

교체 롤백#

롤백하고 싶은 가장 일반적인 이유는 데이터베이스를 재구성할 수 없는 경우입니다. 데이터베이스를 재구성한 후 연결 문제가 발생하면 데이터베이스를 잘못 구성한 것일 가능성이 큽니다.

교체 중에 데이터베이스를 재구성한 경우, standby 단계로 진행하기 전에 rollback 단계에서 다시 재구성해야 합니다.

openssh#

openssh CA는 Proxy Service가 Teleport에 등록된 OpenSSH 서버에 인증하는 데 사용하는 임시 SSH 사용자 인증서를 발급합니다. OpenSSH 에이전트는 Proxy Service로부터 들어오는 연결을 받을 때 이 인증서를 검증합니다.

openssh CA 교체의 init 단계에서 모든 OpenSSH 서버는 기존 공개 키 외에 새 CA 공개 키를 신뢰하도록 업데이트되어야 합니다. 이는 update_clients 단계에서 Proxy Service가 새 CA 키로 서명된 인증서를 사용하기 시작할 때 연결성 손실을 방지하기 위해 필요합니다.

OpenSSH 서버를 등록하기 위해 수동 방법을 사용한 경우, 교체를 update_clients 단계로 전환하기 전에 새 openssh CA 공개 키를 내보내고 OpenSSH 서버에 제공하는 지침을 따라야 합니다.

자동화된 방법을 사용한 경우, update_clients 단계로 진행하기 전에 동일한 단계를 따라 sshd를 재구성해야 합니다.

Note

OpenSSH 서버는 host CA가 발급한 SSH 호스트 인증서를 사용하고 openssh CA가 발급한 들어오는 인증서를 신뢰합니다. host CA를 교체할 때 update_servers 단계에서 새 호스트 인증서로 OpenSSH 서버를 재구성해야 합니다.

jwt#

Teleport Auth Service는 jwt CA를 사용하여 JSON 웹 토큰에 서명합니다. Teleport Application Service는 Teleport로 보호된 애플리케이션에 전달하는 HTTP 메시지에 JSON 웹 토큰을 포함시키며, 애플리케이션은 jwt CA를 사용하여 토큰을 검증합니다.

Teleport에 웹 애플리케이션을 등록했고, 해당 애플리케이션이 Teleport 인증 기관에 대해 JSON 웹 토큰을 검증하여 Teleport Application Service에서 오는 트래픽을 인증하는 경우, 이 애플리케이션이 교체된 CA를 계속 신뢰하도록 해야 합니다.

Teleport로 보호되는 JWT 애플리케이션은 Teleport jwt CA의 공개 키를 검색하는 두 가지 방법 중 하나를 사용합니다. 방법에 따라 init 단계 이후 최종 standby 단계에 도달하기 전에 조치가 필요할 수 있습니다:

  • 애플리케이션이 Teleport Proxy Service의 /.well-known/jwks.json 엔드포인트를 쿼리합니다. 이 경우 애플리케이션이 엔드포인트에 계속 접근할 수 있는 한 조치가 필요하지 않습니다. 애플리케이션이 jwks.json을 캐시하는 경우 캐시를 무효화하세요.
  • 애플리케이션이 로컬 파일시스템의 jwks.json 파일에 접근합니다. /.well-known/jwks.json 엔드포인트를 쿼리하여 새 jwks.json 파일을 얻고 파일을 다시 업로드하세요.

웹 애플리케이션이 Teleport 발급 JWT를 신뢰할 수 있도록 jwt CA를 내보내는 예제는 Elasticsearch에서 JWT 인증 사용 가이드를 참조하세요.

saml_idp#

saml_idp CA는 Teleport IdP가 보내는 SAML 메시지에 서명하여 Teleport IdP에 의존하는 서비스가 검증할 수 있게 합니다.

이 CA를 교체하는 경우, update_clients 단계에 진입하기 전에 Teleport SAML IdP에 의존하는 서비스 제공자가 Teleport saml_idp CA를 신뢰하도록 구성해야 합니다. XML 메타데이터 파일을 내보내고 서비스 제공자에게 제공하려면 SAML IdP 문서의 지침을 따르세요.

oidc_idp#

oidc_idp CA는 Teleport OIDC IdP 연동이 보내는 메시지에 서명합니다. 신뢰 당사자(예: AWS)는 이 메시지를 검증하여 외부 감사 스토리지, 자동 검색, 액세스 그래프를 위한 AWS 동기화와 같은 기능을 위해 Teleport 계정을 인증합니다.

Teleport Proxy Service는 웹 API의 /.well-known/jwks-oidc 경로에서 OIDC IdP 연동을 위한 JSON Web Key Sets를 제공합니다.

Teleport Proxy Service 웹 API의 /.well-known/jwks-oidc 경로는 항상 활성화되어 있습니다. Teleport Proxy Service는 엔드포인트를 자동으로 업데이트합니다.

웹 UI의 /.well-known/openid-configuration 경로를 쿼리하고 jwks_uri 필드를 읽어 연동의 JSON Web Key Sets 전체 URL을 검색할 수 있습니다:

$ curl https://example.teleport.sh/.well-known/openid-configuration | jq '.jwks_uri'
"https://example.teleport.sh/.well-known-jwks-oidc"

spiffe#

spiffe CA는 워크로드 아이덴티티 클라이언트를 위한 X509 및 JWT SVID에 서명합니다. 이는 종종 다른 클라이언트가 mTLS로 서로 아이덴티티를 검증할 수 있게 합니다.

이 CA를 교체할 때, 최종 standby 단계에 진입하기 전에 Teleport 발급 SVID를 검증하는 모든 클라이언트가 새 CA를 신뢰하도록 업데이트되었는지 확인하세요:

  • Teleport 워크로드 아이덴티티 클라이언트는 tbot 클라이언트를 통해 업데이트된 CA 인증서를 자동으로 받아야 하며, 향후 SVID는 새 CA를 사용하여 발급됩니다.

    tbot의 workload-identity-api 서비스를 사용하는 경우, 클라이언트 애플리케이션이 새 SVID를 가져오기 위한 추가 단계가 필요할 수 있습니다. spiffe-svid 출력 중 하나로 자격 증명을 생성하는 경우, 새 SVID는 자동으로 발급되어야 합니다.

  • SPIFFE 페더레이션을 사용하는 경우, 다른 SPIFFE 신뢰 도메인은 주기적으로 Teleport의 인증서 번들을 갱신해야 합니다. 이 간격은 일반적으로 5분이지만, 번들 자체를 검사하여 확인할 수 있습니다:

    $ curl https://example.teleport.sh/webapi/spiffe/bundle.json | jq '.spiffe_refresh_hint'

awsra#

awsra CA는 AWS 임시 세션으로 교환하기 위해 AWS에 전송되는 X.509 인증서에 서명합니다. AWS는 신뢰 앵커로 추가하여 awsra CA를 신뢰하도록 구성되어야 합니다. 이 연동을 통해 AWS CLI 및 콘솔 접근이 가능합니다.

교체를 시작한 후 동일한 AWS IAM Roles Anywhere 신뢰 앵커에 새 CA를 추가해야 합니다.

이 기간 동안 AWS는 이전 CA와 새 CA 모두를 신뢰합니다. 모든 새 세션은 새 CA를 사용합니다.

교체가 완료된 후 AWS IAM Roles Anywhere 신뢰 앵커에서 이전 CA를 제거해야 합니다.

bound_keypair#

bound_keypair CA는 Bound Keypair 조인 상태 검증을 위해 발급된 JWT에 서명합니다. 이는 bound_keypair 조인 방법을 사용하여 Teleport 클러스터에 조인하는 클라이언트가 저장하는 추가 문서로, 각 조인 시도를 고유하게 식별하며 이후 조인 시 Teleport에 의해 추가로 검증됩니다.

교체 중에 클라이언트는 조인 상태 JWT에 서명하는 데 사용된 CA가 활성 상태이거나 신뢰받는 한 예상대로 계속 조인할 수 있으며, 이는 update_servers 단계까지 유효합니다.

Machine & Workload ID 봇은 활성 상태인 경우 교체 이벤트를 감지하고 인증서를 갱신해야 하며, 이를 통해 새 CA로 서명된 새 조인 상태 JWT를 자동으로 가져옵니다. 현재 실행 중이지 않은 봇은 한 번 시작되어 새 인증서를 가져올 수 있어야 하며, 이를 통해 조인 상태 JWT도 갱신됩니다.

CA 교체 후 조인 상태 검증이 실패하면 조인 상태 검증을 임시로 비활성화하여 클라이언트가 다시 조인할 수 있게 허용할 수 있습니다. 다음 조인 시 새 조인 상태 JWT가 발급되며, 그 후 조인 상태 검증을 안전하게 다시 활성화할 수 있습니다.

2/4단계. 수동 교체 시작#

교체할 CA를 선택하고 해당 CA에 의존하는 인프라를 확인하거나 업데이트할 계획을 세웠다면, 수동 교체를 시작할 준비가 된 것입니다.

Tip

17.0.5 이상 버전에서는 tctl auth rotate(인수 없이)를 실행하면 CA 교체를 위한 대화형 터미널 UI가 시작됩니다. 대화형 UI는 실시간 클러스터 상태를 표시하고, 교체할 CA를 선택하고, 각 단계를 안내하며, 클러스터가 다음 단계로 준비되었는지 자동으로 확인하고, 완료해야 하는 수동 단계를 나열합니다. 가능하면 대화형 교체를 사용하는 것을 권장하지만, 각 교체 단계를 수동으로 시작하는 방법을 알아보려면 계속 읽으세요.

init 단계#

init 단계에서 Teleport Auth Service는 선택된 유형의 새 인증 기관을 발급하지만, 인증서 서명에 사용하지 않습니다.

  1. 호스트 인증 기관의 수동 교체를 시작합니다:

    $ tctl auth rotate --manual --type= --phase=init
Updated rotation phase to "init". To check status use 'tctl status'

  2. tctl을 사용하여 교체가 진행 중인지 확인합니다. 이 명령은 클러스터에서 Teleport Auth Service가 유지하는 모든 CA의 교체 상태를 출력합니다:

    $ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000
         sha256:1000000000000000000000000000000000000000000000000000000000000000

authority rotation                                protocol status  algorithm   storage
--------- --------------------------------------- -------- ------- ----------- --------
host      in progress (mode: manual, phase: init) SSH      active  Ed25519     software
                                                  SSH      trusted Ed25519     software
                                                  TLS      active  ECDSA P-256 software
                                                  TLS      trusted ECDSA P-256 software
user      standby (never rotated)                 SSH      active  Ed25519     software
                                                  TLS      active  ECDSA P-256 software
db        standby (never rotated)                 TLS      active  RSA 2048    software
db_client standby (never rotated)                 TLS      active  RSA 2048    software
openssh   standby (never rotated)                 SSH      active  Ed25519     software
jwt       standby (never rotated)                 JWT      active  ECDSA P-256 software
saml_idp  standby (never rotated)                 TLS      active  RSA 2048    software
oidc_idp  standby (never rotated)                 JWT      active  RSA 2048    software
spiffe    standby (never rotated)                 JWT      active  RSA 2048    software
                                                  TLS      active  ECDSA P-256 software
okta      standby (never rotated)                 JWT      active  ECDSA P-256 software

  3. CA 유형에 따라 인프라에 대한 확인 및 업데이트를 수행합니다.

update_clients#

init에서 update_clients로 전환을 실행합니다. 이 단계에서 Teleport Auth Service는 새 CA를 사용하여 인증서를 서명하지만 원래 CA가 서명한 인증서도 계속 신뢰합니다.

  1. update_clients 단계로 전환합니다:

    $ tctl auth rotate --manual --type= --phase=update_clients
# Updated rotation phase to "update_clients". To check status use 'tctl status'
$ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000
         sha256:1000000000000000000000000000000000000000000000000000000000000000

authority rotation                                          protocol status  algorithm   storage
--------- ------------------------------------------------- -------- ------- ----------- --------
host      in progress (mode: manual, phase: update_clients) SSH      active  Ed25519     software
                                                            SSH      trusted Ed25519     software
                                                            TLS      active  ECDSA P-256 software
                                                            TLS      trusted ECDSA P-256 software
user      standby (never rotated)                           SSH      active  Ed25519     software
                                                            TLS      active  ECDSA P-256 software
db        standby (never rotated)                           TLS      active  RSA 2048    software
db_client standby (never rotated)                           TLS      active  RSA 2048    software
openssh   standby (never rotated)                           SSH      active  Ed25519     software
jwt       standby (never rotated)                           JWT      active  ECDSA P-256 software
saml_idp  standby (never rotated)                           TLS      active  RSA 2048    software
oidc_idp  standby (never rotated)                           JWT      active  RSA 2048    software
spiffe    standby (never rotated)                           JWT      active  RSA 2048    software
                                                            TLS      active  ECDSA P-256 software
okta      standby (never rotated)                           JWT      active  ECDSA P-256 software

  2. 다음 단계로 진행하기 전에 CA에 의존하는 인프라를 확인하거나 업데이트합니다.

  3. 리소스에 대한 연결성을 잃은 경우, 새 CA를 수락하도록 재구성해야 하는지 확인하세요. 그래도 접근이 복원되지 않거나 데이터베이스를 재구성할 수 없다면 원래 인증 기관으로 롤백하세요.

update_servers#

update_servers 단계를 시작합니다. 이 단계에서 Teleport 클러스터 구성 요소(에이전트, Auth Service 및 Proxy Service 인스턴스)가 다시 로드되어 새 인증 기관이 서명한 TLS 및 SSH 인증서를 제공하기 시작하지만, 여전히 원래 인증 기관이 발급한 인증서를 수락합니다. 이 단계는 host CA에만 영향을 미칩니다.

  1. 전환을 실행합니다:

    $ tctl auth rotate --manual --type= --phase=update_servers
# Updated rotation phase to "update_servers". To check status use 'tctl status'

$ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000
         sha256:1000000000000000000000000000000000000000000000000000000000000000

authority rotation                                          protocol status  algorithm   storage
--------- ------------------------------------------------- -------- ------- ----------- --------
host      in progress (mode: manual, phase: update_servers) SSH      active  Ed25519     software
                                                            SSH      trusted Ed25519     software
                                                            TLS      active  ECDSA P-256 software
                                                            TLS      trusted ECDSA P-256 software
user      standby (never rotated)                           SSH      active  Ed25519     software
                                                            TLS      active  ECDSA P-256 software
db        standby (never rotated)                           TLS      active  RSA 2048    software
db_client standby (never rotated)                           TLS      active  RSA 2048    software
openssh   standby (never rotated)                           SSH      active  Ed25519     software
jwt       standby (never rotated)                           JWT      active  ECDSA P-256 software
saml_idp  standby (never rotated)                           TLS      active  RSA 2048    software
oidc_idp  standby (never rotated)                           JWT      active  RSA 2048    software
spiffe    standby (never rotated)                           JWT      active  RSA 2048    software
                                                            TLS      active  ECDSA P-256 software
okta      standby (never rotated)                           JWT      active  ECDSA P-256 software

  2. 교체 중인 CA에 따라 리소스를 구성하고 확인합니다. 이는 standby 단계로 전환하기 전에 Teleport로 보호된 리소스를 업데이트할 마지막 기회입니다.

  3. Teleport로 보호된 리소스에 대한 연결성을 잃은 경우, 롤백이 더 이상 불가능한 최종 standby 단계에 진입하기 전에 원래 인증 기관으로 롤백하세요.

최종 standby#

마무리하기 전에 교체한 CA에 의존하는 Teleport로 보호된 리소스에 대한 접근을 잃지 않았는지 확인하세요.

  1. 전환을 실행합니다:

    $ tctl auth rotate --manual --type= --phase=standby

  2. tctl로 교체가 완료되었는지 확인합니다:

    $ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000

authority rotation                                        protocol status algorithm   storage
--------- ----------------------------------------------- -------- ------ ----------- --------
host      standby (last rotated: Apr 4 2025 10:14:51 UTC) SSH      active Ed25519     software
                                                          TLS      active ECDSA P-256 software
user      standby (never rotated)                         SSH      active Ed25519     software
                                                          TLS      active ECDSA P-256 software
db        standby (never rotated)                         TLS      active RSA 2048    software
db_client standby (never rotated)                         TLS      active RSA 2048    software
openssh   standby (never rotated)                         SSH      active Ed25519     software
jwt       standby (never rotated)                         JWT      active ECDSA P-256 software
saml_idp  standby (never rotated)                         TLS      active RSA 2048    software
oidc_idp  standby (never rotated)                         JWT      active RSA 2048    software
spiffe    standby (never rotated)                         JWT      active RSA 2048    software
                                                          TLS      active ECDSA P-256 software
okta      standby (never rotated)                         JWT      active ECDSA P-256 software

  3. CA에 대한 지침에 따라 교체한 CA에 의존하는 Teleport로 보호된 리소스에 연결할 수 있는지 확인하세요. 이것이 롤백할 수 있는 마지막 단계입니다. Teleport로 보호된 리소스에 대한 연결성을 잃은 경우 원래 인증 기관으로 롤백하세요.

3/4단계. [선택 사항] 반자동 교체 실행#

Teleport가 CA 교체를 반자동으로 관리하도록 지시할 수 있습니다. 반자동 교체는 교체 단계 사이를 자동으로 전환하므로 각 단계마다 tctl auth rotate 명령을 실행할 필요가 없습니다. 유예 기간이 경과하면 Teleport Auth Service는 CA 교체 단계를 다음 단계로 업데이트합니다.

반자동 교체 사용 여부 결정#

자동 단계 업데이트를 제외하면, 반자동 교체는 수동 교체와 동일합니다. 유예 기간이 경과하기 전에 현재 단계에 맞게 인프라를 업데이트하는 것은 운영자의 책임입니다.

Teleport는 CA에 의존하는 인프라의 상태를 확인하지 않으며, 문제가 발생하면 연결성을 잃을 수 있습니다. 따라서 인프라에 CA를 내보내야 하는 경우 반자동 교체를 수행해서는 안 됩니다.

반자동 교체를 시도하기 전에 모든 엣지 케이스와 위험을 이해하기 위해 수동 모드로 교체를 먼저 완료하세요.

반자동 교체 시작#

반자동 교체를 실행하려면 tctl로 시작하고 교체 상태를 모니터링하세요.

다음 명령으로 반자동 교체를 트리거할 수 있습니다:

$ tctl auth rotate --type=

이 명령은 기본 유예 기간 48시간으로 호스트에 대한 교체 프로세스를 트리거합니다.

유예 기간 구성

추가 플래그로 유예 기간과 CA 유형을 사용자 지정할 수 있습니다:

# 200시간의 유예 기간으로 사용자 인증서만 교체:
$ tctl auth rotate --type=user --grace-period=200h

# 8시간의 유예 기간으로 호스트 인증서만 교체:
$ tctl auth rotate --type=host --grace-period=8h

host CA를 교체할 때 유예 기간을 신중하게 선택하세요.

유예 기간은 클러스터의 모든 에이전트와 Proxy Service 인스턴스가 새 인증서를 요청할 수 있을 만큼 충분히 길어야 합니다. 일부 호스트가 교체 중에 오프라인 상태가 되고 유예 기간이 끝난 후에야 돌아오면 클러스터를 떠나야 합니다.

반자동 교체 중에 Teleport는 각 단계로 전환하기 전에 동일한 시간을 보내도록 유예 기간을 나누려 합니다. 이는 유예 기간이 짧을수록 상태 전환이 더 빠르게 이루어짐을 의미합니다.

4/4단계. [선택 사항] 교체 롤백#

교체가 standby 상태에 진입하기 전에 롤백을 수행해야 합니다.

  1. 수동 단계 전환으로 롤백 단계에 진입합니다:

    $ tctl auth rotate --phase=rollback --type= --manual
# Updated rotation phase to "rollback". To check status use 'tctl status'

  2. 교체하고 있던 CA에 의존하는 Teleport 리소스에 연결할 수 있는지 확인합니다.

  3. CA 교체 롤백을 완료합니다:

    $ tctl auth rotate --phase=standby --type= --manual
# Updated rotation phase to "standby". To check status use 'tctl status'

추가 읽기#

Teleport 인증 기관 작동 방식.

인증 기관 교체

원문 보기
요약

Teleport 클러스터의 구성 요소들은 X.509 또는 SSH 인증서를 사용하여 서로 인증합니다. 단계를 따르기 전에 전체 가이드를 숙지하는 것을 권장합니다. Teleport는 CA를 독립적으로 유지하며, 하나의 CA를 교체해도 다른 CA의 교체 상태에 영향을 주지 않습니다.

Teleport 클러스터의 구성 요소들은 X.509 또는 SSH 인증서를 사용하여 서로 인증합니다. 인증서를 발급하기 위해 Teleport는 여러 인증 기관을 유지합니다. Teleport CA를 교체하면 악의적인 행위자가 Teleport 클러스터의 일부를 가장하는 것을 방지할 수 있습니다. 이 가이드는 Teleport가 유지하는 CA와 교체 방법을 설명합니다.

단계를 따르기 전에 전체 가이드를 숙지하는 것을 권장합니다. 예상대로 진행되지 않을 경우 CA 교체를 롤백할 준비가 되어 있어야 합니다.

작동 방식#

Teleport는 CA를 독립적으로 유지하며, 하나의 CA를 교체해도 다른 CA의 교체 상태에 영향을 주지 않습니다. 교체 프로세스는 운영자가 인프라를 업데이트하고 필요한 경우 CA 교체를 롤백할 시간을 주는 단계로 진행됩니다.

Teleport CA 교체는 각 CA에 대해 5단계로 이루어집니다. 단계의 순서는 다음과 같습니다:

  1. standby: 교체 진행 중 없음. 아무 작업도 시작되지 않음.
  2. init: 새 인증 기관이 발급되었지만 사용되지 않음.
  3. update_clients: Teleport Auth Service는 새 CA를 사용하여 새 인증서에 서명하지만 원래 CA가 서명한 인증서도 계속 신뢰함.
  4. update_servers: 클라이언트로부터 들어오는 연결을 수락하는 클러스터의 모든 서버 구성 요소가 아이덴티티를 다시 로드하고 새 CA가 발급한 인증서를 제공하기 시작함. 이 단계에서 클라이언트는 원래 CA 또는 새 CA가 발급한 서버 인증서를 수락합니다. host CA를 교체할 때 Teleport 에이전트, Auth Service 및 Proxy Service 인스턴스는 자동으로 아이덴티티를 다시 로드합니다. 이 단계에서 OpenSSH 호스트에 새 SSH 호스트 인증서를 발급해야 합니다.
  5. standby: 교체 진행 중 없음. 모든 작업이 완료됨. 모든 구성 요소가 이전 CA 신뢰를 중단하고 새 CA만 신뢰합니다.

최종 standby 단계 이전에 rollback 단계로 교체를 중단하고 원래 인증 기관으로 돌아갈 수도 있습니다. rollback 단계 후에는 standby 단계로 진행합니다.

CA 교체는 수동 또는 반자동으로 진행할 수 있습니다. 수동 모드에서는 관리자가 Teleport Auth Service에 한 단계에서 다음 단계로 진행하도록 지시해야 합니다. 단계 사이에 관리자는 각 변경 사항에 맞게 인프라를 준비할 수 있습니다. 반자동 모드에서는 Teleport Auth Service가 각 단계 사이에 유예 기간을 두고 자동으로 각 단계를 순환합니다.

17.0.5 이상 버전에서는 tctl auth rotate(인수 없이)를 실행하면 CA 교체를 위한 대화형 터미널 UI가 시작됩니다. 대화형 UI는 실시간 클러스터 상태를 표시하고, 교체할 CA를 선택하고, 각 단계를 안내하며, 클러스터가 다음 단계로 준비되었는지 자동으로 확인하고, 완료해야 하는 수동 단계를 나열합니다.

사전 요구 사항#

  • 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

    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:

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.

  • 사용자는 certificate_authority 리소스에 대해 create 및 update 권한이 있는 역할이 필요합니다.

    kind: role
version: v8
metadata:
  name: rotate-cas
spec:
  allow:
    rules:
    - resources: [ certificate_authority ]
      verbs: [ create, update ]

1/4단계. 교체할 CA 선택#

CA를 교체할 때 각 단계에서 해당 CA에 의존하는 인프라가 연결성을 잃지 않았는지 확인해야 합니다. 또한 새 CA를 인프라로 내보내거나 자체 호스팅 서비스에 새 인증서를 발급해야 할 수 있습니다. 마이그레이션 중 최신 상태를 유지하는 방법을 결정하려면 아래 CA 중 하나를 선택하세요.

CA 유형 인증서 주체
host Teleport 에이전트. Auth Service 및 Proxy Service 인스턴스.
user Teleport 사용자.
db Teleport로 보호되는 자체 호스팅 데이터베이스(사용자는 데이터베이스에 인증서를 배포해야 함).
db_client Teleport Database Service.
openssh Teleport 클러스터에 등록된 OpenSSH 서버.
jwt 웹 애플리케이션에 접근하는 Teleport 사용자.
saml_idp Teleport SAML IdP.
oidc_idp Teleport OIDC IdP 연동.
windows Windows 데스크톱에 연결하는 Teleport 사용자.
awsra Teleport AWS IAM Roles Anywhere 연동.
spiffe 워크로드 아이덴티티(SPIFFE) 클라이언트.
bound_keypair Bound Keypair JWT 검증.

host#

host CA는 Teleport 클라이언트와 Teleport Auth Service가 검증할 수 있도록 Teleport 에이전트 및 Auth Service와 Proxy Service 인스턴스에 인증서를 발급합니다. host CA는 등록된 에이전트 없는 OpenSSH 서버에 SSH 호스트 인증서도 발급합니다.

Teleport 에이전트와 Proxy Service 인스턴스는 하트비트를 사용하여 주기적으로 Teleport Auth Service에 상태를 보고하고 Auth Service가 보유한 데이터를 반영하여 내부 데이터를 업데이트합니다. 이 내부 데이터에는 진행 중인 경우 host CA 교체 상태가 포함됩니다.

에이전트 또는 Proxy Service 인스턴스의 교체 상태를 확인하려면 다음 명령의 변형을 실행하고, 에 에이전트 또는 Proxy Service 인스턴스의 이름을 할당하세요:

$ tctl get  --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}'
{
  "hostname": "terminal",
  "rotation": "in_progress",
  "phase": "init"
}

이 예에서 terminal이라는 Teleport 인스턴스는 상태를 init 단계로 업데이트했습니다. 이는 새 CA 공개 키를 다운로드하고 상태 전환 준비가 되었음을 의미합니다.

다음 리소스로 tctl get 명령을 사용하여 각 에이전트 종류에서 host CA의 교체 상태를 확인할 수 있습니다:

역할 tctl get 값
Application Service app_server
Auth Service auth_server
Database Service db_server
Kubernetes Service kube_server
Proxy Service proxies
SSH Service nodes
Windows Desktop Service windows_desktop_service

host CA 교체의 각 단계에서 다음 단계로 진행하기 전에 모든 에이전트와 Proxy Service 인스턴스가 대상 단계로 전환을 완료했는지 확인하세요. 단계는 2단계에서 설명합니다.

모든 OpenSSH 호스트는 host CA 교체의 update_servers 단계 동안 새 호스트 인증서를 발급받아야 합니다.

Auth Service에 직접 연결하는 Teleport 프로세스는 Auth Service가 제시하는 TLS 인증서를 신뢰하기 위해 CA 핀이 필요합니다. 여기에는 모든 Proxy Service 인스턴스와 Auth Service에 직접 연결하는 자체 호스팅 클러스터의 모든 에이전트가 포함됩니다. CA 교체 중에 tctl status는 CA 핀이 2개 있다고 보고합니다. CA 교체 중에 새 Teleport 에이전트를 클러스터에 추가하는 경우, 보고된 두 CA 핀 모두를 신뢰하도록 구성해야 합니다. 교체가 완료된 후에는 새 CA 핀만 보고됩니다.

참고: Proxy Service에 연결하는 Teleport 에이전트는 Proxy의 TLS 인증서가 신뢰할 수 있는 CA에 의해 발급되어야 하므로 CA 핀이 필요하지 않습니다.

windows#

windows CA는 Windows 데스크톱에 연결하는 사용자를 위한 인증서를 발급합니다. Teleport로 보호되는 Windows 데스크톱은 이 인증서를 사용합니다. v18.7.0 이전 Teleport 버전에서는 user CA가 windows CA의 기능을 수행했습니다.

windows CA를 교체할 때, init 단계에서 Windows 호스트가 새 CA 인증서를 신뢰하도록 구성해야 합니다. Windows Desktop Service가 RDP 호스트에 인증할 수 있도록 Teleport windows CA를 내보내려면 가이드를 따르세요.

update_clients로 진행한 후 교체 전반에 걸쳐 등록된 데스크톱에 연결할 수 있는지 확인하세요.

user#

user CA는 사용자가 Teleport에 인증할 때 인증서를 발급합니다. 또한 Teleport SSH 서버에 연결하는 사용자를 위한 클라이언트 인증서에 서명합니다. Teleport로 보호되는 서버는 이 인증서를 사용합니다.

교체를 완료하고 최종 standby 단계에 도달하기 전에, Teleport에 로그인한 사용자는 새 CA에서 사용자 인증서를 받기 위해 재인증해야 합니다. 그렇지 않으면 웹 세션과 Teleport 클라이언트 명령이 실패하고 사용자가 로그아웃 후 다시 로그인해야 할 수 있습니다. 이를 방지하려면 update_clients와 standby 단계 사이에 최대 사용자 세션 TTL보다 더 오래 기다릴 수 있습니다. 이렇게 하면 이전 CA가 서명한 모든 사용자 인증서가 이미 만료되어 재로그인이 필요하게 됩니다.

db와 db_client#

db와 db_client CA는 Teleport Database Service가 자체 호스팅 데이터베이스와 통신하는 데 사용하는 인증서를 발급합니다.

Teleport Database Service는 자체 호스팅 데이터베이스와 통신할 때 db_client CA가 서명한 인증서를 제시하며, 관리자는 이 CA가 발급한 인증서를 신뢰하도록 데이터베이스를 구성합니다.

관리자는 자체 호스팅 데이터베이스가 db CA가 서명한 인증서를 제시하도록 구성할 수 있으며, Database Service는 이를 사용하여 데이터베이스 서버가 진짜 Teleport로 보호된 리소스인지 확인합니다. 또는 자체 호스팅 데이터베이스는 사용자 지정 CA가 서명한 인증서를 제시할 수 있으며, 관리자는 Teleport Database Service가 해당 CA를 신뢰하도록 구성할 수 있습니다.

데이터베이스 CA 교체#

이 단계에서는 db와 db_client CA를 함께 교체하는 지침을 제공하지만, 하나만 교체하고 동일한 단계를 따르는 것도 가능합니다.

먼저 db와 db_client CA 모두를 init 단계로 교체하기 시작합니다. init 단계에서 tctl auth sign은 새 db CA 키로 서명된 데이터베이스 서버 인증서를 발급하고, 이전 db_client CA 인증서와 새 db_client CA 인증서를 모두 포함하는 CA 파일을 출력합니다. init 단계에서 자체 호스팅 데이터베이스를 새 인증서와 신뢰할 수 있는 CA로 재구성하여 어느 시점에서도 데이터베이스에 대한 접근을 잃지 않도록 해야 합니다.

Note

tctl auth sign --format db는 init 교체 단계의 일반적인 동작에 대한 예외입니다. db CA가 init 단계에 있을 때, tctl auth sign --format db는 새 CA 키로 서명된 데이터베이스 서버 인증서를 발급합니다. 이는 CA 교체 중에 자체 호스팅 데이터베이스를 두 번만 재구성하면 되도록 하기 위한 것입니다: 첫 번째는 init 단계에서 새 db CA가 서명한 인증서를 받고 새 db_client CA를 신뢰하기 시작할 때, 두 번째는 최종 standby 단계에서 이전 db_client CA 신뢰를 중단할 때입니다.

update_clients 교체 단계로 진행하기 전에 데이터베이스 구성에 대한 적절한 문서를 참조하세요.

update_clients 단계로 진행하자마자, Teleport Database Service는 새 db_client CA가 발급한 클라이언트 인증서를 사용하여 데이터베이스에 연결하기 시작합니다. 두 CA를 모두 update_clients 단계로 전환하기 전후에 데이터베이스에 계속 접근할 수 있는지 확인하세요.

모두 정상이면 두 CA를 update_servers 및 standby 단계로 계속 교체합니다. standby 단계에 도달한 후, 이제 교체된 이전 CA 인증서 신뢰를 중단하도록 데이터베이스를 다시 구성할 수 있습니다.

교체 롤백#

롤백하고 싶은 가장 일반적인 이유는 데이터베이스를 재구성할 수 없는 경우입니다. 데이터베이스를 재구성한 후 연결 문제가 발생하면 데이터베이스를 잘못 구성한 것일 가능성이 큽니다.

교체 중에 데이터베이스를 재구성한 경우, standby 단계로 진행하기 전에 rollback 단계에서 다시 재구성해야 합니다.

openssh#

openssh CA는 Proxy Service가 Teleport에 등록된 OpenSSH 서버에 인증하는 데 사용하는 임시 SSH 사용자 인증서를 발급합니다. OpenSSH 에이전트는 Proxy Service로부터 들어오는 연결을 받을 때 이 인증서를 검증합니다.

openssh CA 교체의 init 단계에서 모든 OpenSSH 서버는 기존 공개 키 외에 새 CA 공개 키를 신뢰하도록 업데이트되어야 합니다. 이는 update_clients 단계에서 Proxy Service가 새 CA 키로 서명된 인증서를 사용하기 시작할 때 연결성 손실을 방지하기 위해 필요합니다.

OpenSSH 서버를 등록하기 위해 수동 방법을 사용한 경우, 교체를 update_clients 단계로 전환하기 전에 새 openssh CA 공개 키를 내보내고 OpenSSH 서버에 제공하는 지침을 따라야 합니다.

자동화된 방법을 사용한 경우, update_clients 단계로 진행하기 전에 동일한 단계를 따라 sshd를 재구성해야 합니다.

Note

OpenSSH 서버는 host CA가 발급한 SSH 호스트 인증서를 사용하고 openssh CA가 발급한 들어오는 인증서를 신뢰합니다. host CA를 교체할 때 update_servers 단계에서 새 호스트 인증서로 OpenSSH 서버를 재구성해야 합니다.

jwt#

Teleport Auth Service는 jwt CA를 사용하여 JSON 웹 토큰에 서명합니다. Teleport Application Service는 Teleport로 보호된 애플리케이션에 전달하는 HTTP 메시지에 JSON 웹 토큰을 포함시키며, 애플리케이션은 jwt CA를 사용하여 토큰을 검증합니다.

Teleport에 웹 애플리케이션을 등록했고, 해당 애플리케이션이 Teleport 인증 기관에 대해 JSON 웹 토큰을 검증하여 Teleport Application Service에서 오는 트래픽을 인증하는 경우, 이 애플리케이션이 교체된 CA를 계속 신뢰하도록 해야 합니다.

Teleport로 보호되는 JWT 애플리케이션은 Teleport jwt CA의 공개 키를 검색하는 두 가지 방법 중 하나를 사용합니다. 방법에 따라 init 단계 이후 최종 standby 단계에 도달하기 전에 조치가 필요할 수 있습니다:

  • 애플리케이션이 Teleport Proxy Service의 /.well-known/jwks.json 엔드포인트를 쿼리합니다. 이 경우 애플리케이션이 엔드포인트에 계속 접근할 수 있는 한 조치가 필요하지 않습니다. 애플리케이션이 jwks.json을 캐시하는 경우 캐시를 무효화하세요.
  • 애플리케이션이 로컬 파일시스템의 jwks.json 파일에 접근합니다. /.well-known/jwks.json 엔드포인트를 쿼리하여 새 jwks.json 파일을 얻고 파일을 다시 업로드하세요.

웹 애플리케이션이 Teleport 발급 JWT를 신뢰할 수 있도록 jwt CA를 내보내는 예제는 Elasticsearch에서 JWT 인증 사용 가이드를 참조하세요.

saml_idp#

saml_idp CA는 Teleport IdP가 보내는 SAML 메시지에 서명하여 Teleport IdP에 의존하는 서비스가 검증할 수 있게 합니다.

이 CA를 교체하는 경우, update_clients 단계에 진입하기 전에 Teleport SAML IdP에 의존하는 서비스 제공자가 Teleport saml_idp CA를 신뢰하도록 구성해야 합니다. XML 메타데이터 파일을 내보내고 서비스 제공자에게 제공하려면 SAML IdP 문서의 지침을 따르세요.

oidc_idp#

oidc_idp CA는 Teleport OIDC IdP 연동이 보내는 메시지에 서명합니다. 신뢰 당사자(예: AWS)는 이 메시지를 검증하여 외부 감사 스토리지, 자동 검색, 액세스 그래프를 위한 AWS 동기화와 같은 기능을 위해 Teleport 계정을 인증합니다.

Teleport Proxy Service는 웹 API의 /.well-known/jwks-oidc 경로에서 OIDC IdP 연동을 위한 JSON Web Key Sets를 제공합니다.

Teleport Proxy Service 웹 API의 /.well-known/jwks-oidc 경로는 항상 활성화되어 있습니다. Teleport Proxy Service는 엔드포인트를 자동으로 업데이트합니다.

웹 UI의 /.well-known/openid-configuration 경로를 쿼리하고 jwks_uri 필드를 읽어 연동의 JSON Web Key Sets 전체 URL을 검색할 수 있습니다:

$ curl https://example.teleport.sh/.well-known/openid-configuration | jq '.jwks_uri'
"https://example.teleport.sh/.well-known-jwks-oidc"

spiffe#

spiffe CA는 워크로드 아이덴티티 클라이언트를 위한 X509 및 JWT SVID에 서명합니다. 이는 종종 다른 클라이언트가 mTLS로 서로 아이덴티티를 검증할 수 있게 합니다.

이 CA를 교체할 때, 최종 standby 단계에 진입하기 전에 Teleport 발급 SVID를 검증하는 모든 클라이언트가 새 CA를 신뢰하도록 업데이트되었는지 확인하세요:

  • Teleport 워크로드 아이덴티티 클라이언트는 tbot 클라이언트를 통해 업데이트된 CA 인증서를 자동으로 받아야 하며, 향후 SVID는 새 CA를 사용하여 발급됩니다.

    tbot의 workload-identity-api 서비스를 사용하는 경우, 클라이언트 애플리케이션이 새 SVID를 가져오기 위한 추가 단계가 필요할 수 있습니다. spiffe-svid 출력 중 하나로 자격 증명을 생성하는 경우, 새 SVID는 자동으로 발급되어야 합니다.

  • SPIFFE 페더레이션을 사용하는 경우, 다른 SPIFFE 신뢰 도메인은 주기적으로 Teleport의 인증서 번들을 갱신해야 합니다. 이 간격은 일반적으로 5분이지만, 번들 자체를 검사하여 확인할 수 있습니다:

    $ curl https://example.teleport.sh/webapi/spiffe/bundle.json | jq '.spiffe_refresh_hint'

awsra#

awsra CA는 AWS 임시 세션으로 교환하기 위해 AWS에 전송되는 X.509 인증서에 서명합니다. AWS는 신뢰 앵커로 추가하여 awsra CA를 신뢰하도록 구성되어야 합니다. 이 연동을 통해 AWS CLI 및 콘솔 접근이 가능합니다.

교체를 시작한 후 동일한 AWS IAM Roles Anywhere 신뢰 앵커에 새 CA를 추가해야 합니다.

이 기간 동안 AWS는 이전 CA와 새 CA 모두를 신뢰합니다. 모든 새 세션은 새 CA를 사용합니다.

교체가 완료된 후 AWS IAM Roles Anywhere 신뢰 앵커에서 이전 CA를 제거해야 합니다.

bound_keypair#

bound_keypair CA는 Bound Keypair 조인 상태 검증을 위해 발급된 JWT에 서명합니다. 이는 bound_keypair 조인 방법을 사용하여 Teleport 클러스터에 조인하는 클라이언트가 저장하는 추가 문서로, 각 조인 시도를 고유하게 식별하며 이후 조인 시 Teleport에 의해 추가로 검증됩니다.

교체 중에 클라이언트는 조인 상태 JWT에 서명하는 데 사용된 CA가 활성 상태이거나 신뢰받는 한 예상대로 계속 조인할 수 있으며, 이는 update_servers 단계까지 유효합니다.

Machine & Workload ID 봇은 활성 상태인 경우 교체 이벤트를 감지하고 인증서를 갱신해야 하며, 이를 통해 새 CA로 서명된 새 조인 상태 JWT를 자동으로 가져옵니다. 현재 실행 중이지 않은 봇은 한 번 시작되어 새 인증서를 가져올 수 있어야 하며, 이를 통해 조인 상태 JWT도 갱신됩니다.

CA 교체 후 조인 상태 검증이 실패하면 조인 상태 검증을 임시로 비활성화하여 클라이언트가 다시 조인할 수 있게 허용할 수 있습니다. 다음 조인 시 새 조인 상태 JWT가 발급되며, 그 후 조인 상태 검증을 안전하게 다시 활성화할 수 있습니다.

2/4단계. 수동 교체 시작#

교체할 CA를 선택하고 해당 CA에 의존하는 인프라를 확인하거나 업데이트할 계획을 세웠다면, 수동 교체를 시작할 준비가 된 것입니다.

Tip

17.0.5 이상 버전에서는 tctl auth rotate(인수 없이)를 실행하면 CA 교체를 위한 대화형 터미널 UI가 시작됩니다. 대화형 UI는 실시간 클러스터 상태를 표시하고, 교체할 CA를 선택하고, 각 단계를 안내하며, 클러스터가 다음 단계로 준비되었는지 자동으로 확인하고, 완료해야 하는 수동 단계를 나열합니다. 가능하면 대화형 교체를 사용하는 것을 권장하지만, 각 교체 단계를 수동으로 시작하는 방법을 알아보려면 계속 읽으세요.

init 단계#

init 단계에서 Teleport Auth Service는 선택된 유형의 새 인증 기관을 발급하지만, 인증서 서명에 사용하지 않습니다.

  1. 호스트 인증 기관의 수동 교체를 시작합니다:

    $ tctl auth rotate --manual --type= --phase=init
Updated rotation phase to "init". To check status use 'tctl status'

  2. tctl을 사용하여 교체가 진행 중인지 확인합니다. 이 명령은 클러스터에서 Teleport Auth Service가 유지하는 모든 CA의 교체 상태를 출력합니다:

    $ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000
         sha256:1000000000000000000000000000000000000000000000000000000000000000

authority rotation                                protocol status  algorithm   storage
--------- --------------------------------------- -------- ------- ----------- --------
host      in progress (mode: manual, phase: init) SSH      active  Ed25519     software
                                                  SSH      trusted Ed25519     software
                                                  TLS      active  ECDSA P-256 software
                                                  TLS      trusted ECDSA P-256 software
user      standby (never rotated)                 SSH      active  Ed25519     software
                                                  TLS      active  ECDSA P-256 software
db        standby (never rotated)                 TLS      active  RSA 2048    software
db_client standby (never rotated)                 TLS      active  RSA 2048    software
openssh   standby (never rotated)                 SSH      active  Ed25519     software
jwt       standby (never rotated)                 JWT      active  ECDSA P-256 software
saml_idp  standby (never rotated)                 TLS      active  RSA 2048    software
oidc_idp  standby (never rotated)                 JWT      active  RSA 2048    software
spiffe    standby (never rotated)                 JWT      active  RSA 2048    software
                                                  TLS      active  ECDSA P-256 software
okta      standby (never rotated)                 JWT      active  ECDSA P-256 software

  3. CA 유형에 따라 인프라에 대한 확인 및 업데이트를 수행합니다.

update_clients#

init에서 update_clients로 전환을 실행합니다. 이 단계에서 Teleport Auth Service는 새 CA를 사용하여 인증서를 서명하지만 원래 CA가 서명한 인증서도 계속 신뢰합니다.

  1. update_clients 단계로 전환합니다:

    $ tctl auth rotate --manual --type= --phase=update_clients
# Updated rotation phase to "update_clients". To check status use 'tctl status'
$ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000
         sha256:1000000000000000000000000000000000000000000000000000000000000000

authority rotation                                          protocol status  algorithm   storage
--------- ------------------------------------------------- -------- ------- ----------- --------
host      in progress (mode: manual, phase: update_clients) SSH      active  Ed25519     software
                                                            SSH      trusted Ed25519     software
                                                            TLS      active  ECDSA P-256 software
                                                            TLS      trusted ECDSA P-256 software
user      standby (never rotated)                           SSH      active  Ed25519     software
                                                            TLS      active  ECDSA P-256 software
db        standby (never rotated)                           TLS      active  RSA 2048    software
db_client standby (never rotated)                           TLS      active  RSA 2048    software
openssh   standby (never rotated)                           SSH      active  Ed25519     software
jwt       standby (never rotated)                           JWT      active  ECDSA P-256 software
saml_idp  standby (never rotated)                           TLS      active  RSA 2048    software
oidc_idp  standby (never rotated)                           JWT      active  RSA 2048    software
spiffe    standby (never rotated)                           JWT      active  RSA 2048    software
                                                            TLS      active  ECDSA P-256 software
okta      standby (never rotated)                           JWT      active  ECDSA P-256 software

  2. 다음 단계로 진행하기 전에 CA에 의존하는 인프라를 확인하거나 업데이트합니다.

  3. 리소스에 대한 연결성을 잃은 경우, 새 CA를 수락하도록 재구성해야 하는지 확인하세요. 그래도 접근이 복원되지 않거나 데이터베이스를 재구성할 수 없다면 원래 인증 기관으로 롤백하세요.

update_servers#

update_servers 단계를 시작합니다. 이 단계에서 Teleport 클러스터 구성 요소(에이전트, Auth Service 및 Proxy Service 인스턴스)가 다시 로드되어 새 인증 기관이 서명한 TLS 및 SSH 인증서를 제공하기 시작하지만, 여전히 원래 인증 기관이 발급한 인증서를 수락합니다. 이 단계는 host CA에만 영향을 미칩니다.

  1. 전환을 실행합니다:

    $ tctl auth rotate --manual --type= --phase=update_servers
# Updated rotation phase to "update_servers". To check status use 'tctl status'

$ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000
         sha256:1000000000000000000000000000000000000000000000000000000000000000

authority rotation                                          protocol status  algorithm   storage
--------- ------------------------------------------------- -------- ------- ----------- --------
host      in progress (mode: manual, phase: update_servers) SSH      active  Ed25519     software
                                                            SSH      trusted Ed25519     software
                                                            TLS      active  ECDSA P-256 software
                                                            TLS      trusted ECDSA P-256 software
user      standby (never rotated)                           SSH      active  Ed25519     software
                                                            TLS      active  ECDSA P-256 software
db        standby (never rotated)                           TLS      active  RSA 2048    software
db_client standby (never rotated)                           TLS      active  RSA 2048    software
openssh   standby (never rotated)                           SSH      active  Ed25519     software
jwt       standby (never rotated)                           JWT      active  ECDSA P-256 software
saml_idp  standby (never rotated)                           TLS      active  RSA 2048    software
oidc_idp  standby (never rotated)                           JWT      active  RSA 2048    software
spiffe    standby (never rotated)                           JWT      active  RSA 2048    software
                                                            TLS      active  ECDSA P-256 software
okta      standby (never rotated)                           JWT      active  ECDSA P-256 software

  2. 교체 중인 CA에 따라 리소스를 구성하고 확인합니다. 이는 standby 단계로 전환하기 전에 Teleport로 보호된 리소스를 업데이트할 마지막 기회입니다.

  3. Teleport로 보호된 리소스에 대한 연결성을 잃은 경우, 롤백이 더 이상 불가능한 최종 standby 단계에 진입하기 전에 원래 인증 기관으로 롤백하세요.

최종 standby#

마무리하기 전에 교체한 CA에 의존하는 Teleport로 보호된 리소스에 대한 접근을 잃지 않았는지 확인하세요.

  1. 전환을 실행합니다:

    $ tctl auth rotate --manual --type= --phase=standby

  2. tctl로 교체가 완료되었는지 확인합니다:

    $ tctl status
Cluster       teleport.example.com
Version       (=teleport.version=)
CA pins: sha256:0000000000000000000000000000000000000000000000000000000000000000

authority rotation                                        protocol status algorithm   storage
--------- ----------------------------------------------- -------- ------ ----------- --------
host      standby (last rotated: Apr 4 2025 10:14:51 UTC) SSH      active Ed25519     software
                                                          TLS      active ECDSA P-256 software
user      standby (never rotated)                         SSH      active Ed25519     software
                                                          TLS      active ECDSA P-256 software
db        standby (never rotated)                         TLS      active RSA 2048    software
db_client standby (never rotated)                         TLS      active RSA 2048    software
openssh   standby (never rotated)                         SSH      active Ed25519     software
jwt       standby (never rotated)                         JWT      active ECDSA P-256 software
saml_idp  standby (never rotated)                         TLS      active RSA 2048    software
oidc_idp  standby (never rotated)                         JWT      active RSA 2048    software
spiffe    standby (never rotated)                         JWT      active RSA 2048    software
                                                          TLS      active ECDSA P-256 software
okta      standby (never rotated)                         JWT      active ECDSA P-256 software

  3. CA에 대한 지침에 따라 교체한 CA에 의존하는 Teleport로 보호된 리소스에 연결할 수 있는지 확인하세요. 이것이 롤백할 수 있는 마지막 단계입니다. Teleport로 보호된 리소스에 대한 연결성을 잃은 경우 원래 인증 기관으로 롤백하세요.

3/4단계. [선택 사항] 반자동 교체 실행#

Teleport가 CA 교체를 반자동으로 관리하도록 지시할 수 있습니다. 반자동 교체는 교체 단계 사이를 자동으로 전환하므로 각 단계마다 tctl auth rotate 명령을 실행할 필요가 없습니다. 유예 기간이 경과하면 Teleport Auth Service는 CA 교체 단계를 다음 단계로 업데이트합니다.

반자동 교체 사용 여부 결정#

자동 단계 업데이트를 제외하면, 반자동 교체는 수동 교체와 동일합니다. 유예 기간이 경과하기 전에 현재 단계에 맞게 인프라를 업데이트하는 것은 운영자의 책임입니다.

Teleport는 CA에 의존하는 인프라의 상태를 확인하지 않으며, 문제가 발생하면 연결성을 잃을 수 있습니다. 따라서 인프라에 CA를 내보내야 하는 경우 반자동 교체를 수행해서는 안 됩니다.

반자동 교체를 시도하기 전에 모든 엣지 케이스와 위험을 이해하기 위해 수동 모드로 교체를 먼저 완료하세요.

반자동 교체 시작#

반자동 교체를 실행하려면 tctl로 시작하고 교체 상태를 모니터링하세요.

다음 명령으로 반자동 교체를 트리거할 수 있습니다:

$ tctl auth rotate --type=

이 명령은 기본 유예 기간 48시간으로 호스트에 대한 교체 프로세스를 트리거합니다.

유예 기간 구성

추가 플래그로 유예 기간과 CA 유형을 사용자 지정할 수 있습니다:

# 200시간의 유예 기간으로 사용자 인증서만 교체:
$ tctl auth rotate --type=user --grace-period=200h

# 8시간의 유예 기간으로 호스트 인증서만 교체:
$ tctl auth rotate --type=host --grace-period=8h

host CA를 교체할 때 유예 기간을 신중하게 선택하세요.

유예 기간은 클러스터의 모든 에이전트와 Proxy Service 인스턴스가 새 인증서를 요청할 수 있을 만큼 충분히 길어야 합니다. 일부 호스트가 교체 중에 오프라인 상태가 되고 유예 기간이 끝난 후에야 돌아오면 클러스터를 떠나야 합니다.

반자동 교체 중에 Teleport는 각 단계로 전환하기 전에 동일한 시간을 보내도록 유예 기간을 나누려 합니다. 이는 유예 기간이 짧을수록 상태 전환이 더 빠르게 이루어짐을 의미합니다.

4/4단계. [선택 사항] 교체 롤백#

교체가 standby 상태에 진입하기 전에 롤백을 수행해야 합니다.

  1. 수동 단계 전환으로 롤백 단계에 진입합니다:

    $ tctl auth rotate --phase=rollback --type= --manual
# Updated rotation phase to "rollback". To check status use 'tctl status'

  2. 교체하고 있던 CA에 의존하는 Teleport 리소스에 연결할 수 있는지 확인합니다.

  3. CA 교체 롤백을 완료합니다:

    $ tctl auth rotate --phase=standby --type= --manual
# Updated rotation phase to "standby". To check status use 'tctl status'

추가 읽기#

Teleport 인증 기관 작동 방식.