SAML 인증을 통한 SSO 설정

개요

Fess 에서는 SAML（Security Assertion Markup Language）2.0을 사용한 싱글 사인온（SSO）인증을 지원합니다. SAML 인증을 사용하면 IdP（Identity Provider）에서 인증된 사용자 정보를 Fess 에 연동하고, 역할 기반 검색과 결합하여 사용자의 권한에 따른 검색 결과 구분이 가능해집니다.

SAML 인증의 구조

SAML 인증에서는 Fess 가 SP（Service Provider）로 동작하여 외부 IdP와 연동하여 인증을 수행합니다.

1. 사용자가 Fess 의 SSO 엔드포인트（/sso/）에 접근

2. Fess 가 IdP에 인증 요청을 리다이렉트

3. 사용자가 IdP에서 인증 실행

4. IdP가 SAML 어서션을 Fess 에 전송

5. Fess 가 어서션을 검증하고 사용자를 로그인

역할 기반 검색과의 연동에 대해서는 역할 기반 검색 설정 을 참조하십시오.

전제 조건

SAML 인증을 설정하기 전에 다음 전제 조건을 확인하십시오.

• Fess 15.7 이상이 설치되어 있을 것

• SAML 2.0 대응 IdP（Identity Provider）를 사용할 수 있을 것

• Fess 가 HTTPS로 접근 가능할 것（운영 환경에서는 필수）

• IdP 측에서 Fess 를 SP로 등록할 수 있는 권한이 있을 것

지원 IdP의 예:

• Microsoft Entra ID（Azure AD）

• Okta

• Google Workspace

• Keycloak

• OneLogin

• 기타 SAML 2.0 대응 IdP

기본 설정

SSO 기능 활성화

SAML 인증을 활성화하려면 app/WEB-INF/conf/system.properties 에 다음 설정을 추가합니다.

sso.type=saml

참고

sso.type 및 기본적인 SAML 설정（IdP 정보, SP 정보, 사용자 속성 매핑）은 관리 화면의 「시스템 > 전체」 페이지에서도 설정·변경할 수 있습니다. 관리 화면에서 변경한 설정은 system.properties 에 저장되며, 재시작 후에도 유지됩니다. 단, 서명·암호화 등의 보안 설정이나 SP 인증서·비밀 키는 관리 화면에서 설정할 수 없으므로 system.properties 에 직접 기술하십시오.

SP（Service Provider）설정

Fess 를 SP로 설정하려면 SP Base URL을 지정합니다.

프로퍼티	설명	기본값
saml.sp.base.url	SP의 베이스 URL	http://localhost:8080

참고

saml.sp.base.url 의 기본값은 http://localhost:8080 입니다. 검증 환경 이외에서는 반드시 Fess 에 외부에서 접근할 때의 URL（운영 환경에서는 HTTPS）을 설정하십시오.

이 설정에 의해 다음 엔드포인트가 자동으로 구성됩니다.

• Entity ID: {saml.sp.base.url}/sso/metadata

• ACS URL: {saml.sp.base.url}/sso/

• SLO URL: {saml.sp.base.url}/sso/logout

설정 예:

saml.sp.base.url=https://fess.example.com

개별 URL 설정

일반적으로 saml.sp.base.url 을 설정하면 각 엔드포인트 URL이 자동으로 구성되지만, 필요에 따라 다음 프로퍼티로 개별 URL을 명시적으로 지정하여 덮어쓸 수도 있습니다.

프로퍼티	설명	기본값
saml.sp.entityid	SP의 Entity ID	{saml.sp.base.url}/sso/metadata
saml.sp.assertion_consumer_service.url	Assertion Consumer Service URL	{saml.sp.base.url}/sso/
saml.sp.single_logout_service.url	Single Logout Service URL	{saml.sp.base.url}/sso/logout

IdP（Identity Provider）설정

IdP에서 취득한 정보를 설정합니다.

프로퍼티	설명	기본값
saml.idp.entityid	IdP의 Entity ID	（필수）
saml.idp.single_sign_on_service.url	IdP의 SSO 서비스 URL	（필수）
saml.idp.x509cert	IdP의 서명용 X.509 인증서（Base64 인코딩, 줄 바꿈 없음）	（필수）
saml.idp.single_logout_service.url	IdP의 SLO 서비스 URL	（선택 사항）

참고

saml.idp.x509cert 에는 인증서의 Base64 인코딩된 내용을 줄 바꿈 없이 1행으로 지정합니다. -----BEGIN CERTIFICATE----- 와 -----END CERTIFICATE----- 행은 포함하지 마십시오.

SP 메타데이터 취득

Fess 를 시작하면 /sso/metadata 엔드포인트에서 SP 메타데이터를 XML 형식으로 취득할 수 있습니다.

https://fess.example.com/sso/metadata

이 메타데이터를 IdP에 임포트하거나, 메타데이터의 내용을 참고하여 IdP 측에서 SP를 수동으로 등록하십시오.

참고

메타데이터를 취득하려면 먼저 기본적인 SAML 설정（sso.type=saml 과 saml.sp.base.url）을 완료하고 Fess 를 시작해 두어야 합니다.

IdP 측 설정

IdP 측에서 Fess 를 SP로 등록할 때 다음 정보를 설정합니다.

설정 항목	설정값
ACS URL / Reply URL	https://<Fess의 호스트>/sso/
Entity ID / Audience URI	https://<Fess의 호스트>/sso/metadata
Name ID Format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress （권장）

IdP에서 취득하는 정보

IdP의 설정 화면 또는 메타데이터에서 다음 정보를 취득하여 Fess 의 설정에 사용합니다.

• IdP Entity ID: IdP를 식별하기 위한 URI

• SSO URL（HTTP-Redirect）: 싱글 사인온의 엔드포인트 URL

• X.509 인증서: SAML 어서션의 서명 검증에 사용하는 공개 키 인증서

사용자 속성 매핑

SAML 어서션에서 취득한 사용자 속성을 Fess 의 그룹이나 역할에 매핑할 수 있습니다.

그룹 속성 설정

프로퍼티	설명	기본값
saml.attribute.group.name	그룹 정보를 포함하는 속성명	memberOf
saml.default.groups	기본 그룹（쉼표로 구분）	（없음）

설정 예:

saml.attribute.group.name=groups
saml.default.groups=user

역할 속성 설정

프로퍼티	설명	기본값
saml.attribute.role.name	역할 정보를 포함하는 속성명	（없음）
saml.default.roles	기본 역할（쉼표로 구분）	（없음）

설정 예:

saml.attribute.role.name=roles
saml.default.roles=viewer

참고

IdP에서 속성을 취득할 수 없는 경우 기본값이 사용됩니다. 역할 기반 검색을 사용하는 경우 적절한 그룹 또는 역할을 설정하십시오.

보안 설정

운영 환경에서는 다음 보안 설정을 활성화하는 것을 권장합니다.

서명 설정

프로퍼티	설명	기본값
saml.security.authnrequest_signed	인증 요청에 서명한다	false
saml.security.want_messages_signed	메시지의 서명을 요구한다	false
saml.security.want_assertions_signed	어서션의 서명을 요구한다	false
saml.security.logoutrequest_signed	로그아웃 요청에 서명한다	false
saml.security.logoutresponse_signed	로그아웃 응답에 서명한다	false

경고

기본값에서는 보안 기능이 비활성화되어 있습니다. 운영 환경에서는 최소한 saml.security.want_assertions_signed=true 를 설정하도록 강력히 권장합니다.

암호화 설정

프로퍼티	설명	기본값
saml.security.want_assertions_encrypted	어서션의 암호화를 요구한다	false
saml.security.want_nameid_encrypted	NameID의 암호화를 요구한다	false

SP 인증서 및 비밀 키 설정

SP 측에서 인증 요청이나 로그아웃 메시지에 서명하는 경우（saml.security.authnrequest_signed 등）, 또는 어서션이나 NameID의 암호화를 요구하는 경우（saml.security.want_assertions_encrypted 등）는, SP의 비밀 키와 X.509 인증서를 설정해야 합니다.

프로퍼티	설명	기본값
saml.sp.x509cert	SP의 X.509 인증서（Base64 인코딩, 줄 바꿈 없음）	（빈 문자열）
saml.sp.privatekey	SP의 비밀 키（Base64 인코딩, 줄 바꿈 없음）	（빈 문자열）

참고

saml.sp.x509cert 와 saml.sp.privatekey 에는 saml.idp.x509cert 와 마찬가지로, Base64 인코딩된 내용을 줄 바꿈 없이 1행으로 지정합니다（-----BEGIN ...----- 와 -----END ...----- 행은 포함하지 않습니다）. 서명·암호화를 활성화하는 경우 SP 인증서를 IdP 측에도 등록하십시오. SP 인증서는 /sso/metadata 의 SP 메타데이터에 포함되어 공개됩니다.

기타 보안 설정

프로퍼티	설명	기본값
saml.strict	엄격 모드（검증을 엄격하게 수행）	true
saml.security.want_xml_validation	메시지의 XML 스키마 검증을 수행한다	true
saml.security.signature_algorithm	서명 알고리즘	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
saml.security.requested_authncontext	요구하는 인증 컨텍스트	urn:oasis:names:tc:SAML:2.0:ac:classes:Password
saml.sp.nameidformat	NameID 형식	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

참고

Fess 는 내부적으로 SAML 라이브러리（java-saml）를 사용하며, saml. 로 시작하는 프로퍼티는 라이브러리의 대응하는 설정（onelogin.saml2. 프리픽스）에 매핑됩니다. 이 때문에 여기서 소개한 것 외에도, 바인딩（saml.sp.assertion_consumer_service.binding 등）, 조직 정보（saml.organization.*）, 연락처 정보（saml.contacts.*）와 같은 상세 설정을 system.properties 에 지정할 수 있습니다.

설정 예

최소 구성（검증 환경용）

다음은 검증 환경에서 동작을 확인하기 위한 최소한의 설정 예입니다.

# SSO 활성화
sso.type=saml

# SP 설정
saml.sp.base.url=https://fess.example.com

# IdP 설정（IdP의 관리 화면에서 취득한 값을 설정）
saml.idp.entityid=https://idp.example.com/saml/metadata
saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso
saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64 인코딩된 인증서）

# 기본 그룹
saml.default.groups=user

권장 구성（운영 환경용）

다음은 운영 환경에서 사용하기 위한 권장 설정 예입니다.

# SSO 활성화
sso.type=saml

# SP 설정
saml.sp.base.url=https://fess.example.com

# IdP 설정
saml.idp.entityid=https://idp.example.com/saml/metadata
saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso
saml.idp.single_logout_service.url=https://idp.example.com/saml/logout
saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...（Base64 인코딩된 인증서）

# 사용자 속성 매핑
saml.attribute.group.name=groups
saml.attribute.role.name=roles
saml.default.groups=user

# 보안 설정（운영 환경에서는 활성화 권장）
saml.security.want_assertions_signed=true
saml.security.want_messages_signed=true

문제 해결

자주 발생하는 문제와 해결 방법

인증 후 Fess 로 돌아올 수 없음

• IdP 측의 ACS URL이 올바르게 설정되어 있는지 확인하십시오

• saml.sp.base.url 의 값이 IdP 측의 설정과 일치하는지 확인하십시오

서명 검증 오류

• IdP의 인증서가 올바르게 설정되어 있는지 확인하십시오

• 인증서의 유효 기간이 만료되지 않았는지 확인하십시오

• 인증서는 Base64 인코딩된 내용만 줄 바꿈 없이 설정하십시오

사용자의 그룹·역할이 반영되지 않음

• IdP 측에서 속성（Attribute）이 올바르게 설정되어 있는지 확인하십시오

• saml.attribute.group.name 의 값이 IdP에서 전송되는 속성명과 일치하는지 확인하십시오

• SAML 어서션의 내용을 확인하려면 디버그 모드를 활성화하십시오

디버그 설정

문제를 조사할 때는 다음 설정으로 디버그 모드를 활성화할 수 있습니다.

saml.debug=true

saml.debug=true 를 설정하면 SAML 인증에 실패했을 때의 상세한 이유가 로그에 출력됩니다.

또한 app/WEB-INF/classes/log4j2.xml 에 다음 로거를 추가하면 SAML 관련 상세 로그를 출력할 수 있습니다.

<Logger name="org.codelibs.fess.sso.saml" level="DEBUG"/>

참고 정보

• 역할 기반 검색 설정 - 역할 기반 검색 설정에 대하여

• OpenID Connect를 통한 SSO 설정 - OpenID Connect에 의한 SSO 설정에 대하여

• Microsoft Entra ID를 이용한 SSO 설정 - Microsoft Entra ID 전용 SSO 설정에 대하여