SAML 싱글 사인온: 기술 문서

Security Assertion Markup Language(SAML)은 OneLogin 같은 ID 공급자(IdP)가 Mattermost 같은 서비스 공급자(SP)에 인가 자격 증명을 전달할 수 있게 하는 개방형 표준입니다.

더 간단히 말하면, 하나의 자격 증명으로 여러 사이트에 로그인할 수 있다는 뜻입니다. SAML ID 공급자 계정이 있으면 같은 계정으로 Mattermost와 다른 사이트에 안전하게 로그인할 수 있습니다.

가장 큰 이점은 관리자가 SAML ID 공급자 자격 증명으로 사용자가 접근할 수 있는 사이트를 통제함으로써 사용자 관리를 중앙화할 수 있다는 점입니다.

Mattermost는 싱글 사인온 URL로 IdP 메타데이터 URL을 생성하여, 단일 메타데이터 URL로 ID 공급자의 구성 정보를 가져오는 방식을 지원합니다. IdP 메타데이터 XML 파일에는 IdP 인증서, 엔티티 ID, 리디렉션 URL, 로그아웃 URL이 담겨 있습니다.

이 URL을 사용하면 구성 과정에서 SAML SSO URL과 Identity Provider Issuer URL 필드가 자동으로 채워지고, Identity Provider Public Certificate도 서버에서 내려받아 로컬에 설정됩니다.

현재 Okta와 Microsoft ADFS server 2012 및 2016에서 지원됩니다.

자세한 절차는 Okta로 SAML 구성, Windows Server 2012 ADFS로 SAML 구성, Windows Server 2016 ADFS로 SAML 구성 문서를 참고하세요. v10.9에서 추가된 AES-192-GCM 및 AES-256-GCM 암호화 지원을 포함해 Mattermost가 SAML에 대해 지원하는 암호화 방식은 암호화 옵션 문서에서 확인할 수 있습니다.

SAML 공급자

ID 공급자(IdP): ID 공급자는 인증을 수행합니다. 사용자가 로그인을 클릭하면 ID 공급자가 사용자가 누구인지 확인하고, 사이트에 접근할 수 있는 적절한 인가 정보와 함께 데이터를 서비스 공급자에게 전송합니다.

예: OneLogin, Okta, Microsoft Active Directory(ADFS) 또는 Azure.

서비스 공급자(SP): 서비스 공급자는 IdP로부터 인증 및 인가 정보를 받습니다. 정보를 받으면 사용자에게 시스템 접근을 허용하고 로그인시킵니다.

예: Mattermost, Zendesk, Zoom, Salesforce.

SAML 요청(AuthNRequest)

Mattermost가 SP 주도(SP-initiated) SAML 요청 흐름을 시작하면, base64 문자열 형태의 XML 페이로드를 담은 HTTP-Redirect 바인딩 요청을 IdP로 생성합니다.

bM441nuRIzAjKeMM8RhegMFjZ4L4xPBHhAfHYqgnYDQnSxC++Qn5IocWuzuBGz7JQmT9C57nxjxgbFIatiqUCQN17aYrLn/mWE09C5mJMYlcV68ibEkbR/JKUQ+2u/N+mSD4/C/QvFvuB6BcJaXaz0h7NwGhHROUte6MoGJKMPE=

AuthNRequest는 Mattermost가 서명할 수도 있으며, 이 경우 XML 페이로드는 다음과 비슷합니다.

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:samlsig="https://www.w3.org/2000/09/xmldsig#" ID="_u5mpjadp1fdozfih4cj8ap4brh" Version="2.0" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="http://localhost:8065/login/sso/saml" IssueInstant="2019-06-08T16:00:31Z">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://www.okta.com/exkoxukx1D8OIfY03356</saml:Issuer>
    <samlsig:Signature Id="Signature1">
        <samlsig:SignedInfo>
            <samlsig:CanonicalizationMethod Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#"></samlsig:CanonicalizationMethod>
            <samlsig:SignatureMethod Algorithm="https://www.w3.org/2000/09/xmldsig#rsa-sha256"></samlsig:SignatureMethod>
            <samlsig:Reference URI="#_u5mpjadp1fdozfih4cj8ap4brh">
                <samlsig:Transforms>
                    <samlsig:Transform Algorithm="https://www.w3.org/2000/09/xmldsig#enveloped-signature"></samlsig:Transform>
                </samlsig:Transforms>
                <samlsig:DigestMethod Algorithm="https://www.w3.org/2000/09/xmldsig#sha256"></samlsig:DigestMethod>
                <samlsig:DigestValue></samlsig:DigestValue>
            </samlsig:Reference>
        </samlsig:SignedInfo>
        <samlsig:SignatureValue></samlsig:SignatureValue>
        <samlsig:KeyInfo>
            <samlsig:X509Data>
                <samlsig:X509Certificate>MIIFmzCCA4OgAwIBAgIJAIusvV3gZIwiMA0GCSqGSIb3DQEBCwUAMGIxCzAJBgNVBAYTAlVTMRIwEAYDVQQHDAlQYWxvIEFsdG8xEzARBgNVBAoMCk1hdHRlcm1vc3QxDzANBgNVBAsMBkRldk9wczEZMBcGA1UEAwwQYmFzZS5leGFtcGxlLmNvbTAeFw0xOTA2MDcxMjQ0MTdaFw0yOTA2MDQxMjQ0MTdaMGIxCzAJBgNVBAYTAlVTMRIwEAYDVQQHDAlQYWxvIEFsdG8xEzARBgNVBAoMCk1hdHRlcm1vc3QxDzANBgNVBAsMBkRldk9wczEZMBcGA1UEAwwQYmFzZS5leGFtcGxlLmNvbTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBALAfDj+RyByszTOPRL4b+cilNF/3PB1I0CG3TNzgllgy5CwRGHLKn5/t8rPsJoWLKOUGenzVdXWuoVi3jyl5FZ1N60CBbXfmSWk20dSIkcYCcYEgs1BTBqKKYFw2dV4M0oppzNtlq7A0Glpg/gpaR/2TXEPAhOsUfORC2qAdJt9ev0AQjp5V0TkIKMZz8oo33Coi38TG5r/LG+ihRbpWzO7j9Rc2S5I6bczvG4wOg7nVKG+B5XBvuU9PjSqgxpd/F/fYf+ggAEru58E+VM4veCRV8vSPbBqDG4FMPV6DiA+tH/70n6zuPCS3soxX00kjKtP80QD6UgzvM2NN7PHiNlf0Zj6VCU3VdjEnypg7dzlHJuyyaAaTD5nSfkecamEoJpq7kaUB7uTmBHELRUhOOy24f54HnP72vnxicZL8cWsOkJwQAqIGzBxQ7J0uX4Os71WrV2YIur8QVk6KN6MBPxfiCh3xO/R+cycgx0aMrWZoyzOzP7NCTM5MNE41C48xeGviyCtUID4xiBow+xo6IDUaiCoUVJhz579ore8ic70a19DD0qHy4SpBvrUwCO54kvkgn6HjYlLC/k8nFM9F9W9wVAQD/QwIjd7EtLZLGgbU61Jv3q4kZxxq270hogCRY0lmI3RxkedGHhetF7kaizrikW5zJQEeido/ir37HhX5AgMBAAGjVDBSMBIGA1UdEwEB/wQIMAYBAf8CAQAwPAYDVR0RBDUwM4IQbG9ncy5leGFtcGxlLmNvbYITbWV0cmljcy5leGFtcGxlLmNvbYcEwKgAAYcEfwAAATANBgkqhkiG9w0BAQsFAAOCAgEAH1O91BABHXZjrU7v1OwG+GbU/4TYZqBXXNxax++OFSRCkEEoNKGg49R6J7lY4lrm12zBlw+oGSyjIOerzi39/dcxDkKpzyhGvEN4mExbDlybmdCVrHPeWgZl7uwqn4Bj1xiu97M6eMthgxJE7KVNDGDHthGL0/fTlONIh3qS7Far33hLHJJKy3+lC1MDB8cNltV3mf/ctHCx5Wa0bfZId0MJgd/seP0WU1HCf3kIxhnhsnOYs32xu7EGiM4/lgnquVd/q/f99ueSaDSHrep373/w2ce9iF3U0qcLd2iP8ayF/daGeW1dVPL9R10Oe4BpRjMkjlLwhZdjJeKSg9GBa2GXUEn1Ru9vpSw/C10no3Qx/6ZHweYbSmJ6hBg4T0nDBp6iVS1eQULNXxDuDWb26U0ESOO5jK8ATywuc45o0bqdvD1XOrGYGfGnofx7ofRWwKHWfltvxurnbsyo2vH6nM6K41K2DpVdyQOKAGvKe/oCWfdi+WyBQJGWcIp2OTC1XyWHv7JsY3lo04+islkHEcqJyd8Rf8GWmRHdXz0WzGiZbxWzAuvRRWnzM31VAws8kQBHTBwIJlJoGX4AXfEvPi+NTxkntf8cQdJucK9ZZbP4ycXHULO4LneyJoJ9Q7nxX11xWv7BDWxxclOXy6tyUkg9Fjb7pQ/HCVvGhRzilVU=</samlsig:X509Certificate>
            </samlsig:X509Data>
        </samlsig:KeyInfo>
    </samlsig:Signature>
</samlp:AuthnRequest>

SAML 응답

IdP가 SP에 보내는 SAML 응답에는 여러 유형이 있습니다. 응답에는 사용자의 NameID와 속성을 담은 어설션(Assertion)이 포함됩니다.

아래는 응답 유형별 표입니다. SAML 어설션은 서명되었지만 SAML 응답 자체는 서명되지 않은 경우를 제외하면 모든 응답 유형을 완전히 지원합니다.

각 유형의 XML 응답 예시는 OneLogin SAML 응답 예시를 참고하세요.

AD/LDAP과의 SAML 동기화 기술 설명

활성화된 경우 AD/LDAP과의 SAML 동기화는 다음 단계로 진행됩니다.

1. Mattermost 데이터베이스에서 Users.AuthService가 ldap으로 설정된 현재 LDAP 사용자를 모두 가져옵니다. Mattermost 데이터베이스에 대해 실행되는 SQL 쿼리는 SELECT * FROM Users WHERE AuthService = 'ldap'입니다.
2. Mattermost 데이터베이스에서 Users.AuthService가 saml로 설정된 현재 SAML 사용자를 모두 가져옵니다. Mattermost 데이터베이스에 대해 실행되는 SQL 쿼리는 SELECT * FROM Users WHERE AuthService = 'saml'입니다.
3. LdapSettings.UserFilter에 정의된 대로 LDAP 서버에서 현재 LDAP 사용자를 모두 가져옵니다. 이는 LDAP 서버에 대해 실행되는 LDAP 쿼리입니다. 사용자는 LdapSettings.MaxPageSize에 정의된 크기의 배치 단위로 조회됩니다.
4. LDAP 속성을 업데이트합니다. 1단계에서 가져온 기존 Mattermost 사용자 각각에 대해 3단계의 LDAP 사용자 목록에서 일치 항목을 찾습니다. 일치 여부는 Mattermost 사용자의 Users.AuthData 필드를 LdapSettings.IdAttribute LDAP 설정과 비교해 판단합니다.
   • 사용자의 속성 중 변경된 것이 있으면 해당 속성을 LDAP 서버에서 복사해 오고 사용자를 업데이트됨으로 표시합니다.
   • 대응하는 LdapSettings.IdAttribute를 찾지 못하면 해당 사용자가 LDAP 서버에서 삭제된 것으로 간주하고, Users.DeleteAt 필드에 유효한 타임스탬프를 설정해 Mattermost에서 비활성화합니다.
5. SAML 속성을 업데이트합니다. 2단계에서 가져온 기존 Mattermost 사용자 각각에 대해 3단계의 LDAP 사용자 목록에서 일치 항목을 찾습니다. 일치 여부는 SamlSettings.Email을 LdapSettings.EmailAttribute LDAP 설정과 비교해 판단합니다.
   • 사용자의 속성 중 변경된 것이 있으면 해당 속성을 LDAP 서버에서 복사해 오고 사용자를 업데이트됨으로 표시합니다.
   • 대응하는 LdapSettings.EmailAttribute를 찾지 못하면 해당 사용자가 LDAP 서버에서 삭제된 것으로 간주하고, Users.DeleteAt 필드에 유효한 타임스탬프를 설정해 Mattermost에서 비활성화합니다.

자주 묻는 질문

Mattermost가 사용하는 SAML 메타데이터 XML 파일은 어떻게 얻나요?

Mattermost RESTful API 엔드포인트 /api/v4/saml/metadata를 호출해 XML 파일을 얻을 수 있습니다.

유용한 다른 SAML API 호출은 API 레퍼런스를 참고하세요.

API로 사용자 속성을 업데이트할 수 있나요?

아니요. Mattermost가 사용자 인증에 SAML을 사용하도록 구성된 경우, 다음 사용자 속성은 API로 변경할 수 없습니다. 이름, 성, 직책, 닉네임, 이메일, 프로필 이미지, 사용자 이름. 이 사용자 속성들은 SAML이 권위 있는 원본이어야 합니다.

Mattermost의 사용자 ObjectGUID가 ADFS에서 보이는 값과 다른 이유는 무엇인가요?

Active Directory의 Object-Guid 속성(LDAP 표시 이름 objectGUID)은 16바이트 배열이며 여러 방식으로 표시될 수 있습니다. 다만 인코딩을 바꾸는 것은 Microsoft뿐이고, 나머지는 진법(8진수, 10진수, 16진수)만 다를 뿐 값은 동일하게 유지합니다. 구체적으로는 다음과 같습니다.

1. Linux ldapsearch 명령은 base 64로 표시합니다: Hrz/HqNKnU+lCNTYHx9Ycw==. LDIF 파일에서도 이 형식을 사용합니다.
2. Mattermost가 사용하는 LDAP Golang 패키지는 값을 16진수(base 16) 배열로 내보내며, 각 바이트를 백슬래시로 구분합니다: \1e\bc\ff\1e\a3\4a\9d\4f\a5\08\d4\d8\1f\1f\58\73
   • 백슬래시를 제거하고(1ebcff1ea34a9d4fa508d4d81f1f5873) 이런 식으로 Golang에서 파싱할 수 있습니다. 이 스니펫은 각 값의 10진수 표현을 출력합니다: [30 188 255 30 163 74 157 79 165 8 212 216 31 31 88 115]
3. Windows PowerShell은 값을 다음과 같이 표시합니다: 1effbc1e-4aa3-4f9d-a508-d4d81f1f5873

ID 공급자가 relaystate를 클라이언트로 다시 전달해야 하나요?

네. 기본적으로 그렇게 하지 않는 공급자와 Mattermost를 연동하는 경우 relaystate가 활성화되어 있는지 확인하세요. 자세한 내용은 PingIdentity의 SAML RelayState 문서를 참고하세요.

SAML 로그온 과정은 어떻게 문제를 해결하나요?

SAML 연결 문제를 해결하는 데 가장 유용하다고 알려진 도구는 SAML Chrome Panel Chrome 확장 프로그램입니다. 다른 브라우저에 비슷한 도구가 있는지는 알지 못하지만, 이 도구만으로도 Chrome을 설치할 이유가 충분합니다.