API 키 기반 접근 제어 — role_descriptors와 '생성 시점 권한 스냅샷'
Elasticsearch ES|QL 및 API 키 기반 접근 제어 공식 문서 종합 (웹 리서치, 2026) — Elastic 공식 문서(explore-analyze/query-filter/languages/esql, deploy-manage/api-keys/elasticsearch-api-keys, security-api-create-api-key) Elastic 공식 문서 Elasticsearch API keys 및 Create API key API
이 모듈을 다 읽으면
- API 키의 실질 권한이 role_descriptors와 소유자 권한의 조합으로 결정된다는 것을 설명할 수 있다
- API 키가 사용자 인증(비밀번호)과 근본적으로 다른 용도로 쓰이는 이유를 설명할 수 있다
서비스 간 인증이나 외부 애플리케이션 접근처럼 사용자 계정을 직접 공유하기 부적절한 상황에서 쓰는 API 키가, 어떻게 세밀한 권한 범위를 갖고 발급되며 왜 발급 이후 소유자의 권한 변경과 독립적인지를 정리한다.
권한 범위는 두 가지의 조합 — role_descriptors와 '발급 시점 스냅샷'
API 키를 생성할 때 role_descriptors로 그 키에 부여할 권한(클러스터 권한, 인덱스별 권한 등)을 명시적으로 지정할 수 있다. 그런데 이 키의 실제 접근 범위는 role_descriptors만으로 정해지는 게 아니라, '키를 발급한 사용자가 그 순간에 실제로 가지고 있던 권한의 스냅샷'과 함께 적용된다 — 즉 아무리 role_descriptors에 넓은 권한을 명시해도, 발급자 본인이 애초에 갖지 못한 권한을 키에 부여할 수는 없다. 이는 '최소 권한을 명시했지만 발급자가 그보다 더 많은 권한을 갖고 있어서 실제로는 더 넓게 동작하는' 실수를 막는 안전장치로 볼 수 있다.
핵심 포인트
- API 키의 실제 권한 = role_descriptors에 명시한 권한 + 발급자의 발급 시점 권한 스냅샷의 조합 — 발급자가 못 가진 권한을 키에 부여할 수 없음
- 발급자 본인의 권한을 넘어서는 권한을 실수로 부여하는 것을 막는 안전장치로 기능
왜 사용자 인증과 다른가 — 서비스 간 인증과 세밀한 폐기
API 키는 사용자명/비밀번호 기반 인증과 달리, 애플리케이션·서비스가 사람 계정을 거치지 않고 Elasticsearch에 접근하도록 설계된 토큰 기반 인증 수단이다. 사용자 비밀번호를 서비스 설정 파일에 박아 넣는 대신, 그 서비스 전용으로 범위가 제한된 API 키를 발급해 쓸 수 있고, 문제가 생기면 사용자 비밀번호 전체를 바꿀 필요 없이 그 키 하나만 개별적으로 폐기(삭제)하면 된다 — 여러 서비스가 같은 사용자 자격증명을 공유하다 하나가 유출됐을 때 전체를 다 바꿔야 하는 상황을 피할 수 있다는 게 실무적 이점이다.
핵심 포인트
- API 키는 사람 계정의 비밀번호 대신, 서비스별로 범위가 제한된 토큰을 발급해 서비스 간 인증에 쓰기 위한 수단
- 문제 발생 시 사용자 비밀번호 전체를 바꾸지 않고 해당 키만 개별 폐기 가능 — 자격증명 공유로 인한 연쇄 영향을 피함
만료 설정과 크로스 클러스터 키
API 키는 기본적으로 만료되지 않지만, 보안 모범 사례로는 발급 시 유효기간(expiry)을 명시적으로 설정해 유한한 수명을 갖게 하는 것이 권장된다. 또한 크로스 클러스터 검색·복제처럼 다른 클러스터가 이 클러스터에 접속할 때도 전용 크로스 클러스터 API 키로 '다른 클러스터가 접근할 수 있는 인덱스 범위'를 별도로 세밀하게 제어할 수 있다 — 클러스터 간 신뢰 관계에도 동일한 최소 권한 원칙을 적용하는 것이다.
핵심 포인트
- API 키는 기본 무제한 만료지만 보안 모범 사례로 유효기간을 명시적으로 설정하는 것이 권장됨
- 크로스 클러스터 검색/복제용 API 키로 다른 클러스터가 접근 가능한 인덱스 범위를 별도로 세밀하게 제어 가능