데이터베이스 시크릿 엔진

데이터베이스 시크릿 엔진 (Database secrets engine)

구성된 역할을 기반으로 데이터베이스 자격 증명을 동적으로 생성하는 데이터베이스 시크릿 엔진을 다룹니다.

출처: 문서

본문

데이터베이스 시크릿 엔진은 구성된 역할을 기반으로 데이터베이스 자격 증명을 동적으로 생성해요. 플러그인 인터페이스를 통해 여러 다른 데이터베이스와 함께 동작합니다. 내장 데이터베이스 타입도 여러 개 있고, 확장성을 위해 커스텀 데이터베이스 타입을 실행하는 노출된 프레임워크도 있어요. 이는 데이터베이스에 접근해야 하는 서비스가 더 이상 자격 증명을 하드코딩할 필요가 없고, Vault에서 요청하고 Vault의 리스 메커니즘을 사용해 키를 더 쉽게 교체할 수 있다는 뜻입니다. 이를 "동적 역할(dynamic roles)" 또는 "동적 시크릿(dynamic secrets)"이라고 해요.

모든 서비스가 고유한 자격 증명으로 데이터베이스에 접근하므로, 의심스러운 데이터 접근이 발견됐을 때 감사가 훨씬 쉬워집니다. SQL 사용자명으로 특정 서비스 인스턴스까지 추적할 수 있어요.

Vault는 자체 내부 폐기 시스템을 사용해 리스가 만료된 후 합리적인 시간 안에 사용자가 무효화되도록 보장합니다.

정적 역할 (Static roles)

Vault는 모든 데이터베이스 시크릿 엔진에 정적 역할(static roles) 도 지원해요. 정적 역할은 Vault 역할과 데이터베이스의 사용자명을 1:1로 매핑한 것입니다. 정적 역할에서는 Vault가 구성 가능한 기간이나 회전 일정에 따라 연결된 데이터베이스 사용자의 비밀번호를 저장하고 자동으로 회전합니다.

Create static role API로 데이터베이스 사용자가 Vault에 온보딩되면 사용자의 비밀번호가 자동으로 회전됩니다. 자동 회전은 skip_static_role_import_rotation 필드로 config 수준에서 모든 역할에 대해, 또는 skip_import_rotation 필드로 역할별로 비활성화할 수 있어요.

클라이언트가 정적 역할에 대한 자격 증명을 요청하면 Vault는 요청된 역할에 매핑된 데이터베이스 사용자의 현재 비밀번호를 반환합니다. 정적 역할에서는 적절한 Vault 정책을 가진 누구나 데이터베이스의 연결된 사용자 계정에 접근할 수 있어요.

루트 데이터베이스 자격 증명에 정적 역할을 사용하지 마세요. config/에서 Vault에 제공하는 것과 같은 루트 데이터베이스 자격 증명을 정적 역할로 관리하지 마세요.

Vault는 비밀번호 회전 시 표준 자격 증명과 루트 자격 증명을 구분하지 않아요. 루트 자격 증명을 정적 역할에 할당하면, 회전 후 config/의 비밀번호가 더 이상 유효하지 않으므로 그 데이터베이스 구성으로 관리되는 모든 동적·정적 사용자가 실패하게 됩니다.

루트 자격 증명을 회전해야 한다면 Rotate root credentials API 엔드포인트를 사용하세요.

설정 (Setup)

대부분의 시크릿 엔진은 제 기능을 하기 전에 미리 구성해야 해요. 이 단계는 보통 운영자나 구성 관리 도구가 수행합니다.

CLI — 데이터베이스 시크릿 엔진을 활성화해요.

$ vault secrets enable database
Success! Enabled the database secrets engine at: database/

기본적으로 시크릿 엔진은 엔진 이름으로 활성화돼요. 다른 경로에 활성화하려면 -path 인자를 사용하면 됩니다.

GUI — Enable a Secrets Engine 페이지를 엽니다.

Vault 인스턴스의 GUI를 엽니다.
플러그인 네임스페이스로 로그인하거나 왼쪽 메뉴 하단의 선택기에서 네임스페이스를 선택하고 다시 인증합니다.
왼쪽 메뉴에서 Secrets를 선택합니다.
하위 메뉴에서 Secrets engines를 선택합니다.
Secrets engines 페이지에서 + Enable new engine을 클릭합니다.
Databases를 선택합니다.
Enable engine을 클릭합니다.
Save를 클릭해 플러그인을 활성화합니다.

CLI — 적절한 플러그인과 연결 정보로 Vault를 구성해요.

$ vault write database/config/my-database \
    plugin_name="..." \
    connection_url="..." \
    allowed_roles="..." \
    username="..." \
    password="..." \

Vault가 사용할 전용 데이터베이스 사용자를 만드는 것을 강력히 권장합니다. 이 사용자는 데이터베이스 안의 동적·정적 사용자를 조작하는 데 사용됩니다. 이 사용자를 문서에서는 "root" 사용자라고 해요.

Vault는 여기에 지정된 사용자로 데이터베이스 자격 증명을 생성/업데이트/폐기합니다. 그 사용자는 데이터베이스의 다른 사용자에 대해 작업을 수행(생성, 자격 증명 업데이트, 삭제 등)할 수 있는 적절한 권한이 있어야 해요.

이 시크릿 엔진은 여러 데이터베이스 연결을 구성할 수 있습니다. 특정 구성 옵션에 대한 자세한 내용은 데이터베이스별 문서를 참고하세요.

GUI (연결 구성): 1. GUI 열기 → 2. 네임스페이스 로그인 → 3. Secrets 선택 → 4. Secrets engines 선택 → 5. database/ 마운트 경로 선택 → 6. Connections 탭 선택 → 7. Create connection + 클릭 → 8. Database plugin 드롭다운에서 데이터베이스 선택.

CLI — 구성 후, vault 사용자가 Vault 이외의 다른 사용자에게 접근되지 않도록 루트 사용자 비밀번호를 회전할 것을 강력히 권장합니다.

$ vault write -force database/rotate-root/my-database

이렇게 하면 이전 단계에서 지정한 사용자의 비밀번호는 더 이상 접근할 수 없게 됩니다. 그렇기 때문에 데이터베이스 사용자를 관리하기 위해 Vault가 쓸 전용 사용자를 만드는 것을 강력히 권장합니다.

GUI (역할 구성): 1. 데이터베이스 구성 세부 정보 제공 → 2. Create database 클릭해 연결 생성 → 3. 네비게이션 메뉴에서 Secret Engines 선택 → 4. database/ 마운트 경로 선택 → 5. Roles 탭 선택 → 6. Create role + 클릭.

CLI — Vault의 이름을 데이터베이스 자격 증명을 만드는 creation statements 집합에 매핑하는 역할을 구성해요.

$ vault write database/roles/my-role \
    db_name=my-database \
    creation_statements="..." \
    default_ttl="1h" \
    max_ttl="24h"
Success! Data written to: database/roles/my-role

{{username}}과 {{password}} 필드는 플러그인이 동적으로 생성된 값으로 채웁니다. 일부 플러그인에서는 {{expiration}} 필드도 지원해요.

GUI (역할): 1. Role name을 사람이 읽기 쉬운 이름으로 설정 → 2. Connection name 드롭다운에서 새 역할과 연결할 DB 연결 선택 → 3. Type of role 드롭다운에서 static 또는 dynamic 선택 → 4. 역할 구성 (정적 역할: DB 사용자명 설정, DB 비밀번호 설정(비울 수도 있음), Rotation period 설정(기본 24시간마다 회전), 초기 회전을 건너뛰려면 Rotate immediately를 끔 / 동적 역할: TTL·max TTL 만료 시간 설정(기본 TTL 1시간, max TTL 24시간), 커스텀 creation·revocation·rollback·renew 문 추가) → 5. Create role 클릭해 생성.

사용법 (Usage)

시크릿 엔진이 구성되고 사용자/머신이 적절한 권한을 가진 Vault 토큰을 가지면 자격 증명을 생성할 수 있어요.

역할 이름으로 /creds 엔드포인트를 읽어 새 자격 증명을 생성해요.

$ vault read database/creds/my-role
Key                Value
---                -----
lease_id           database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
lease_duration     1h
lease_renewable    true
password           FSREZ1S0kFsZtLat-y94
username           v-vaultuser-e2978cd0-ugp7iqI2hdlff5hfjylJ-1602537260

데이터베이스 기능

Vault 1.6부터 모든 데이터베이스가 동적 역할과 정적 역할을 지원해요. MongoDB Atlas를 제외한 모든 플러그인이 루트 사용자 자격 증명 회전을 지원합니다. MongoDB Atlas는 공개·비공개 키 쌍으로 인증하기 때문에 루트 사용자 자격 증명 회전을 지원할 수 없습니다.

데이터베이스	UI 지원	루트 자격 증명 회전	동적 역할	정적 역할	사용자명 커스터마이즈	자격 증명 유형
Cassandra	No	Yes	Yes	Yes (1.6+)	Yes (1.7+)	password
Couchbase	No	Yes	Yes	Yes	Yes (1.7+)	password
Elasticsearch	Yes (1.9+)	Yes	Yes	Yes (1.6+)	Yes (1.8+)	password
HanaDB	No	Yes (1.6+)	Yes	Yes (1.6+)	Yes (1.12+)	password
InfluxDB	No	Yes	Yes	Yes (1.6+)	Yes (1.8+)	password
MongoDB	Yes (1.7+)	Yes	Yes	Yes	Yes (1.7+)	password
MongoDB Atlas	No	No	Yes	Yes	Yes (1.8+)	password, client_certificate
MSSQL	Yes (1.8+)	Yes	Yes	Yes	Yes (1.7+)	password
MySQL/MariaDB	Yes (1.8+)	Yes	Yes	Yes	Yes (1.7+)	password, gcp_iam
Oracle	Yes (1.9+)	Yes	Yes	Yes	Yes (1.7+)	password
PostgreSQL	Yes (1.9+)	Yes	Yes	Yes	Yes (1.7+)	password, gcp_iam
Redis	No	Yes	Yes	Yes	No	password
Redis ElastiCache	No	No	No	Yes	No	password
Redshift	No	Yes	Yes	Yes	Yes (1.8+)	password
Snowflake	No	Yes	Yes	Yes	Yes (1.8+)	password(deprecated), rsa_private_key

커스텀 플러그인 (Custom plugins)

이 시크릿 엔진은 노출된 플러그인 인터페이스를 통해 커스텀 데이터베이스 타입을 실행할 수 있게 해 줍니다. 자세한 내용은 custom database plugin을 참고하세요.

자격 증명 유형 (Credential types)

데이터베이스 시스템은 다양한 인증 방식과 자격 증명 유형을 지원합니다. 데이터베이스 시크릿 엔진은 사용자명·비밀번호 외의 대안 자격 증명 관리도 지원해요. 동적·정적 역할의 credential_type 및 credential_config 파라미터는 Vault가 생성해 데이터베이스 플러그인에 제공할 자격 증명을 구성합니다. 각 데이터베이스 플러그인이 지원하는 자격 증명 유형과 사용 예는 개별 문서를 참고하세요.

정적 데이터베이스 사용자 온보딩

정적 데이터베이스 사용자가 데이터베이스 시크릿 엔진에 온보딩될 때, 기본적으로 Vault는 즉시 자동으로 데이터베이스 사용자의 비밀번호를 회전합니다. 이 즉시 회전은 온보딩 과정에 추가 운영 오버헤드를 더할 수 있으며 일부 조직에서는 어려운 일로 입증됐어요. 이런 어려움을 해결하려면 다음 옵션 중 하나 이상을 구성할 수 있습니다.

Vault 온보딩 중 정적 역할 비밀번호의 자동 회전을 비활성화합니다. 이렇게 하면 애플리케이션을 실제로 전환해 Vault에서 자격 증명을 사용하기 전에 정적 데이터베이스 사용자를 Vault에 등록할 수 있어요. 데이터베이스 연결과 관련된 모든 역할에 대해서는 skip_static_role_import_rotation으로, 역할별로는 skip_import_rotation으로 구성할 수 있습니다.
Vault 온보딩 중 초기 정적 역할 비밀번호를 설정합니다. 정적 역할의 password를 설정하면 온보딩 후 첫 회전 전에 정적 사용자의 기존 비밀번호를 가져올 수 있는 능력을 얻습니다. 이 기능은 클라이언트 애플리케이션이 Vault에서 비밀번호를 찾기 시작할 때 Vault가 준비되게 하고, 같은 정적 역할을 사용하는 여러 클라이언트가 천천히 전환하게 합니다.

DB 연결 생성 페이지와 정적 역할 생성 페이지에서 Rotate static roles immediately 토글을 끄면 역할 생성 시 초기 회전을 건너뛸 수 있어요.

정적 역할 생성 중 초기 비밀번호를 설정하려면 비밀번호를 제공하고 저장 전에 Rotate immediately를 꺼둡니다.

일정 기반 회전 (Schedule-based rotation)

기본적으로 정적 역할 자격 증명은 rotation_period를 사용해 고정된 주기로 회전해요. 대안으로 cron 스타일의 rotation_schedule을 사용해 회전이 정확히 언제 일어날지 제어하고, 선택적으로 Vault가 회전을 완료할 시간을 제한하는 rotation_window를 둘 수 있어요.

일정 기반 루트 자격 증명 회전

Enterprise에요. 적절한 Vault Enterprise 라이선스가 필요합니다.

rotation_schedule 필드를 사용해 DB Secrets 엔진의 루트 자격 증명에 대한 일정 기반 자동 회전을 구성해요. 예를 들어 다음 명령은 회전이 매주 토요일 자정(00:00)에 일어나게 설정합니다.

$ vault write database/config/my-mssql-database \
  ...
  rotation_schedule="0 * * * SAT"
  ...

예약된 루트 자격 증명 회전은 예약된 회전이 발생하도록 허용되는 rotation_window도 설정할 수 있어요. Vault는 창(window)이 만료되면 자격 증명 회전 시도를 중지합니다. 예를 들어 다음 명령은 토요일 자정에 회전하되 1시간 안에만 회전하도록 지시합니다. 실패 등으로 1시까지 회전하지 못하면 Vault는 다음 예약 회전까지 회전 시도를 중지합니다.

$ vault write database/config/my-mssql-database \
  ...
  rotation_window="1h" \
  rotation_schedule="0 * * * SAT"
...

disable_automated_rotation을 true로 설정해 루트 회전을 임시로 비활성화할 수 있어요. disable_automated_rotation 필드를 설정하면 필드가 false로 재설정될 때까지 루트 자격 증명의 회전을 방지합니다. rotation_period를 사용한다면 disable_automated_rotation을 설정하면 자격 증명 TTL도 초기화됩니다.

DB Secrets 엔진에서 루트 자격 증명 회전에 대한 자세한 내용은 Rotate Root credentials API 문서를 참고하세요.

회전 로깅 (Rotation logging)

Vault Enterprise는 성공 또는 실패한 회전마다 표준 vault.log에 로그를 남깁니다.

성공의 경우 Vault는 다음을 기록합니다.

회전된 자격 증명을 첫 번째 파라미터인 rotationID로.
다음 회전이 예상되는 시간을 expire_time으로.

실패의 경우 Vault는 rotationID를 err로 설정하고 구성된 로그 수준에 따라 추가 로그를 남길 수 있어요.

일정 기반 정적 역할 회전

데이터베이스 시크릿 엔진은 rotation_schedule 필드로 정적 역할에 대한 일정 기반 자동 자격 증명 회전 구성을 지원해요. 예:

$ vault write database/static-roles/my-role \
    db_name=my-database \
    username="vault" \
    rotation_schedule="0 * * * SAT"

이 구성은 역할의 자격 증명 회전이 토요일 00:00에 일어나도록 설정합니다.

또한 이 일정 기반 방식은 자동 회전이 발생하도록 허용되는 rotation_window를 선택적으로 구성할 수 있어요. 예:

$ vault write database/static-roles/my-role \
    db_name=my-database \
    username="vault" \
    rotation_window="1h" \
    rotation_schedule="0 * * * SAT"

이 구성은 회전이 토요일 00:00에 일어나도록 설정합니다. 1시간 rotation_window는 01:00 이후에는 회전이 발생하지 않게 합니다. 실패 등으로 이 창 안에 정적 역할 자격 증명이 회전되지 않으면 다음 예약 회전까지 회전되지 않습니다.

rotation_period와 rotation_schedule 필드는 상호 배타적이에요. 둘 중 하나는 반드시 설정해야 하지만 둘 다 설정할 수는 없어요.

Vault는 역할 이름과 회전 실패 여부를 참조해 회전을 로깅합니다. 로그는 회전이 주기 함수의 일부였는지도 나타냅니다.

실패 시 재시도 동작

예약된 회전 시도가 실패하면 Vault는 백그라운드에서 자동으로 재시도합니다. Vault는 5초마다 회전 대기열에서 보류 중인 회전을 확인하고, 실패한 회전을 고정 10초 백오프 후 재시도합니다. Vault는 재시도 횟수에 상한을 두지 않고 지수 백오프를 적용하지 않아요. Vault는 회전이 성공하거나 rotation_window가 닫힐 때까지(둘 중 먼저 일어나는 때) 고정 일정으로 회전을 계속 재시도합니다.

rotation_window가 회전 성공 전에 닫히면 Vault는 재시도를 멈추고 다음 rotation_schedule 발생(예: 다음 토요일 00:00)에 다음 시도를 예약합니다. Vault는 회전 시도가 실패했다고 해서 계정을 무효화하거나 잠그지 않으며, 자격 증명은 마지막으로 성공적으로 회전된 값을 유지합니다.

다음 예약 창을 기다리는 대신 자격 증명을 즉시 회전하려면 루트 자격 증명에는 Rotate root credentials 엔드포인트를, 정적 역할에는 Rotate static role credentials 엔드포인트를 사용하세요.

비밀번호 생성 (Password generation)

비밀번호는 Password Policies을 통해 생성됩니다. 데이터베이스는 모든 역할에 걸쳐 또는 그 데이터베이스의 개별 역할 수준에서 사용할 비밀번호 정책을 선택적으로 설정할 수 있어요. 예를 들어 vault write database/config/my-database를 호출할 때마다 my-database를 사용하는 모든 역할에 대한 비밀번호 정책을 지정할 수 있습니다. 각 데이터베이스에는 20자(대문자 1개 이상, 소문자 1개 이상, 숫자 1개 이상, 대시 문자 1개 이상)의 기본 비밀번호 정책이 정의되어 있어요.

기본 비밀번호 생성은 다음 비밀번호 정책으로 나타낼 수 있습니다.

length = 20

rule "charset" {
    charset = "abcdefghijklmnopqrstuvwxyz"
    min-chars = 1
}
rule "charset" {
    charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    min-chars = 1
}
rule "charset" {
    charset = "0123456789"
    min-chars = 1
}
rule "charset" {
    charset = "-"
    min-chars = 1
}

문자 이스케이프 비활성화 (Disable character escaping)

Vault 1.10부터 일부 시크릿 엔진에서 disable_escaping 옵션을 true로 지정해 Vault가 username과 password 필드의 특수 문자를 이스케이프하지 못하게 할 수 있어요. 이것은 MSSQL 또는 Azure SQL과 함께 쓰는 ADO 같은 일부 대체 연결 문자열 형식에 필요합니다. 이 파라미터 지원 여부는 databases secrets engine API 문서와 개별 플러그인 문서를 참고하세요.

예를 들어 비밀번호에 #나 % 같은 URL 이스케이프 문자가 포함되어 있으면, 이것이 각각 %23과 %25가 되는 대신 그대로 유지됩니다.

$ vault write database/config/my-mssql-database \
plugin_name="mssql-database-plugin" \
connection_url='server=localhost;port=1433;user id={{username}};password={{password}};database=mydb;' \
username="root" \
password='your#StrongPassword%' \
disable_escaping="true"

지원되지 않는 데이터베이스

AWS DynamoDB

Amazon Web Services(AWS) DynamoDB는 완전 관리형, 서버리스, 키-값 NoSQL 데이터베이스 서비스예요. DynamoDB는 데이터베이스 시크릿 엔진에서 지원되지 않지만, AWS 시크릿 엔진으로 DynamoDB에 접근할 수 있는 동적 자격 증명을 프로비저닝할 수 있습니다.

AWS 시크릿 엔진이 활성화·구성되었는지 확인해요.
사용자가 DynamoDB에 접근할 수 있는 필요한 권한을 가진 역할을 만들어요. 예:

$ vault write aws/roles/aws-dynamodb-read \
        credential_type=iam_user \
        policy_document=<<EOF
<POLICY_JSON>
EOF

aws-dynamodb-read 역할로 DynamoDB용 동적 자격 증명을 생성해요.

$ vault read aws/creds/aws-dynamodb-read
Key                Value
---                -----
lease_id           aws/creds/my-role/kbSnl9WSDzOXQerd8GiVh75N.DACNl
lease_duration     1h
lease_renewable    true
access_key         AKALMNOP123456
secret_key         xY4XhS3AsM3s+R33tCaybsT2XI6BVL+vF+khbbYD
security_token

Vault가 생성한 동적 자격 증명으로 DynamoDB에 접근해요. 예를 들어 AWS CLI로 연결합니다.

$ aws dynamodb list-tables --region us-east-1
{
    "TableNames": [
        "example-table"
    ]
}

튜토리얼

Vault로 데이터베이스 자격 증명 라이프사이클을 관리하는 방법을 배우려면 database credential management 튜토리얼을 참고하세요.

API

데이터베이스 시크릿 엔진은 완전한 HTTP API를 제공해요. 자세한 내용은 Database secret secrets engine API를 참고하세요.

데이터베이스 시크릿 엔진