SPIFFE 인증 메서드 구성

SPIFFE 인증 메서드 구성

각 SPIFFE 인증 메서드 인스턴스는 단일 트러스트 도메인과 연관된 트러스트 번들을 가져요. 역할 수준 구성은 SPIFFE 워크로드 ID를 Vault 토큰 정책에 매핑해요. Vault는 구성의 일부로 제공되는 트러스트 번들이나 HTTPS를 통해 원격 엔드포인트에서 가져온 트러스트 번들을 수락해요.

출처: 문서

본문

JWT-SVID 요구 사항

JWT 기반 SPIFFE SVID를 사용하려면 SPIFFE 플러그인의 패스스루 요청 헤더(passthrough request headers) 집합에 Authorization 헤더를 포함해야 해요. 그래야 클라이언트가 Authorization 헤더에 SVID를 Bearer 토큰으로 제공할 수 있어요.

Authorization: Bearer ***

SPIFFE 플러그인을 활성화하거나 튜닝할 때 -passthrough-request-headers 플래그를 사용해 허용 패스스루 헤더 집합에 Authorization을 추가하세요.

예를 들어 플러그인을 마운트할 때 vault auth enable과 함께 -passthrough-request-headers를 사용해 헤더를 구성할 수 있어요.

$ vault auth enable -passthrough-request-headers="Authorization" spiffe

또는 기존 마운트의 헤더를 구성하려면 vault auth tune과 함께 -passthrough-request-headers를 사용하세요.

$ vault auth tune -passthrough-request-headers="Authorization" spiffe

Audience 검증

JWT 기반 SPIFFE SVID를 사용할 때는 허용 audience 값 목록으로 플러그인을 구성해야 하고, 클라이언트는 적절한 값 중 하나로 audience 매개변수를 설정해야 해요.

audience 매개변수는 SVID를 검증하는 데 사용하는 배열을 정의해요.

• 워크로드가 SPIRE 같은 SPIFFE 호환 서비스에서 SVID를 요청할 때 JWT-SVID에 포함된 aud 클레임.
• auth/spiffe/config의 Vault audience 허용 목록.

Vault는 일치하는 요소가 있는 모든 클라이언트가 인증하도록 허용해요. 허용 값 목록이 비어 있으면 모든 JWT 기반 SVID를 거부해요.

SPIFFE 인증 메서드 활성화

• vault auth enable을 실행해 SPIFFE 인증 메서드를 활성화하세요.

$ vault auth enable \
  -passthrough-request-headers="Authorization" \
  spiffe

• SPIFFE 인증 메서드를 구성하세요. 예시 매개변수를 사용자 환경의 값으로 바꾸세요. endpoint_spiffe_id는 페더레이션 엔드포인트가 실제로 제시하는 SPIFFE ID와 일치해야 해요. 이 단계의 예시 값을 그대로 재사용하지 말고 배포 환경의 실제 값을 확인하세요.

$ vault write auth/spiffe/config \
  trust_domain="example.org" \
  profile="https_spiffe_bundle" \
  endpoint_url="https://spire-server.example.org:8443" \
  endpoint_spiffe_id="spiffe://example.org/spire-federation" \
  audience="vault.example.org"

• 각 워크로드 유형에 대해 역할을 구성하세요.

$ vault write auth/spiffe/role/payment-role \
  workload_id_patterns="ns/prod/sa/payment-service" \
  token_policies="payment-vault-policy" \
  token_ttl="1h"

원격 트러스트 번들 새로고침

Vault는 원격 엔드포인트에서 가져온 트러스트 번들을 캐시하고, 제공된 새로고침 힌트(refresh hint)에 따라 주기적으로 번들을 새로고침해요. 번들이 새로고침 힌트를 제공하지 않으면 기본 새로고침 간격인 1시간을 사용해요.

Vault 클러스터 내 활성 노드가 클러스터의 모든 노드를 대신해 트러스트 번들의 초기 가져오기와 이후 새로고침을 수행해요. Performance replica 클러스터의 활성 노드는 트러스트 번들을 독립적으로 가져오고 새로고침해요.

즉시 새로고침을 강제하려면 빈 페이로드로 구성 엔드포인트를 호출하세요. 가져온 트러스트 번들(마지막 새로고침 시간과 계산된 새로고침 간격 포함)에 대한 세부 정보를 보려면 구성 읽기 엔드포인트를 호출하세요.

로드 밸런서 및 프록시 고려 사항

리버스 프록시나 로드 밸런서가 Vault 앞에서 TLS를 종료한다면 다음 네 가지 조건이 모두 참이어야 해요.

• 프론트엔드 프록시가 검증된 클라이언트 인증서를 요청 헤더로 Vault에 전달해야 함.
• Vault 리스너가 프록시의 해당 헤더를 수락하고 신뢰하도록 구성되어야 함.
• 프론트엔드가 클라이언트 인증서의 전체 TLS 검증을 수행해야 함 — 검증되지 않은 인증서는 절대 통과하면 안 됨.
• 프론트엔드와 Vault 사이 연결이 상호 TLS로 보호되어야 함.

NGINX를 리버스 프록시로 구성

# nginx — terminates workload mTLS, forwards the validated cert to Vault

upstream vault_backend {
    server 127.0.0.1:8200;
}

server {
    listen 443 ssl;
    server_name vault.example.org;

    ssl_certificate     /etc/nginx/certs/proxy-server.crt;
    ssl_certificate_key /etc/nginx/certs/proxy-server.key;

    # Requirement: full TLS verification against the SPIFFE trust bundle CA
    ssl_client_certificate /etc/nginx/certs/spiffe-trust-bundle-ca.pem;
    ssl_verify_client       on;
    ssl_verify_depth        2;

    location / {
        # Requirement 1: forward the validated cert. $ssl_client_escaped_cert
        # is URL-encoded PEM — matches Vault's built-in NGINX decoder preset
        # ("URL,DER": URL-decode, then PEM to DER).
        proxy_set_header X-Client-Cert $ssl_client_escaped_cert;

        proxy_pass https://vault_backend;

        # Requirement: mTLS between nginx and Vault
        proxy_ssl_certificate         /etc/nginx/certs/proxy-to-vault-client.crt;
        proxy_ssl_certificate_key     /etc/nginx/certs/proxy-to-vault-client.key;
        proxy_ssl_trusted_certificate /etc/nginx/certs/vault-internal-ca.pem;
        proxy_ssl_verify              on;
        proxy_ssl_verify_depth        2;
        proxy_ssl_server_name         on;
    }
}

다음 Vault 리스너 구성은 NGINX 예시와 일치해요.

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/etc/vault/certs/vault-internal.crt"
  tls_key_file  = "/etc/vault/certs/vault-internal.key"

  # mTLS with nginx
  tls_client_ca_file                 = "/etc/vault/certs/proxy-client-ca.pem"
  tls_require_and_verify_client_cert = true

  # Trust the header nginx populates
  x_forwarded_for_client_cert_header          = "X-Client-Cert"
  x_forwarded_for_client_cert_header_decoders = "URL,DER"
}

x_forwarded_for_client_cert_header는 리스너 수준 설정이에요. Vault는 요청을 인증 메서드로 라우팅하기 전에 리스너에서 전달된 인증서를 구문 분석하므로, 이 설정은 cert와 동일한 방식으로 spiffe에 적용돼요. 리스너 구성만 신뢰하지 말고, 헤더가 채워진 실제 로그인 요청이 Vault에 도달하는 전체 경로를 종단 간 테스트하세요. 구성된 디코더 형식과 일치하지 않는 형식으로 헤더를 전달하는 프록시는 인증 메서드별 오류가 아니라 리스너에서 실패해요.

SPIFFE 플러그인 API

SPIFFE 인증 메서드는 완전한 HTTP API를 제공해요. 엔드포인트 세부 정보와 요청 매개변수는 SPIFFE 인증 메서드 API 레퍼런스를 참조하세요.

Terraform

vault_auth_backend 리소스로 SPIFFE 인증 메서드를 활성화하고 vault_spiffe_auth_backend_config로 구성을 관리할 수 있어요.

• Vault auth backend 리소스
• Vault SPIFFE auth backend config 리소스
• Vault SPIFFE auth backend role 리소스

더 알아보기 (Learn more)

• SPIRE로 SPIFFE 인증 메서드를 사용해 Vault에 인증하기 — 완전한 동작 예제