Windows Server 2016 ADFS로 SAML 구성

이 문서는 Mattermost와 Microsoft Windows Server 2016 환경에서 Microsoft ADFS로 SAML 2.0을 구성하는 단계를 설명합니다.

시작하기 전에

시작하기 전에 SAML 연결을 암호화하는 데 사용할 암호화 인증서를 생성해야 합니다.

1. GitHub의 mattermost/docs 저장소에 있는 Bash 스크립트를 사용하거나 다른 적절한 방법을 사용할 수 있습니다. 여러 URL/IP에 사용할 수 있는 자체 서명 x509v3 인증서 생성 방법은 자체 서명 인증서 생성 문서를 참조하세요.
2. 생성된 두 파일을 저장합니다. 각각 개인 키와 공개 키입니다. 시스템 콘솔에서는 각각 Service Provider Private Key(서비스 공급자 개인 키)와 Service Provider Public Certificate(서비스 공급자 공개 인증서)라고 부릅니다.

사전 요구 사항

• 모든 사용자에게 email과 username 속성이 지정된 Active Directory 인스턴스. Mattermost 3.3 이하 버전을 실행하는 서버에서는 사용자에게 first name과 last name 속성도 지정되어 있어야 합니다.
• 실행 중인 Microsoft Server. 이 가이드의 스크린샷은 Microsoft Server 2012R2 기준이지만, 다른 버전에서도 유사한 단계가 동작합니다.
• ADFS 로그인 페이지에 서명할 SSL 인증서.
• Microsoft Server에 설치된 ADFS. ADFS 배포·구성에 대한 자세한 안내는 이 Microsoft 문서를 참조하세요.

ADFS 설치 환경에서 ADFS 콘솔을 엽니다. Service를 선택한 뒤 Endpoints를 선택합니다. Type 열에서 SAML 2.0/WS-Federation을 찾아 URL Path 열의 값을 기록해 둡니다. 이 가이드에서는 이를 SAML SSO URL Endpoint라고도 부릅니다. 설치 시 기본값을 선택했다면 이 값은 /adfs/ls입니다.

신뢰 당사자 트러스트 추가

1. ADFS 관리 스냅인을 연 뒤 오른쪽 사이드바에서 AD FS > Relying Party Trusts > Add Relying Party Trust(AD FS > 신뢰 당사자 트러스트 > 신뢰 당사자 트러스트 추가)를 선택합니다. Relying Party Trusts를 마우스 오른쪽 버튼으로 클릭한 뒤 컨텍스트 메뉴에서 Add Relying Party Trust를 선택할 수도 있습니다.

   

2. 구성 마법사의 Welcome 화면에서 Claims aware를 선택한 뒤 Start를 선택합니다.

   

3. Select Data Source 화면에서 Enter data about the relying party manually를 선택합니다.

   

4. Specify Display Name 화면에서 Display Name(예: Mattermost)을 입력합니다. 메모는 선택 사항으로 추가할 수 있습니다.

   

5. Configure Certificate 화면에서 인증서 설정을 기본값 그대로 둡니다.

   

SAML 연결에 대한 암호화를 설정하려면 Browse를 선택한 뒤 Service Provider Public Certificate를 업로드합니다.

6. Configure URL 화면에서 Enable Support for the SAML 2.0 WebSSO protocol을 선택한 뒤 다음 형식으로 SAML 2.0 SSO service URL을 입력합니다. https://<your-mattermost-url>/login/sso/saml. 여기서 <your-mattermost-url>은 일반적으로 Mattermost Site URL과 일치해야 합니다.

   

7. Configure Identifiers 화면에서 Relying party trust identifier를 입력합니다. 이 값은 요청되는 클레임을 식별합니다. SAML 2.0 SSO service URL 형식은 https://<your-mattermost-url>/login/sso/saml이어야 하며, 여기서 <your-mattermost-url>은 Mattermost Site URL과 일치합니다. 그런 다음 Next를 선택합니다.

   

   

이 문자열은 Service Provider Identifier 문자열과 일치해야 합니다. Relying party trust identifier와 접두사 매칭이 적용되는 방식에 대한 자세한 내용은 이 문서를 참조하세요.

동일한 방식으로 SAML 2.0 SSO service URL도 추가합니다.

8. Choose Access Control Policy 화면에서 환경에 적합한 접근 제어 정책을 선택합니다. 이 가이드에서는 기본값인 Permit everyone과 체크 해제 상태를 가정합니다.

   

9. Ready to Add Trust 화면에서 설정을 검토합니다.

   

10. Finish 화면에서 Configure claims issuance policy for this application을 선택한 뒤 Close를 선택합니다.

    

클레임 규칙 만들기

1. Claim Rules 편집기의 Issuance Transform Rules 탭에서 Add Rule…을 선택합니다.

   

2. Choose Rule Type 화면의 드롭다운 메뉴에서 Send LDAP Attributes as Claims를 선택한 뒤 Next를 선택합니다.

   

3. Configure Claim Rule 화면에서 원하는 Claim Rule Name을 입력하고 Attribute Store로 Active Directory를 선택한 뒤 다음 매핑을 추가합니다.

   • LDAP Attribute column에서 E-Mail-Addresses를 선택합니다. Outgoing Claim Type에는 Email을 입력합니다.
   • LDAP Attribute column에서 E-Mail-Addresses를 선택합니다. Outgoing Claim Type에는 Name ID를 입력합니다.
   • LDAP Attribute column에서 Given-Name을 선택합니다. Outgoing Claim Type에는 FirstName을 입력합니다.
   • LDAP Attribute column에서 Surname을 선택합니다. Outgoing Claim Type에는 LastName을 입력합니다.
   • LDAP Attribute column에서 SAM-Account-Name을 선택합니다. Outgoing Claim Type에는 Username을 입력합니다.

FirstName과 LastName 속성은 선택 사항입니다.

Finish를 선택해 규칙을 추가합니다.

Outgoing Claim Type 열의 항목은 수정할 수 있습니다. 대시는 포함할 수 있지만 공백은 사용할 수 없습니다. 이 값들은 Mattermost에서 대응하는 필드를 매핑하는 데 사용됩니다.

4. Add Rule을 선택해 새 규칙을 하나 더 만듭니다.

5. Choose Rule Type 화면의 드롭다운 메뉴에서 Transform an Incoming Claim을 선택한 뒤 Next를 선택합니다.

   

6. Configure Claim Rule 화면에서 원하는 Claim Rule Name을 입력한 뒤 다음을 설정합니다.

   • Incoming claim type으로 Name ID를 선택합니다
   • Incoming name ID format으로 Unspecified를 선택합니다
   • Outgoing claim type으로 E-Mail Address를 선택합니다

Pass through all claim values를 선택한 뒤 Finish를 선택합니다.

7. Finish를 선택해 클레임 규칙을 만든 뒤 OK를 선택해 규칙 생성을 완료합니다.

8. Windows PowerShell을 관리자 권한으로 연 뒤 다음 명령을 실행합니다.

   Set-ADFSRelyingPartyTrust -TargetName <display-name> -SamlResponseSignature "MessageAndAssertion"

여기서 <display-name>은 신뢰 당사자 트러스트를 추가할 때 4단계에서 지정한 이름입니다. 이 예시에서 <display-name>은 mattermost가 됩니다.

이 작업은 SAML 메시지에 서명을 추가해 검증이 성공하도록 합니다.

ID 공급자 인증서 내보내기

다음으로 ID 공급자 인증서를 내보냅니다. 이 인증서는 나중에 Mattermost에 업로드해 SAML 구성을 마무리하는 데 사용합니다.

1. ADFS 관리 스냅인을 열고 AD FS > Service > Certificates(AD FS > 서비스 > 인증서)를 선택한 뒤 Token-signing 아래의 인증서를 더블 클릭합니다. 해당 항목을 마우스 오른쪽 버튼으로 클릭한 뒤 컨텍스트 메뉴에서 View Certificate를 선택할 수도 있습니다.

   

2. Certificate 화면에서 Details 탭을 열고 Copy to File을 선택한 뒤 OK를 선택합니다.

   

3. Certificate Export Wizard 화면에서 Next를 선택합니다.

   

4. Base-64 encoded X.509 (.CER)을 선택한 뒤 다시 Next를 선택합니다.

   

5. Certificate Export Wizard 화면에서 Browse를 선택해 ID 공급자 인증서를 내보낼 위치를 지정한 뒤 파일 이름을 입력합니다.

   

6. Save를 선택합니다. Certificate Export Wizard 화면에서 파일 경로가 올바른지 확인한 뒤 Next를 선택합니다.

7. Completing the Certificate Export Wizard에서 Finish를 선택한 뒤 OK를 선택해 내보내기가 성공했는지 확인합니다.

   

Mattermost에서 SAML 사인온 구성

ADFS 서버의 루트 URL 뒤에 "FederationMetadata/2007-06/FederationMetadata.xml"을 붙여 메타데이터 URL을 만듭니다. 예: https://<adfs.domain.com>/federationmetadata/2007-06/FederationMetadata.xml>

다음으로 Mattermost 서버를 시작한 뒤 시스템 관리자로 Mattermost에 로그인합니다. System Console > Authentication > SAML(시스템 콘솔 > 인증 > SAML)로 이동해 메타데이터 URL을 Identity Provider Metadata URL 필드에 붙여 넣은 뒤 Get SAML Metadata from IdP를 선택합니다.

그러면 SAML SSO URL과 Identity Provider Issuer URL 필드가 자동으로 채워집니다. Identity Provider Public Certificate도 서버에서 내려받아 로컬에 설정됩니다.

다음 필드를 선택할 수 있습니다.

• Enable Login With SAML 2.0을 true로 설정합니다.
• Enable Synchronizing SAML Accounts With AD/LDAP을 환경에 맞게 설정합니다.
• Override SAML bind data with AD/LDAP information을 환경에 맞게 설정합니다.

메타데이터 URL을 사용하지 않을 계획이라면 다음 필드를 직접 입력할 수 있습니다.

• SAML SSO URL에는 이 과정 초반에 복사한 SAML 2.0/W-Federation URL ADFS Endpoint를 사용합니다.
• Identity Provider Issuer URL에는 ADFS의 Relying party trust identifier를 사용합니다.
• Identity Provider Public Certificate에는 X.509 Public Certificate를 사용합니다.

2. 서명을 검증하도록 Mattermost를 구성합니다.

   • Verify Signature를 true로 설정합니다.
   • Service Provider Login URL에는 ADFS에서 지정한 SAML 2.0 SSO service URL을 사용합니다.

   

3. 암호화를 활성화합니다.

   • Enable Encryption을 true로 설정합니다.
   • Service Provider Private Key에는 이 과정 초반에 생성한 Service Provider Private Key를 사용합니다.
   • Service Provider Public Certificate에는 이 과정 초반에 생성한 Service Provider Public Certificate를 사용합니다.
   • Sign Request를 환경에 맞게 설정합니다.

   

4. Mattermost에서 사용자 정보를 업데이트하는 데 사용할 SAML 어설션 속성을 설정합니다. email과 username 속성은 필수이며, 앞서 ADFS에서 입력한 값과 일치해야 합니다. 자세한 내용은 SAML 구성 설정 문서를 참조하세요.

Mattermost 3.3 이하 버전을 실행하는 서버에서는 first name과 last name 속성도 필수 필드입니다.

5. Save를 선택합니다.

6. (선택) First Name 속성과 Last Name 속성을 구성했다면 System Console > Site Configuration > Users and Teams(시스템 콘솔 > 사이트 구성 > 사용자 및 팀)로 이동해 Teammate Name Display를 Show first and last name으로 설정합니다. 사용자 경험 측면에서 이 설정을 권장합니다.

이것으로 완료되었습니다. SAML SSO가 정상적으로 활성화되었는지 확인하려면, 프로필 사진에서 Profile > Security > Sign-in Method > Switch to SAML SSO(프로필 > 보안 > 로그인 방식 > SAML SSO로 전환)를 통해 시스템 관리자 계정을 이메일 인증에서 SAML 기반 인증으로 전환한 다음, SAML 자격 증명으로 로그인해 전환을 완료합니다.

또한 마이그레이션이 어떻게 진행되는지 사용자에게 설명하는 공지를 게시하는 것을 권장합니다.

config.json 파일을 편집해 SAML 구성 설정에 따라 SAML을 활성화하는 방식으로 ADFS용 SAML을 구성할 수도 있습니다. 변경 사항을 적용하려면 Mattermost 서버를 재시작해야 합니다.

자주 묻는 질문

SAML에서 지원하는 암호화 옵션은 무엇인가요?

Mattermost가 SAML에서 지원하는 암호화 방식은 암호화 옵션 문서를 참조하세요.

이메일 대신 Id 속성으로 인증을 바인딩하는 방법

이메일 대신 Id 속성을 사용해 사용자를 바인딩할 수 있습니다. 고유하면서 시간이 지나도 변경되지 않는 ID를 선택하는 것을 권장합니다.

Id 속성으로 구성하면 이전 사용자의 정보를 노출하지 않고도 새 사용자에게 동일한 이메일 주소를 재사용할 수 있습니다. 예를 들어 joe.smith@mattermost.com이라는 이메일 주소를 쓰던 직원이 퇴사한 뒤, Joe Smith라는 이름의 새 직원이 같은 이메일을 사용할 수 있습니다. 이 구성은 사용자의 이름이 바뀌어 이메일을 변경해야 하는 경우에도 유용합니다.

이 처리는 이메일 바인딩과의 하위 호환성을 고려해 설계되었습니다. 신규 계정 생성 시, 그리고 구성 이후 로그인하는 계정에 적용되는 과정은 다음과 같습니다.

• SAML로 인증된 사용자는 Id Attribute가 구성되어 있으면 해당 속성으로, 그렇지 않으면 SAML에서 전달받은 이메일로 SAML 서비스 사용자에 바인딩됩니다.
• 사용자가 로그인을 시도하고 SAML 서버가 유효한 인증 응답을 반환하면, 서버는 SAML 인증의 "Id" 필드로 사용자를 검색합니다.
• 해당 ID에 바인딩된 사용자가 이미 존재하면 그 사용자로 로그인합니다.
• 해당 ID에 바인딩된 사용자가 없으면 이메일을 기준으로 검색합니다.
• 해당 이메일에 바인딩된 사용자가 존재하면 이메일로 로그인한 뒤 인증 데이터를 이메일 대신 ID로 업데이트합니다.
• ID나 이메일에 바인딩된 사용자가 존재하지 않으면 SAML 계정에 ID로 바인딩된 새 Mattermost 계정을 생성하고 로그인을 허용합니다.

로그인이 "one of the attributes is incorrect" / "<attribute> attribute is missing" 오류로 실패하는 이유는 무엇인가요?

로그인이 SAML login was unsuccessful because one of the attributes is incorrect. Please contact your System Administrator. 오류로 실패하고, 서버 로그에 email attribute is missing이나 name attribute is missing 같은 상세 정보가 함께 기록된다면, ID 공급자(IdP)가 보낸 어설션에 Mattermost SAML 속성 설정에 구성한 이름과 정확히 일치하는 속성이 없다는 뜻입니다.

Mattermost는 각 속성을 어설션에 나타난 전체 Name(또는 FriendlyName) 기준으로 한 글자도 다르지 않게 매칭합니다. 오류 메시지에 표시된 속성 이름은 Mattermost에 입력했으나 찾지 못한 값입니다.

이 문제는 IdP가 속성을 네임스페이스 아래로 보내기 때문에 발생하는 경우가 가장 많습니다. 예를 들어 Microsoft Entra ID는 기본적으로 내장 클레임을 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ 아래로 내보내므로, Entra ID 관리 UI에서 email로 보이는 속성이 실제 어설션에서는 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email로 전송됩니다. Mattermost에 email만 입력하면 매칭되지 않습니다.

해결 방법은 다음과 같습니다.

• SAML 응답을 캡처해 디코딩하고(예: SAML-tracer 브라우저 확장 프로그램 사용), <AttributeStatement> 안에 있는 각 <Attribute> 요소의 Name 속성을 확인합니다.
• 각 Mattermost 속성 필드를 어설션에 나타난 정확한 Name 값(네임스페이스 접두사 포함)으로 설정하거나, Mattermost에서 사용하려는 짧은 이름으로 클레임을 내보내도록 IdP를 다시 구성합니다.

Microsoft ADFS를 통한 SAML을 IWA(Integrated Windows Authentication)와 함께 구성할 수 있나요?

가능합니다. IWA는 브라우저에서 지원되며, iOS와 Android 모바일 앱에는 2019년 2분기(모바일 앱 v1.18 이상)에 지원이 추가되었습니다.

다만 Electron의 제약으로 인해 Mattermost 데스크톱 앱에서는 IWA가 지원되지 않습니다. 우회 방법으로 데스크톱 앱처럼 빠르게 접근할 수 있도록 Mattermost용 브라우저 바탕 화면 바로 가기를 만들 수 있습니다.

SAML로 로그인하는 사용자를 프로비저닝·디프로비저닝할 수 있나요?

가능하지만 AD/LDAP에 의존합니다. 현재 SCIM은 지원하지 않습니다. 자세한 내용은 "사용자를 어떻게 비활성화하나요?"를 참조하세요.

사용자를 다른 인증 방식(예: 이메일)에서 SAML로 마이그레이션하려면 어떻게 하나요?

자세한 내용은 mmctl user migrate-auth 명령 문서를 참조하세요.

SAML은 OAuth 2.0 및 OpenID Connect와 어떻게 다른가요?

OAuth 2.0은 주로 위임된 인가를 목적으로 만들어졌습니다. 애플리케이션이 Google 연락처 목록 같은 리소스에 접근할 수 있도록 인가하는 방식이며, 인증을 다루지는 않습니다.

OpenID Connect는 OAuth 2.0 위에 구축되었으며 인증을 지원하므로 직접적인 SSO가 가능합니다.

SAML은 OpenID Connect와 비슷하지만 일반적으로 엔터프라이즈 환경에서 사용됩니다. OpenID Connect는 소비자 웹사이트와 웹·모바일 앱에서 더 흔히 쓰입니다.

자세한 내용은 https://hackernoon.com/demystifying-oauth-2-0-and-openid-connect-and-saml-12aa4cf9fdba 에서 확인하세요.

AD/LDAP와 SAML 동기화 구성

SAML 로그인 구성에 더해, SAML 계정을 AD/LDAP와 동기화하도록 선택적으로 구성할 수 있습니다. 구성하면 다음과 같이 동작합니다.

• Mattermost가 AD/LDAP에 관련 계정 정보를 질의하고, 속성(이름, 성, 닉네임) 변경에 따라 SAML 계정을 업데이트합니다.
• AD/LDAP에서 비활성화된 계정은 Mattermost에서도 비활성화되며, Mattermost가 속성을 동기화하는 시점에 해당 계정의 활성 세션이 취소됩니다.

AD/LDAP와 SAML 동기화를 구성하려면 다음을 수행합니다.

1. System Console > Authentication > SAML 2.0으로 이동한 뒤 Enable Synchronizing SAML Accounts With AD/LDAP를 true로 설정합니다.
2. System Console > Authentication > AD/LDAP로 이동해 AD/LDAP 마법사를 연 다음 Connection Settings 섹션으로 이동해 Enable Synchronization with AD/LDAP를 true로 설정합니다.
3. 동기화 시 게스트 사용자를 제외하려면 System Console > Authentication > SAML 2.0으로 이동해 Ignore Guest Users when Synchronizing with AD/LDAP를 true로 설정합니다.
4. Mattermost를 AD/LDAP 서버에 연결하려면 구성 설정 문서에 따라 나머지 AD/LDAP 설정을 지정합니다.

   AD/LDAP 로그인을 활성화하지 않으려면 System Console > Authentication > AD/LDAP 마법사로 이동해 Connection Settings 섹션에서 Enable sign-in with AD/LDAP를 false로 설정합니다.

5. Mattermost가 SAML 사용자 계정을 AD/LDAP와 동기화하는 주기를 지정하려면 System Console > Authentication > AD/LDAP 마법사로 이동해 Sync Performance 섹션에서 Synchronization Interval을 분 단위로 설정합니다. 기본값은 60분입니다. 계정을 비활성화한 직후 즉시 동기화하려면 Sync History 섹션으로 이동해 AD/LDAP Synchronize Now를 선택합니다.
6. Mattermost가 AD/LDAP 서버에 정상적으로 연결되는지 확인하려면 System Console > Authentication > AD/LDAP 마법사로 이동해 Connection Settings 섹션에서 Test Connection을 선택합니다.

AD/LDAP 동기화를 활성화하면 사용자 속성이 이메일 주소를 기준으로 AD/LDAP와 동기화됩니다. 특정 이메일 주소를 가진 사용자에게 AD/LDAP 계정이 없으면, 다음 AD/LDAP 동기화 시 해당 사용자는 Mattermost에서 비활성화됩니다.

계정을 다시 활성화하려면 다음을 수행합니다.

1. AD/LDAP 서버에 해당 사용자를 추가합니다.
2. System Console > Environment > Web Server(시스템 콘솔 > 환경 > 웹 서버)로 이동해 Purge All Caches를 선택하여 Mattermost의 모든 캐시를 비웁니다.
3. System Console > Authentication > AD/LDAP 마법사로 이동해 Sync History 섹션에서 AD/LDAP Synchronize Now를 선택하여 AD/LDAP 동기화를 실행합니다.
4. System Console > Environment > Web Server에서 Purge All Caches를 다시 선택해 캐시를 한 번 더 비웁니다. 그러면 Mattermost에서 해당 계정이 다시 활성화됩니다.

자세한 내용은 AD/LDAP와의 SAML 동기화에 대한 기술 설명을 참조하세요.

SAML 데이터를 AD/LDAP 데이터로 덮어쓰기

또는 SAML 바인드 데이터를 AD/LDAP 정보로 덮어쓰도록 선택할 수 있습니다. SAML ID 속성으로 사용자를 바인딩하는 방법에 대한 자세한 내용은 이 문서를 참조하세요.

이 처리는 SAML 이메일 주소를 AD/LDAP 이메일 주소 데이터로 덮어쓰며, 구성되어 있는 경우 SAML Id Attribute를 AD/LDAP Id Attribute로 덮어씁니다. 사용자의 이메일 주소가 변경될 때 새 사용자가 생성되지 않도록 하려면 SAML ID Attribute와 함께 이 구성을 사용하는 것을 권장합니다.

이 과정에서 기존 사용자 계정이 비활성화되지 않도록 하려면, 양쪽 시스템에서 데이터를 내보내 ID 데이터를 비교함으로써 SAML ID와 LDAP ID가 일치하는지 확인하세요. Mattermost 내에서 AD/LDAP와 SAML의 ID Attribute를 동일한 데이터를 담은 필드로 매핑하면 ID가 일치하게 됩니다.

1. System Console > Authentication > SAML 2.0 > Id Attribute로 이동해 SAML Id Attribute를 설정합니다.
2. System Console > Authentication > SAML 2.0 > Override SAML bind data with AD/LDAP information을 true로 설정합니다.
3. System Console > Authentication > SAML 2.0 > Enable Synchronizing SAML Accounts With AD/LDAP를 true로 설정합니다.
4. System Console > Authentication > AD/LDAP 마법사로 이동해 Sync History 섹션에서 AD/LDAP Synchronize Now를 선택하여 AD/LDAP 동기화를 실행합니다.