Microsoft Windows Server 2016을 사용하여 Microsoft ADFS로 SAML 구성하기

이 문서는 Mattermost와 Microsoft Windows Server 2016을 위한 Microsoft ADFS로 SAML 2.0을 구성하는 단계를 제공합니다.

시작하기 전에

시작하기 전에 SAML 연결을 암호화하기 위한 암호화 인증서를 생성해야 합니다.

1. GitHub의 mattermost/docs 저장소에서 Bash 스크립트 를 사용하거나 다른 적절한 방법을 사용할 수 있습니다. 여러 URL/IP에 사용할 자체 서명된 x509v3 인증서 생성에 대한 자세한 내용은 자체 서명 인증서 생성 문서를 참조하세요.

2. 생성된 두 파일을 저장하세요. 이는 개인 키와 공개 키입니다. 시스템 콘솔에서는 각각 서비스 제공자 개인 키 와 서비스 제공자 공개 인증서 라고 합니다.

사전 요구사항

• 모든 사용자가 이메일과 사용자 이름 속성을 지정한 Active Directory 인스턴스가 필요합니다. 3.3 이전 버전의 Mattermost 서버를 실행하는 경우 사용자는 이름과 성 속성도 지정해야 합니다.

• 실행 중인 Microsoft Server가 필요합니다. 이 가이드에서 사용된 스크린샷은 Microsoft Server 2012R2의 것이지만, 다른 버전에서도 유사한 단계가 작동할 것입니다.

• ADFS 로그인 페이지에 서명할 SSL 인증서가 필요합니다.

• Microsoft Server에 설치된 ADFS가 필요합니다. ADFS 배포 및 구성에 대한 자세한 가이드는 이 Microsoft 문서 에서 찾을 수 있습니다.

ADFS 설치에서 ADFS 콘솔을 엽니다. 서비스 를 선택한 다음 엔드포인트 를 선택하세요. 유형 열에서 SAML 2.0/WS-Federation 을 검색하고 URL 경로 열의 값을 기록하세요. 이는 이 가이드에서 SAML SSO URL 엔드포인트 라고도 합니다. 설치 시 기본값을 선택했다면 이는 /adfs/ls 가 됩니다.

신뢰 당사자 신뢰 추가

1. ADFS 관리 스냅인을 열고 오른쪽 사이드바에서 AD FS > 신뢰 당사자 신뢰 > 신뢰 당사자 신뢰 추가 를 선택하세요. 또는 신뢰 당사자 신뢰 를 마우스 오른쪽 버튼으로 클릭한 다음 컨텍스트 메뉴에서 신뢰 당사자 신뢰 추가 를 선택할 수도 있습니다.

   

2. 구성 마법사의 시작 화면에서 클레임 인식 을 선택한 다음 시작 을 선택하세요.

   

3. 데이터 소스 선택 화면에서 신뢰 당사자에 대한 데이터를 수동으로 입력 을 선택하세요.

   

4. 표시 이름 지정 화면에서 표시 이름 을 입력하세요(예: Mattermost). 선택적 메모를 추가할 수 있습니다.

   

5. 인증서 구성 화면에서 인증서 설정을 기본값으로 두세요.

   

SAML 연결에 대한 암호화를 설정하려면 찾아보기 를 선택한 다음 서비스 제공자 공개 인증서를 업로드하세요.

6. URL 구성 화면에서 SAML 2.0 WebSSO 프로토콜 지원 활성화 를 선택한 다음 SAML 2.0 SSO 서비스 URL 을 다음 형식으로 입력하세요: https://<your-mattermost-url>/login/sso/saml 여기서 <your-mattermost-url> 은 일반적으로 Mattermost 사이트 URL 과 일치해야 합니다.

   

7. 식별자 구성 화면에서 신뢰 당사자 신뢰 식별자 를 입력하세요. 이는 요청된 클레임을 식별합니다. SAML 2.0 SSO 서비스 URL 형식은 https://<your-mattermost-url>/login/sso/saml 이어야 하며, 여기서 <your-mattermost-url> 은 Mattermost 사이트 URL 과 일치해야 합니다. 그런 다음 다음 을 선택하세요.

   

이 문자열은 반드시 서비스 제공자 식별자 문자열과 일치해야 합니다.신뢰 당사자 신뢰 식별자와 접두사 일치 방식에 대한 자세한 내용은 이 문서 를 참고하세요.

SAML 2.0 SSO 서비스 URL 도 동일한 방식으로 추가하세요.

8. 액세스 제어 정책 선택 화면에서 환경에 맞는 액세스 제어 정책을 선택하세요.이 가이드에서는 기본값인 모두 허용 과 체크되지 않은 박스를 가정합니다.

   

9. 신뢰 추가 준비 화면에서 설정을 검토하세요.

   

10. 마침 화면에서 이 애플리케이션에 대한 클레임 발급 정책 구성 을 선택한 후, 닫기 를 선택하세요.

    

클레임 규칙 생성

1. 클레임 규칙 편집기의 발급 변환 규칙 탭에서 규칙 추가… 를 선택하세요.

   

2. 규칙 유형 선택 화면에서 드롭다운 메뉴에서 LDAP 속성을 클레임으로 전송 을 선택한 후, 다음 을 선택하세요.

   

3. 클레임 규칙 구성 화면에서 원하는 클레임 규칙 이름 을 입력하고, 속성 저장소 로 Active Directory 를 선택한 후,다음 매핑을 추가하세요:

• LDAP 속성 열에서 E-Mail-Addresses 를 선택하고, 출력 클레임 유형 에 Email 을 입력하세요.

• LDAP 속성 열에서 E-Mail-Addresses 를 선택하고, 출력 클레임 유형 에 Name ID 를 입력하세요.

• LDAP 속성 열에서 Given-Name 을 선택하고, 출력 클레임 유형 에 FirstName 을 입력하세요.

• LDAP 속성 열에서 Surname 을 선택하고, 출력 클레임 유형 에 LastName 을 입력하세요.

• LDAP 속성 열에서 SAM-Account-Name 을 선택하고, 출력 클레임 유형 에 Username 을 입력하세요.

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

마침 을 선택하여 규칙을 추가하세요.

출력 클레임 유형 열의 항목은 수정할 수 있습니다. 항목에는 대시(-)는 사용할 수 있지만 공백은 사용할 수 없습니다. 이 항목들은 Mattermost의 해당 필드와 매핑하는 데 사용됩니다.

4. 규칙 추가 를 선택하여 새 규칙을 만드세요.

5. 규칙 유형 선택 화면에서 드롭다운 메뉴에서 수신 클레임 변환 을 선택한 후, 다음 을 선택하세요.

   

6. 클레임 규칙 구성 화면에서 원하는 클레임 규칙 이름 을 입력한 후, 다음을 진행하세요:

• 수신 클레임 유형 에 Name ID 를 선택하세요.

• 수신 이름 ID 형식 에 Unspecified 를 선택하세요.

• 출력 클레임 유형 에 E-Mail Address 를 선택하세요.

모든 클레임 값 전달 을 선택한 후, 마침 을 선택하세요.

7. 마침 을 선택하여 클레임 규칙을 생성한 후, 확인 을 선택하여 규칙 생성을 완료하세요.

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 를 선택합니다. 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 SSO를 구성하세요.

ADFS 서버의 루트 URL 뒤에 “FederationMetadata/2007-06/FederationMetadata.xml” 을 추가하여 메타데이터 URL을 만드세요. 예시: https://<adfs.domain.com>/federationmetadata/2007-06/FederationMetadata.xml>

다음으로 Mattermost 서버를 시작하고 시스템 관리자로 로그인하세요. System Console > Authentication > SAML 로 이동한 후, Identity Provider Metadata URL 필드에 메타데이터 URL을 붙여넣고 Get SAML Metadata from IdP 를 선택하세요.

이 작업을 하면 SAML SSO URL 과 Identity Provider Issuer URL 필드가 자동으로 채워집니다. ID 공급자 공개 인증서도 서버에서 다운로드되어 로컬에 설정됩니다.

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

• 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. SAML Assertions에 사용할 속성을 설정하세요. 이 속성들은 Mattermost에서 사용자 정보를 업데이트하는 데 사용됩니다. 이메일과 사용자 이름 속성은 필수이며, 이전에 ADFS에 입력한 값과 일치해야 합니다. 자세한 내용은 SAML 구성 설정 문서 를 참조하세요.

Mattermost 3.3 이하 버전에서는 이름과 성 속성도 필수입니다.

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 기반 인증으로 전환한 후 SAML 자격 증명으로 로그인하여 전환을 완료하세요.

마이그레이션 방법에 대해 사용자들에게 공지하는 것도 권장합니다.

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

자주 묻는 질문

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

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

Id 속성으로 구성하면 기존 사용자의 정보가 노출되지 않고 새 사용자가 동일한 이메일 주소를 재사용할 수 있습니다. 예를 들어, joe.smith@mattermost.com 이메일을 사용하던 직원이 퇴사한 후, 새로운 직원 Joe Smith가 동일한 이메일을 사용할 수 있습니다. 또한 사용자의 이름이 변경되어 이메일을 업데이트해야 할 때도 유용합니다.

이 프로세스는 이메일 바인딩과의 하위 호환성을 고려하여 설계되었습니다. 아래는 신규 계정 생성 및 구성 이후 로그인하는 계정에 적용되는 절차입니다:

• SAML로 인증된 사용자는 Id Attribute가 구성된 경우 해당 Id Attribute로 SAML 서비스 사용자에 바인딩되며, 구성되지 않은 경우 SAML에서 받은 이메일로 바인딩됩니다.

• 사용자가 로그인 시도 시 SAML 서버가 유효한 인증을 반환하면, 서버는 SAML 인증의 “Id” 필드를 사용하여 사용자를 검색합니다.

• 해당 ID에 바인딩된 사용자가 이미 존재하면, 해당 사용자로 로그인합니다.

• 해당 ID에 바인딩된 사용자가 없으면, 이메일을 기준으로 사용자를 검색합니다.

• 이메일에 바인딩된 사용자가 존재하면, 이메일로 로그인한 후 인증 데이터를 이메일 대신 ID로 업데이트합니다.

• ID 또는 이메일에 바인딩된 사용자가 존재하지 않으면, ID로 SAML 계정에 바인딩된 새로운 Mattermost 계정을 생성하고 사용자가 로그인할 수 있도록 합니다.

참고

기존 계정은 서버에 로그인할 때까지 업데이트되지 않습니다.

Microsoft ADFS를 통한 SAML에서 통합 Windows 인증(IWA) 구성이 가능한가요?

네. IWA는 브라우저에서 지원되며, 2019년 2분기(iOS 및 Android 모바일 앱 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 연락처 목록과 같은 리소스에 접근할 수 있도록 허용합니다. OAuth 2.0은 인증 자체를 다루지 않습니다.

OpenID Connect는 OAuth 2.0을 기반으로 하며, 인증을 지원하여 직접적인 SSO가 가능합니다.

SAML은 OpenID Connect와 유사하지만, 주로 엔터프라이즈 환경에서 사용됩니다. OpenID Connect는 일반적으로 소비자 웹사이트나 웹/모바일 앱에서 더 많이 사용됩니다.

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

SAML을 AD/LDAP과 동기화하는 방법을 설정하세요.

SAML 로그인 설정 외에도, 선택적으로 SAML 계정을 AD/LDAP과 동기화하도록 구성할 수 있습니다. 구성 시 다음과 같은 동작이 이루어집니다:

• Mattermost는 AD/LDAP에서 관련 계정 정보를 조회하고, 속성(이름, 성, 닉네임) 변경 사항을 기반으로 SAML 계정을 업데이트합니다.

• AD/LDAP에서 비활성화된 계정은 Mattermost에서도 비활성화되며, 속성 동기화 시 해당 계정의 활성 세션이 해제됩니다.

SAML을 AD/LDAP과 동기화하려면 다음을 수행하세요:

1. System Console > Authentication > SAML 2.0 으로 이동한 후, Enable Synchronizing SAML Accounts With AD/LDAP 를 true 로 설정하세요.

2. System Console > Authentication > AD/LDAP 로 이동한 후, 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 서버와 연결하려면 configuration settings documentation 를 참조하여 나머지 AD/LDAP 설정을 구성하세요.

• AD/LDAP 로그인을 활성화하지 않으려면 System Console > Authentication > AD/LDAP 으로 이동한 후 Enable sign-in with AD/LDAP 을 false 로 설정하세요.

5. Mattermost가 SAML 사용자 계정을 AD/LDAP과 동기화하는 빈도를 지정하려면 System Console > Authentication > AD/LDAP 으로 이동한 후 Synchronization Interval 을 분 단위로 설정하세요. 기본 설정은 60분입니다. 계정을 비활성화한 후 즉시 동기화하려면 AD/LDAP Synchronize Now 를 선택하세요.

6. Mattermost가 AD/LDAP 서버에 성공적으로 연결할 수 있는지 확인하려면 System Console > Authentication > AD/LDAP 으로 이동한 후 AD/LDAP Test 를 선택하세요.

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 으로 이동한 후 AD/LDAP Synchronize Now 를 선택하여 AD/LDAP 동기화를 실행하세요.

4. System Console > Environment > Web Server 로 이동한 후 Purge All Caches 를 다시 선택하여 Mattermost의 모든 캐시를 다시 삭제하세요. 이렇게 하면 Mattermost에서 계정이 다시 활성화됩니다.

참고

사용자가 AD/LDAP에서 비활성화되면 다음 동기화 시 Mattermost에서도 비활성화됩니다. System Console 사용자 목록에서 “비활성화됨”으로 표시되며, 모든 세션이 만료되고 Mattermost에 다시 로그인할 수 없게 됩니다.

사용자가 SAML에서 비활성화되면 AD/LDAP에서 비활성화될 때까지 세션이 만료되지 않습니다. 하지만 Mattermost에 다시 로그인할 수는 없습니다.

참고

SAML과 AD/LDAP의 동기화는 인증을 제어하기 위한 것이 아니라 AD/LDAP에서 이름과 성과 같은 사용자 속성을 가져오기 위해 설계되었습니다.

특히 사용자 필터는 Mattermost에 로그인할 수 있는 사용자를 제어하는 데 사용할 수 없으며, 이는 SAML 서비스 제공자의 그룹 권한으로 제어해야 합니다.

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

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

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

이 프로세스는 SAML 이메일 주소를 AD/LDAP 이메일 주소 데이터로 덮어쓰거나, 구성된 경우 SAML ID 속성을 AD/LDAP ID 속성으로 덮어씁니다. 사용자의 이메일 주소가 변경될 때 새 사용자가 생성되지 않도록 하기 위해 SAML ID 속성과 함께 이 구성을 사용하는 것을 권장합니다.

이 프로세스에서 기존 사용자 계정이 비활성화되지 않도록 하려면, 두 시스템에서 데이터를 내보내고 ID 데이터를 비교하여 SAML ID와 LDAP ID가 일치하는지 확인하세요. Mattermost 내에서 AD/LDAP과 SAML 모두의 ID 속성을 동일한 데이터를 보유하는 필드에 매핑하면 ID도 일치하게 됩니다.

1. 시스템 콘솔 > 인증 > SAML 2.0 > ID 속성 으로 이동하여 SAML ID 속성 을 설정하세요.

2. 시스템 콘솔 > 인증 > SAML 2.0 > SAML 바인딩 데이터를 AD/LDAP 정보로 덮어쓰기 를 true 로 설정하세요.

3. 시스템 콘솔 > 인증 > SAML 2.0 > SAML 계정을 AD/LDAP과 동기화 활성화 를 true 로 설정하세요.

4. 시스템 콘솔 > 인증 > AD/LDAP 으로 이동한 다음 AD/LDAP 지금 동기화 를 선택하여 AD/LDAP 동기화를 실행하세요.