Teleport can automatically create users in your database, removing the need for creating individual user accounts in advance or using the same set of shared database accounts for all users.

전제 조건#

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

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

Teleport should be able to connect to the database as a user that can create other users and assign them roles. We recommend creating a separate user designated specifically for Teleport automatic user provisioning. Let's call it teleport-admin.

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

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

GRANT rds_superuser TO "teleport-admin";

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

CREATE USER "teleport-admin" login createrole;

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

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 그룹에 배치되며, 해당 그룹이 존재하지 않으면 자동으로 생성됩니다.

Next, configure the database admin user in the Teleport database configuration:

kind: db
version: v3
metadata:
  name: example
spec:
  protocol: "postgres"
  uri: "localhost:5432"
  admin_user:
    name: "teleport-admin"
    # Optional default database the admin user logs into. Default is
    # the same database that the user is accessing, if not specified.
    # default_database: teleport

This example assumes that you have configured the database as a dynamic resource. If you have configured your database using a static Teleport Database Service configuration, edit the entry in your db_service.databases configuration.

For auto-discovered cloud databases, the name of the admin user is taken from the teleport.dev/db-admin label, and the default database is taken from the teleport.dev/db-admin-default-database label.

2/3단계. Teleport 역할 구성#

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

With automatic user provisioning, users always connect to the database with their Teleport username so the db_users role field is ignored for roles that have database user provisioning enabled.

The available provisioning modes are:

• off: Disables user provisioning.

• keep: Enables user provisioning and disables users at session end. The user will be stripped of all roles and the user account will be locked.

• best_effort_drop: Enables user provisioning and, when the session ends, drops the user if no resources depend on it. In cases where any resource depends on the user, it falls back to disabling the user, mirroring the behavior of keep mode.

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 역할의 일부가 됩니다.
• 선택한 메커니즘에 따라 권한이 할당됩니다.

Note that in case of a name conflict where a user with the same name already exists in the database and is not managed by Teleport (i.e. not assigned the teleport-auto-user role), the connection will be aborted.

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

Now, log into your Teleport cluster and connect to the database:

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

To view the list of database roles that are allowed for each database, you can use the command tsh db ls -v. By default, all database roles will be assigned to your auto-provisioned database user. You can optionally select a subset of the database roles with --db-roles:

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

문제 해결#

사용자가 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;

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

You may encounter the following error when connecting to a database in a remote cluster:

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

When you access resources in a remote cluster, the remote cluster will receive the name remote-<your-teleport-username>-<root-cluster-name> from the local cluster. This is to prevent any naming collisions with users in the remote cluster. Please use the username from the error message as the database username for when connecting through tsh or GUI clients.

Unable to cancel a query#

If you use a PostgreSQL cli client like psql, and you try to cancel a query with Ctrl+C, but it doesn't cancel the query, then you need to connect using a tsh local proxy instead. When psql cancels a query, it establishes a new connection without TLS certificates, however Teleport requires TLS certificates not only for authentication, but also to route database connections.

If you enable TLS Routing in Teleport then tsh db connect will automatically start a local proxy for every connection. Alternatively, you can connect via Teleport Connect which also uses a local proxy. Otherwise, you need to start a tsh local proxy manually using tsh proxy db and connect via the local proxy.

If you have already started a long-running query in a psql session that you cannot cancel with Ctrl+C, you can start a new client session to cancel that query manually:

First, find the query's process identifier (PID):

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

Next, gracefully cancel the query using its PID. This will send a SIGINT signal to the postgres backend process for that query:

SELECT pg_cancel_backend(<PID>);

You should always try to gracefully terminate a query first, but if graceful cancellation is taking too long, then you can forcefully terminate the query instead. This will send a SIGTERM signal to the postgres backend process for that query:

SELECT pg_terminate_backend(<PID>);

See the PostgreSQL documentation on admin functions for more information about the pg_cancel_backend and pg_terminate_backend functions.

SSL SYSCALL error#

You may encounter the following error when your local psql is not compatible with newer versions of 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

Please upgrade your local psql to the latest version.

Amazon RDS Blue/Green 배포가 "복제 저하" 상태로 진입#

자동 사용자 프로비저닝을 사용하여 데이터베이스에 연결할 때 Amazon RDS Blue/Green 배포가 "복제 저하" 상태로 진입할 수 있습니다.

이는 Blue/Green 배포에 대한 PostgreSQL 논리적 복제의 제한으로 인해 발생합니다. DDL(데이터 정의 언어) 문은 복제할 수 없기 때문입니다. 결과적으로 DDL 변경이 감지되면 Amazon RDS는 "복제 저하" 상태로 진입합니다.

Blue/Green 배포를 시작하기 전에 데이터베이스 자동 사용자 프로비저닝을 비활성화하는 것이 권장됩니다.

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

자동 사용자 프로비저닝이 비활성화된 후에도 Teleport를 통해 데이터베이스 관리자 사용자로 연결할 수 있습니다.

다음 단계#

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