Teleport는 데이터베이스에서 사용자를 자동으로 생성할 수 있어, 개별 사용자 계정을 미리 만들거나 모든 사용자에게 동일한 공유 데이터베이스 계정을 사용하는 필요성을 제거합니다.

필수 조건

• 구성된 자체 호스팅된 PostgreSQL 또는 RDS PostgreSQL 데이터베이스가 있는 Teleport 클러스터 v13.1 이상. 테이블과 같은 데이터베이스 객체에 대한 권한을 구성하려면 클러스터가 v15.2 이상이어야 합니다.
• 대상 데이터베이스에 연결하고 사용자 계정을 생성할 수 있는 능력.

1/3단계. 데이터베이스 관리자 구성

Teleport는 다른 사용자를 생성하고 그들에게 역할을 할당할 수 있는 사용자로 데이터베이스에 연결할 수 있어야 합니다. Teleport 자동 사용자 프로비저닝을 위해 특별히 지정된 별도의 사용자 생성을 권장합니다. 이를 teleport-admin 이라고 부릅시다.

Teleport는 관리 사용자로 연결할 때 일반 사용자 연결과 동일한 인증 메커니즘을 사용합니다: 자체 호스팅된 데이터베이스의 경우 X.509, RDS의 경우 AWS IAM. 관리 사용자는 역할 또는 구체적인 데이터베이스 객체에 대해 사용자를 생성하고 권한을 부여할 수 있는 권한을 데이터베이스 내에서 가져야 합니다.

CREATE USER "teleport-admin" login createrole;
GRANT rds_iam TO "teleport-admin" WITH ADMIN OPTION;

CREATE USER "teleport-admin" login createrole;

hostssl all             all             ::/0                    cert
hostssl all             all             0.0.0.0/0               cert

GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA schema1, schema2, schema3 TO "teleport-admin";

Teleport에 의해 생성된 사용자는 데이터베이스의 teleport-auto-user 그룹에 배치되며, 이 그룹은 존재하지 않는 경우 자동으로 생성됩니다.

다음으로 Teleport 데이터베이스 구성에서 데이터베이스 관리 사용자(admin user)를 설정합니다:

kind: db  
version: v3  
metadata:  
  name: example  
spec:  
  protocol: "postgres"  
  uri: "localhost:5432"  
  admin_user:  
    name: "teleport-admin"  
    # 관리 사용자가 로그인하는 선택적 기본 데이터베이스입니다. 지정하지 않으면 기본값은  
    # 사용자가 액세스하고 있는 동일한 데이터베이스입니다.  
    # default_database: teleport  

이 예제는 데이터베이스가 동적 리소스로 구성되었다고 가정합니다. 정적 Teleport 데이터베이스 서비스 구성으로 데이터베이스를 구성한 경우, db_service.databases 구성에서 항목을 편집하십시오.

자동 검색된 클라우드 데이터베이스의 경우, 관리 사용자의 이름은 teleport.dev/db-admin 레이블에서 가져오며, 기본 데이터베이스는 teleport.dev/db-admin-default-database 레이블에서 가져옵니다.

GRANT CREATE ON SCHEMA public TO "teleport-admin";

2/3단계. Teleport 역할 구성

데이터베이스 권한은 Teleport 역할에 연결되어 있으며, 이는 미리 정의된 데이터베이스 역할(각 데이터베이스에 구성됨)을 할당하거나 특정 데이터베이스 객체 권한을 직접 정의할 수 있습니다. Teleport는 연결 기간 동안 이러한 권한을 부여합니다.

자동 사용자 프로비저닝이 적용되면, 사용자는 항상 자신이 Teleport에서 사용하는 사용자 이름으로 데이터베이스에 연결하므로 db_users 역할 필드는 데이터베이스 사용자 프로비저닝이 활성화된 역할에 대해 무시됩니다.

사용 가능한 프로비저닝 모드는 다음과 같습니다:

• off : 사용자 프로비저닝을 비활성화합니다.

• keep : 사용자 프로비저닝을 활성화하고 세션 종료 시 사용자를 비활성화합니다. 사용자는 모든 역할을 제거당하고 사용자 계정이 잠깁니다.

• best_effort_drop : 사용자 프로비저닝을 활성화하며, 세션이 종료되면 리소스가 사용자에 의존하지 않는 경우 사용자를 제거합니다. 어떤 리소스라도 사용자에 의존하는 경우, keep 모드의 동작을 따라 사용자를 비활성화합니다.

kind: role
version: v7
metadata:
  name: auto-db-users
spec:
  options:
    # create_db_user_mode는 일치하는 데이터베이스에 대해 자동 사용자 프로비저닝을 활성화합니다.
    create_db_user_mode: keep
  allow:
    db_labels:
      "*": "*"
    db_names:
      - "*"
    # db_roles는 데이터베이스 사용자가 할당받을 역할 목록입니다.
    db_roles:
      - reader
      - "{{internal.db_roles}}"
      - "{{external.db_roles}}"

kind: role
metadata:
  name: read_all_tables
spec:
  options:
    # create_db_user_mode는 일치하는 데이터베이스에 대해 자동 사용자 프로비저닝을 활성화합니다.
    create_db_user_mode: keep
  allow:
    db_labels:
      "*": "*"
    db_names:
      - "*"
    db_permissions:
      # `public` 스키마의 모든 테이블에 대해 `SELECT` 를 부여합니다.
      - match:
          # 일치할 객체 레이블
          object_kind: table
          schema: public
        permissions:
          - SELECT
version: v7

데이터베이스 내에서 생성된 사용자는:

• 인증된 Teleport 사용자와 동일한 사용자 이름을 가집니다.
• teleport-auto-user 역할의 일원입니다.
• 선택한 메커니즘에 따라 권한이 할당됩니다.

이름 충돌이 발생하여 데이터베이스에 동일한 이름을 가진 사용자가 이미 존재하고 해당 사용자가 Teleport에 의해 관리되지 않는 경우 (즉, teleport-auto-user 역할이 할당되지 않은 경우) 연결이 중단됩니다.

3/3단계. 데이터베이스에 연결

이제 Teleport 클러스터에 로그인하고 데이터베이스에 연결하세요:

tsh login --proxy=teleport.example.com
tsh db connect --db-name <database> example

각 데이터베이스에 허용된 데이터베이스 역할 목록을 보려면 tsh db ls -v 명령을 사용할 수 있습니다. 기본적으로 모든 데이터베이스 역할은 자동으로 프로비저닝된 데이터베이스 사용자에게 할당됩니다. 선택적으로 --db-roles 로 데이터베이스 역할의 하위 집합을 선택할 수 있습니다:

tsh db connect --db-name <database> --db-roles reader example

문제 해결

public 스키마에 대한 권한 거부 오류

PostgreSQL 15는 공용(또는 기본) 스키마에서 데이터베이스 소유자를 제외한 모든 사용자에게 CREATE 권한을 철회합니다.

관리자 사용자에게 절차를 생성할 수 있도록 CREATE 권한을 부여합니다:

GRANT CREATE ON SCHEMA public TO "teleport-admin";

admin_user.default_database 가 지정된 경우, CREATE 권한은 지정된 default_database 에 대해서만 필요합니다. 그렇지 않으면, Teleport가 액세스할 모든 데이터베이스에 대해 권한 부여를 반복해야 합니다.

사용자가 CONNECT 권한이 없는 오류

관리 사용자 또는 자동 프로비저닝된 사용자에게 할당된 역할이 대상 데이터베이스에 연결할 수 있는 권한이 없으면 다음과 같은 오류가 발생할 수 있습니다:

tsh db connect --db-name <database> example
...FATAL: permission denied for database "<database>"DETAIL: User does not have CONNECT privilege.

관리 사용자 및 해당 역할에 대해 CONNECT 가 부여되었는지 확인하십시오:

GRANT CONNECT ON DATABASE <database> to "teleport-admin";
GRANT CONNECT ON DATABASE <database> to "reader";

읽기 전용 트랜잭션 오류 실행 불가

Amazon RDS Aurora 리더 엔드포인트에 연결할 때 다음 오류가 발생할 수 있습니다:

tsh db connect --db-name <database> example
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused...ERROR: cannot execute CREATE ROLE in a read-only transaction (SQLSTATE 25006)

데이터베이스 자동 사용자 프로비저닝은 RDS Aurora 리더 엔드포인트와 호환되지 않습니다. 기본 엔드포인트에서 자동 사용자 프로비저닝을 사용하십시오.

스키마가 선택되지 않았습니다 오류

관리 사용자가 스키마에 대한 USAGE 권한이 없는 경우 다음 오류가 발생할 수 있습니다:

tsh db connect --db-name <database> example
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused...ERROR: no schema has been selected to create in (SQLSTATE 3F000)

이를 해결하려면, 대상 데이터베이스의 public 스키마에서 관리 사용자에게 USAGE 및 CREATE 권한을 부여하십시오:

GRANT USAGE ON SCHEMA public TO "teleport-admin";
GRANT CREATE ON SCHEMA public TO "teleport-admin";

역할 "rds_iam" 부여 권한 거부

RDS 데이터베이스에 연결할 때 다음 오류가 발생할 수 있습니다:

tsh db connect --db-name <database> example
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused...ERROR: permission denied to grant role "rds_iam" (SQLSTATE 42501)

이는 관리 사용자가 다른 사용자에게 "rds_iam" 역할을 부여할 권한이 없을 때 발생합니다. 이를 해결하려면, 관리 사용자에게 ADMIN 옵션을 사용하여 "rds_iam" 역할을 부여하십시오:

GRANT rds_iam TO "teleport-admin" WITH ADMIN OPTION;

매핑된 원격 사용자 이름 오류 사용

다음 오류가 원격 클러스터의 데이터베이스에 연결할 때 발생할 수 있습니다:

> tsh db connect --db-name <database> exampleERROR: please use your mapped remote username ("remote-<your-teleport-username>-<root-cluster-name>") to connect instead of "<database-user>"

원격 클러스터의 자원에 접근할 때, 원격 클러스터는 로컬 클러스터에서 remote-<your-teleport-username>-<root-cluster-name> 이라는 이름을 받습니다. 이는 원격 클러스터의 사용자와 이름 충돌을 방지하기 위함입니다. 오류 메시지에 있는 사용자 이름을 데이터베이스 사용자 이름으로 사용하여 tsh 또는 GUI 클라이언트를 통해 연결해 주시기 바랍니다.

쿼리를 취소할 수 없습니다

psql 과 같은 PostgreSQL cli 클라이언트를 사용하고 ctrl+c 로 쿼리를 취소하려고 하지만 쿼리를 취소할 수 없는 경우, 대신 tsh 로컬 프록시를 사용하여 연결해야 합니다.
psql 이 쿼리를 취소하면 TLS 인증서 없이 새로운 연결을 설정하지만, Teleport는 인증 뿐만 아니라 데이터베이스 연결을 라우팅하기 위해 TLS 인증서를 필요로 합니다.

만약에
Teleport에서 TLS 라우팅을 활성화하면 tsh db connect 가 자동으로 각 연결에 대해 로컬 프록시를 시작합니다.
또는 로컬 프록시를 사용하는
Teleport Connect를 통해 연결할 수 있습니다.
그렇지 않으면, tsh proxy db 를 사용하여 로컬 프록시를 수동으로 시작하고 로컬 프록시를 통해 연결해야 합니다.

이미 psql 세션에서 취소할 수 없는 장기 실행 쿼리를 시작한 경우, 해당 쿼리를 수동으로 취소하기 위해 새 클라이언트 세션을 시작할 수 있습니다:

먼저 쿼리의 프로세스 식별자(PID)를 찾습니다:

SELECT pid,usename,backend_start,query FROM pg_stat_activity WHERE state = 'active';

다음으로, 해당 PID를 사용하여 쿼리를 정상적으로 취소합니다.
이렇게 하면 해당 쿼리의 postgres 백엔드 프로세스에 SIGINT 신호가 전송됩니다:

SELECT pg_cancel_backend(<PID>);

항상 쿼리를 정상적으로 종료하려고 시도해야 하지만, 정상적인 취소에 시간이 너무 오래 걸리는 경우, 대신 쿼리를 강제로 종료할 수 있습니다.
이렇게 하면 해당 쿼리의 postgres 백엔드 프로세스에 SIGTERM 신호가 전송됩니다:

SELECT pg_terminate_backend(<PID>);

pg_cancel_backend 및 pg_terminate_backend 함수에 대한
PostgreSQL 문서를 참조하십시오.

SSL SYSCALL 오류

로컬 psql 이 최신 버전의 OpenSSL과 호환되지 않을 때 다음 오류가 발생할 수 있습니다:

tsh db connect --db-user postgres --db-name postgres postgres
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused    Is the server running on that host and accepting TCP/IP connections?connection to server at "localhost" (127.0.0.1), port 12345 failed: SSL SYSCALL error: Undefined error: 0

로컬 psql 을 최신 버전으로 업그레이드하십시오.

Amazon RDS 블루/그린 배포가 "복제 저하" 상태에 진입

Amazon RDS 블루/그린 배포는 데이터베이스에 연결하기 위해 자동 사용자 프로비저닝을 사용하면 "복제 저하" 상태에 진입할 수 있습니다.

이는 데이터 정의 언어(DDL) 문이 복제될 수 없기 때문에 PostgreSQL 논리 복제의 제한으로 인해 발생합니다. DDL 변경 사항이 감지되면 Amazon RDS는 "복제 저하" 상태에 진입합니다.

블루/그린 배포를 시작하기 전에 데이터베이스 자동 사용자 프로비저닝을 비활성화하는 것이 좋습니다.

데이터베이스가 Teleport에 의해 자동으로 발견되는 경우, teleport.dev/db-admin AWS 리소스 태그를 일시적으로 제거할 수 있습니다. 정적 구성 또는 동적 db 리소스를 사용하여 등록된 데이터베이스의 경우 admin_user 설정을 일시적으로 제거할 수 있습니다.

자동 사용자 프로비저닝이 비활성화되면 여전히 Teleport를 통해 데이터베이스 관리 사용자로 연결할 수 있습니다.

다음 단계

• GUI 데이터베이스 클라이언트를 사용하여 연결하십시오.
• 역할 템플릿화에 대해 알아보십시오.
• 자동 사용자 프로비저닝 RFD를 읽어보십시오.
• 데이터베이스 권한 관리 RFD를 읽어보십시오.
• 이 가이드에서 설명한 internal.db_roles 특성은 Teleport 로컬 사용자 데이터베이스의 값으로 대체됩니다. Teleport 역할에서 변수 확장이 작동하는 방법에 대한 전체 세부정보는 Teleport 접근 제어 참고서를 참조하십시오.