Sandfly는 SAMLv2를 사용하여 single sign-on (SSO)을 지원합니다. Sandfly SAML 구현은 다음과 같은 조건을 만족하는 SAML Identity Provider와 함께 작동합니다:

<samlp:AuthnRequest> 메시지에 대해 HTTP-Redirect 바인딩을 허용합니다.
<samlp:Response> 메시지에 대해 HTTP-POST 바인딩을 사용합니다.
Sandfly에서 username으로 사용될 수 있는 username이나 email 주소와 같이 인증된 사용자의 NameID에 대한 유용한 값을 포함합니다. Sandfly는 <samlp:AuthnRequest> 메시지에 <samlp:NameIDPolicy> 요소를 포함하지 않습니다. Identity Provider는 고객이 선택한 NameID를 강제하도록 구성되어야 합니다.
Identity Provider에서 요구하는 경우 Sandfly는 생성하는 <samlp:AuthnRequest> 메시지에 선택적으로 서명할 수 있습니다.

📘
INFO: Upgrade Feature - Single Sign-On
Single Sign-On (SSO)을 구성하고 사용하는 기능은 업그레이드 요금제가 필요합니다. 자세한 내용은 https://www.sandflysecurity.com/get-sandfly/를 참조하세요.

Identity Provider 구성

Identity Provider 내에서 새 Service Provider 구성을 생성합니다:

You may assign an arbitrary Service Provider ID to Sandfly.
Make sure the HTTP-POST binding is used for all responses.
NameID가 유용한 값(username 또는 email 주소)으로 강제되도록 확인합니다.
Sandfly에 대한 redirect URL을 허용된 URL로 추가합니다: https://**<sandfly-server-host>**/sandflysso/acs
- <sandfly-server-host>가 config.server.json 파일의 server.api.hostname에 구성된 값과 동일한 값을 사용하도록 확인하세요. 그렇지 않으면 redirection이 제대로 작동하지 않을 가능성이 높습니다.

Identity Provider가 서명된 요청을 필요로 하는 경우, Sandfly용 X.509 인증서와 개인 키를 생성하세요. 이들은 PEM 형식이어야 합니다.

예시 - Keycloak

예를 들어 Keycloak을 Identity Provider로 사용하는 경우 Sandfly에 중요한 설정이 아래에 강조표시되어 있습니다:

예시 - Google Workspace

Google Workspace를 Identity Provider로 사용하는 경우의 핵심 필드에 대한 또 다른 예시입니다. 이 경우 redirect URL은 "ACS URL"이라고 하며, Google 계정에는 username이 없기 때문에 Name ID를 사용자의 email 주소로 설정합니다:

Important Google Workspace Example Settings

Sandfly 구성

SAML SSO를 구성하려면 사이드바의 Settings 섹션을 확장하고 Server Configuration으로 이동한 다음 SSO Configuration 탭을 클릭합니다. 구성 페이지에서 다음과 같은 필수 값들을 제공합니다:

SAML Enabled - SAML 설정에 액세스할 수 있도록 true로 설정합니다.
IDP Entity ID - 이것은 Identity Provider의 고유 ID입니다. 이 값은 Identity Provider의 SAML 메타데이터 XML에서 <md:EntityDescriptor> 태그의 entityID 속성에서 찾을 수 있습니다. URL이나 일반 문자열로 나타날 수 있습니다.
IDP Certificate - 이것은 Identity Provider의 공개 키를 포함하는 인증서입니다. Sandfly는 이 인증서를 사용하여 인증 요청에 대한 IDP의 응답 서명을 확인합니다. 이 값은 Identity Provider의 SAML 메타데이터 XML에서 <ds:X509Certificate> 태그에서 찾을 수 있으며, 또는 PEM 형식 인증서의 내용을 붙여넣을 수 있습니다 (예: -----BEGIN CERTIFICATE-----로 시작).
IDP SSO Binding URL - 이것은 Sandfly가 인증 요청과 함께 클라이언트 브라우저를 리다이렉트하는 URL입니다. 이 값은 Identity Provider의 SAML 메타데이터 XML에서 Binding 속성이 "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"와 같은 <md:SingleSignOnService> 태그의 Location 속성에서 찾을 수 있습니다.
SP Entity ID - 이것은 Sandfly에 대해 설정하는 entity ID입니다 (위의 스크린샷에서 Identity Provider 구성에 Sandfly를 프로비저닝할 때 "sandfly"를 선택했지만, IDP 구성과 Sandfly의 SSO 구성 간에 일치하는 한 원하는 문자열을 사용할 수 있습니다).
Request Signature Method - IDP가 Service Provider가 인증 요청에 서명하도록 요구하는 경우 Sandfly가 사용할 서명 알고리즘을 선택합니다. 서명 알고리즘을 선택하면 SP Certificate와 SP Private Key 필드가 나타나고 필수가 됩니다. 이것들은 PEM 형식 인증서와 개인 키를 포함해야 합니다 (예: -----BEGIN CERTIFICATE-----와 -----BEGIN PRIVATE KEY-----로 시작).

SSO 사용자 추가

SSO가 활성화된 후 SSO를 통해 로그인할 사용자를 Sandfly에 추가할 수 있습니다. SSO 사용자를 추가하려면 Settings > Manage Users로 이동한 다음 Add 버튼을 클릭합니다. User Type을 "SSO"로 설정하고 필수 사용자 세부 정보를 입력합니다. username이 Identity Provider의 값과 일치하는지 확인하세요. 위의 Keycloak 구성 예시를 사용하는 경우 username이 되고, 위의 Google 구성 예시를 사용하는 경우 email 주소가 됩니다.

❗️
중요: Username 일치
username이 Identity Provider의 값과 일치하도록 하세요.

SSO로 로그인

자세한 내용은 Login Screen 사용자 인터페이스 도큐먼트를 참조하세요.

⚠️
경고: SSO 서비스 장애의 영향
SSO 계정은 Sandfly에서 User Type을 "SSO"로 설정하여 생성되어야 합니다. 이것은 Sandfly 서버에만 존재하는 "Local" 계정과 구분됩니다. 이러한 사용자 유형 구분 때문에 어떤 이유로든 SSO가 손실되어도 로컬 사용자의 인증에는 영향을 주지 않습니다.