SAML authentication

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

SAML 인증

Security 플러그인은 SAML 싱글 사인온을 통한 사용자 인증을 지원해요. Security 플러그인은 SAML 2.0 프로토콜의 웹 브라우저 SSO 프로파일을 구현해요.

이 프로파일은 웹 브라우저에서 사용하기 위한 것이에요. Security 플러그인에서 사용자를 인증하는 범용적인 방법은 아니기 때문에, 주요 사용 사례는 OpenSearch Dashboards 싱글 사인온을 지원하는 거예요.

Docker 예제

SAML을 OpenSearch Dashboards와 함께 사용하는 방법을 이해하는 데 도움이 되는, 완전히 동작하는 예제를 제공해요.

demos 저장소의 saml-demo 브랜치에 방문해서 원하는 폴더에 다운로드하세요. GitHub 사용법이 익숙하지 않다면 OpenSearch 온보딩 가이드에서 안내를 확인하세요.
demo 폴더로 이동하세요:
```
$ cd <path-to-demos-folder>/demo
```
필요에 따라 다음 파일들을 검토하세요:
- .env:
  - 사용할 OpenSearch 및 OpenSearch Dashboards 버전을 정의해요. 기본값은 최신 버전({{site.opensearch_major_minor_version}})이에요.
  - 2.12 이상 버전에서 필요한 OPENSEARCH_INITIAL_ADMIN_PASSWORD 변수를 정의해요.
- ./custom-config/opensearch_dashboards.yml: 기본 opensearch_dashboards.yml 파일을 위한 SAML 설정을 포함해요.
- ./custom-config/config.yml: 인증을 위한 SAML을 구성해요.
- docker-compose.yml: OpenSearch 서버 노드, OpenSearch Dashboards 서버 노드, SAML 서버 노드를 정의해요.
- ./saml/config/authsources.php: 이 SAML 도메인으로 인증할 수 있는 사용자 목록이 담겨 있어요.
명령줄에서 다음을 실행하세요:
```
$ docker compose up.
```
http://localhost:5601{:target='_blank'}에서 OpenSearch Dashboards에 접속하세요.
Log in with single sign-on을 선택하세요. 그러면 SAML 로그인 페이지로 리디렉션돼요.
./saml/config/authsources.php에 정의된 사용자로 OpenSearch Dashboards에 로그인하세요(예: 비밀번호가 user1pass인 user1).
로그인한 후에는 화면 오른쪽 위에 표시되는 사용자 ID가 SAML 서버의 ./saml/config/authsources.php에 정의된 사용자의 NameID 속성과 같다는 점에 유의하세요(즉, user1의 경우 saml-test예요).
SAML 서버를 살펴보고 싶다면 docker ps를 실행해서 컨테이너 ID를 찾은 다음 docker exec -it <container-id> /bin/bash를 실행하세요.

특히 /var/www/simplesamlphp/config/와 /var/www/simplesamlphp/metadata/ 디렉터리의 내용을 검토해 보면 도움이 될 거예요.

SAML 활성화

인증에 SAML을 사용하려면 config/opensearch-security/config.yml의 authc 섹션에 해당하는 인증 도메인을 구성해야 해요. SAML은 오직 HTTP 레이어에서만 동작하기 때문에 authentication_backend가 전혀 필요 없으며 noop으로 설정할 수 있어요. 이 장에 나오는 모든 SAML 관련 구성 옵션은 SAML HTTP 인증기의 config 섹션에 배치하세요:

_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    authc:
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            idp:
              metadata_file: okta.xml
              ...
        authentication_backend:
          type: noop

config.yml에서 SAML을 구성하고 나면 OpenSearch Dashboards에서 활성화하는 것도 반드시 해야 해요.

여러 인증 도메인 실행하기

SAML 없이 OpenSearch에 대한 API 접근을 지원하려면 LDAP이나 내부 사용자 데이터베이스 같은 인증 도메인을 최소 하나 더 추가하는 것을 추천해요. OpenSearch Dashboards와 내부 OpenSearch Dashboards 서버 사용자를 위해서는 기본 인증을 지원하는 다른 인증 도메인도 반드시 추가해야 해요. 이 인증 도메인은 체인에서 가장 먼저 배치해야 하고, challenge 플래그는 false로 설정해야 해요:

_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    authc:
      basic_internal_auth_domain:
        http_enabled: true
        transport_enabled: true
        order: 0
        http_authenticator:
          type: basic
          challenge: false
        authentication_backend:
          type: internal
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            ...
        authentication_backend:
          type: noop

Identity provider 메타데이터

SAML identity provider(IdP)는 IdP의 기능과 구성을 설명하는 SAML 2.0 메타데이터 파일을 제공해요. Security 플러그인은 URL이나 파일에서 IdP 메타데이터를 읽을 수 있어요. 무엇을 선택할지는 사용 중인 IdP와 여러분의 선호에 따라 달라져요. SAML 2.0 메타데이터 파일은 필수예요.

이름	설명
`idp.metadata_file`	IdP의 SAML 2.0 메타데이터 파일 경로예요. 메타데이터 파일은 OpenSearch의 `config` 디렉터리에 배치하세요. 경로는 `config` 디렉터리를 기준으로 상대적으로 지정해야 해요. `idp.metadata_url`이 설정되어 있지 않으면 필수예요.
`idp.metadata_url`	IdP의 SAML 2.0 메타데이터 URL이에요. `idp.metadata_file`이 설정되어 있지 않으면 필수예요.

IdP 및 서비스 제공자 entity ID

entity ID는 IdP나 서비스 제공자(SP) 같은 SAML 엔터티의 전역적으로 고유한 이름이에요. IdP entity ID는 보통 IdP가 제공해요. SP entity ID는 IdP에서 구성한 애플리케이션이나 클라이언트의 이름이에요. OpenSearch Dashboards용 새 애플리케이션을 추가하고 OpenSearch Dashboards 설치의 URL을 SP entity ID로 사용하는 것을 추천해요.

이름	설명
`idp.entity_id`	IdP의 entity ID예요. 필수예요.
`sp.entity_id`	서비스 제공자의 entity ID예요. 필수예요.

JWT 검증을 위한 시간 편차 보정

가끔 인증 서버와 OpenSearch 노드 사이의 시계가 완벽하게 동기화되지 않는 경우가 있어요. 이런 경우에는 몇 초의 차이만 있어도 JSON Web Token(JWT)을 발급하거나 수신하는 시스템이 nbf(not before) 및 exp(expiration) 클레임을 검증하다가 시간 편차 때문에 사용자 인증에 실패할 수 있어요.

기본적으로 OpenSearch Security는 서버 시계 시간 사이에 생길 수 있는 어긋남을 보정하기 위해 30초의 여유를 둬요. 이 기능에 사용자 지정 값을 설정해 기본값을 재정의하려면 config.yml에 jwt_clock_skew_tolerance_seconds 설정을 추가하면 돼요.

http_authenticator:
  type: saml
  challenge: true
  config:
    idp:
      metadata_file: okta.xml
    jwt_clock_skew_tolerance_seconds: 20

OpenSearch Dashboards 설정

웹 브라우저 SSO 프로파일은 HTTP GET이나 POST를 통해 정보를 교환해요. 예를 들어 IdP에 로그인하고 나면 IdP는 SAML 응답이 담긴 HTTP POST를 OpenSearch Dashboards로 다시 보내요. HTTP 요청이 전송되는 OpenSearch Dashboards 설치의 base URL을 반드시 구성해야 해요.

이름	설명
`kibana_url`	OpenSearch Dashboards base URL이에요. 필수예요.

사용자 이름 및 역할 속성

subject(예: 사용자 이름)는 보통 SAML 응답의 NameID 요소에 저장돼요:

<saml2:Subject>
  <saml2:NameID>admin</saml2:NameID>
  ...
</saml2:Subject>

IdP가 SAML 2.0 사양을 준수한다면 특별히 설정할 필요가 없어요. IdP가 다른 요소 이름을 사용한다면 해당 이름을 명시적으로 지정할 수도 있어요.

역할 속성은 선택 사항이에요. 하지만 대부분의 IdP는 SAML assertion에 역할을 추가하도록 구성할 수도 있어요. 역할이 있다면 [역할 매핑]({{site.url}}{{site.baseurl}}/security/access-control/index/#

OpenSearch Dashboards 설정

SAML 관련 설정은 대부분 Security 플러그인에서 이루어지기 때문에, 다음을 추가해서 opensearch_dashboards.yml에서 SAML을 활성화하기만 하면 돼요:

opensearch_security.auth.type: "saml"

또한 SAML 어설션을 검증하는 OpenSearch Dashboards 엔드포인트를 허용 목록에 추가해야 해요:

server.xsrf.allowlist: ["/_opendistro/_security/saml/acs"]

logout POST binding을 사용한다면 logout 엔드포인트도 허용 목록에 추가해야 해요:

server.xsrf.allowlist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"]

Dashboards 로그인 창에서 SAML을 다른 인증 방식과 함께 사용하는 방법은 로그인 옵션 구성하기를 참고하세요. {: .note }

추가 쿠키를 사용한 세션 관리

세션 관리를 개선하기 위해---특히 여러 역할이 할당된 사용자의 경우---Dashboards는 쿠키 페이로드를 여러 개의 쿠키로 분할하고, 수신할 때 페이로드를 다시 결합하는 옵션을 제공해요. 이를 통해 크기가 큰 SAML 어설션이 쿠키별 크기 제한을 초과하는 것을 방지할 수 있어요. 다음 예시의 두 설정을 사용하면 추가 쿠키의 접두사 이름을 지정하고 개수를 정할 수 있어요. 이 설정들은 opensearch_dashboards.yml 파일에 추가해요. 추가 쿠키의 기본 개수는 3개예요:

opensearch_security.saml.extra_storage.cookie_prefix: security_authentication_saml
opensearch_security.saml.extra_storage.additional_cookies: 3

추가 쿠키 개수를 줄이면 변경 전에 사용 중이던 쿠키 일부가 더 이상 동작하지 않을 수 있다는 점에 유의하세요. 추가 쿠키 개수를 고정으로 정해 두고 이후에는 설정을 바꾸지 않는 것을 권장해요.

IdP에서 받은 ID 토큰이 특히 크면 OpenSearch가 HTTP 헤더가 너무 크다는 인증 오류를 서버 로그에 기록할 수 있어요. 이런 경우 opensearch.yml 파일에서 http.max_header_size 설정 값을 늘리면 돼요. {: .tip }

IdP 시작 SSO

IdP 시작 SSO를 사용하려면 IdP의 Assertion Consumer Service 엔드포인트를 다음과 같이 설정하세요:

/_opendistro/_security/saml/acs/idpinitiated

그런 다음 이 엔드포인트를 opensearch_dashboards.yml의 server.xsrf.allowlist에 추가하세요:

server.xsrf.allowlist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"]

문제 해결

일반적인 SAML 설정 문제에 대한 해결 방법은 SAML 문제 해결을 참고하세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/security/authentication-backends/saml/

SAML authentication

본문

SAML 인증

Docker 예제

SAML 활성화

여러 인증 도메인 실행하기

Identity provider 메타데이터

IdP 및 서비스 제공자 entity ID

JWT 검증을 위한 시간 편차 보정

OpenSearch Dashboards 설정

사용자 이름 및 역할 속성

OpenSearch Dashboards 설정

추가 쿠키를 사용한 세션 관리

IdP 시작 SSO

문제 해결

더 알아보기 (Learn more)

함께 읽는 실무 이야기