AD/LDAP 설정

개요

Mattermost는 Microsoft AD/LDAP(구 Active Directory/LDAP)와의 "Same Sign-On"을 제공합니다. 온프레미스 AD/LDAP 배포 환경에서 쓰던 자격 증명을 Mattermost에서 그대로 재사용할 수 있으며, 다중 인증을 선택적으로 함께 적용할 수 있습니다.

AD/LDAP는 조직 네트워크의 사용자 인증·인가 정보를 저장하는 서비스입니다. AD/LDAP 시스템을 Mattermost와 연동하면 사용자는 새 자격 증명을 만들지 않고도 Mattermost에 로그인할 수 있습니다. 사용자 계정은 AD/LDAP에서 관리되며, 변경 사항은 Mattermost로 동기화됩니다.

Mattermost는 시스템 콘솔에서 단계별 AD/LDAP 설정 마법사를 제공합니다. 이 마법사는 설정 과정을 섹션별로 안내하고 각 단계에서 점진적으로 테스트할 수 있게 해 주므로, 다음 단계로 넘어가기 전에 각 부분이 올바르게 동작하는지 확인할 수 있습니다.

AD/LDAP를 Mattermost와 연동할 때의 이점은 다음과 같습니다.

• 싱글 사인온. 사용자가 AD/LDAP 자격 증명으로 Mattermost에 로그인할 수 있습니다.
• 중앙 집중식 ID 관리. Mattermost 계정에 이름, 성, 이메일, 사용자 이름 등 AD/LDAP의 사용자 정보를 표시할 수 있습니다.
• 자동 계정 프로비저닝. 사용자가 AD/LDAP 자격 증명으로 처음 로그인할 때 Mattermost 사용자 계정이 자동으로 생성됩니다.
• 그룹을 Mattermost의 사전 정의된 역할에 동기화. AD/LDAP 그룹 동기화를 통해 팀과 채널 역할을 그룹에 할당합니다.
• 관리자 관리 방식의 컴플라이언스 정합성. AD/LDAP 필터를 사용해 시스템 콘솔에서 Mattermost 관리자 접근 권한을 관리합니다.

설치 전 참고 사항

중첩 보안 그룹과 함께 AD/LDAP를 사용하는 경우, 트리를 평탄화해 하나의 보안 그룹으로 집계한 뒤 Mattermost에 매핑하도록 PowerShell 스크립트 등을 작성해야 합니다.

AD/LDAP 설정을 준비할 때 다음 사항을 반드시 확인하기를 강력히 권장합니다.

속성 이름과 대소문자 구분:

• AD/LDAP와 Mattermost 설정 모두에서 속성 이름은 대소문자를 구분합니다.
• AD/LDAP 클레임 규칙의 속성 이름이 Mattermost가 기대하는 속성 이름과 정확히 일치하는지 확인하세요. 대소문자가 다르면 문제가 발생합니다.

필수 속성:

• SAML 어설션에서 사용자를 식별하려면 NameID 요소가 필요합니다.
• 필수 속성(예: Email, Username, FirstName, LastName)은 모두 포함되어야 하며 올바르게 매핑되어야 합니다.

NameID에 사용할 안정적인 고유 식별자 선택 방법:

• NameID에 안정적이고 고유한 식별자(EmployeeID 또는 ObjectGUID)를 사용하면 시간이 지나면서 사용자 정보가 바뀌는 경우(예: LastName이나 Email 변경)에 생길 수 있는 문제를 예방할 수 있습니다.
• AD에 안정적이고 고유한 속성이 없어 시간이 지나면 바뀔 수 있는 속성을 사용하면 나중에 문제가 생길 수 있습니다.

시작하기

AD/LDAP를 설정하는 방법은 두 가지입니다.

1. 시스템 콘솔 설정 마법사로 AD/LDAP 설정

   • 워크스페이스에 로그인해 이메일과 비밀번호로 새 계정을 만듭니다. 가장 먼저 생성된 사용자이므로 시스템 관리자 역할이 부여됩니다.
   • 이어서 AD/LDAP 설정 마법사로 단계별로 AD/LDAP를 설정하고 각 섹션을 테스트한 뒤, 시스템 관리자 계정을 AD/LDAP 로그인 방식으로 전환합니다.

2. config.json을 편집해 AD/LDAP 설정

   • AD/LDAP 설정 문서를 참고해 config.json을 편집하고 AD/LDAP를 활성화합니다. Mattermost에 로그인할 때 유효한 AD/LDAP 자격 증명으로 처음 로그인한 사용자에게 시스템 관리자 역할이 부여됩니다.

AD/LDAP 로그인 설정

1. 이메일 인증으로 시스템 관리자 계정을 만듭니다.

   • 새 워크스페이스를 만들고 이메일과 비밀번호로 계정을 생성하면, 가장 먼저 생성된 계정이므로 자동으로 시스템 관리자 역할이 부여됩니다. 다른 계정에 이 역할을 부여할 수도 있습니다.

2. 설정 마법사로 AD/LDAP를 설정합니다.

   • System Console > Authentication > AD/LDAP(시스템 콘솔 > 인증 > AD/LDAP)로 이동해 AD/LDAP 설정 마법사를 엽니다. 마법사는 사이드바로 이동할 수 있는 섹션들로 구성되어 있습니다.
     • Connection Settings: 서버 연결 정보를 설정합니다
     • User Filters: 사용자 식별과 필터링을 설정합니다
     • Account sync: AD/LDAP 속성을 Mattermost 사용자 필드에 매핑합니다
     • Group Synchronization: 그룹 설정과 그룹 속성을 설정합니다(LDAP 그룹을 사용하는 경우)
     • Sync Performance: 동기화 주기와 성능 설정을 조정합니다
     • Sync History: 동기화 상태를 확인하고 수동으로 동기화를 실행합니다
   • 각 섹션에는 다음 단계로 넘어가기 전에 설정을 검증할 수 있는 테스트 버튼이 있습니다. 이런 점진적 테스트는 설정 과정 초기에 문제를 발견하고 해결하는 데 도움이 됩니다.

3. AD/LDAP 로그인이 활성화되었는지 확인합니다.

   • 마법사로 AD/LDAP 설정을 마친 뒤, 사용자가 AD/LDAP 자격 증명으로 로그인할 수 있는지 확인합니다.

4. 시스템 관리자 계정을 이메일 인증에서 AD/LDAP 인증으로 전환합니다.

   • 프로필로 이동해 Security > Sign-in Method > Switch to AD/LDAP(보안 > 로그인 방식 > AD/LDAP로 전환)를 선택하고 AD/LDAP 자격 증명으로 로그인해 전환을 완료합니다.

5. (선택) 인증을 AD/LDAP로만 제한합니다.

   • System Console > Authentication > Email로 이동해 Enable sign-in with email과 Enable sign-in with username을 모두 false로 설정합니다.
   • 그런 다음 Save를 선택해 변경 사항을 저장합니다. 이렇게 하면 AD/LDAP만 유일한 로그인 옵션으로 남습니다.

6. (선택) 시스템 콘솔에서 First Name Attribute와 Last Name Attribute를 설정한 경우.

   • System Console > Site Configuration > Users and Teams로 이동해 Teammate Name Display를 Show first and last name으로 설정합니다. 사용자 경험을 위해 권장하는 설정입니다.

AD/LDAP 동기화 설정

AD/LDAP 로그인을 설정하는 것에 더해 AD/LDAP 동기화도 설정할 수 있습니다. 동기화가 실행되면 Mattermost는 AD/LDAP에 관련 계정 정보를 질의하고, 속성(이름, 성, 닉네임) 변경 사항에 따라 Mattermost 계정을 갱신합니다. AD/LDAP에서 계정이 비활성화되면 Mattermost에서도 해당 사용자가 비활성화되며, 갱신된 속성이 동기화되는 시점에 활성 세션이 모두 취소됩니다.

AD/LDAP 동기화는 이메일에 의존합니다. AD/LDAP 서버의 모든 사용자에게 이메일 주소가 있는지 확인하거나, 없다면 해당 계정이 Mattermost에서 비활성화되도록 하세요.

Mattermost가 사용자 인증에 AD/LDAP를 사용하도록 설정된 경우, 이름, 성, 직책, 닉네임, 이메일, 프로필 사진, 사용자 이름은 API로 변경할 수 없습니다. 이 속성들은 LDAP가 권위 있는 소스여야 합니다.

AD/LDAP 로그인과 함께 AD/LDAP 동기화를 설정하려면 다음과 같이 합니다.

1. System Console > Authentication > AD/LDAP로 이동해 AD/LDAP 마법사를 열고 Connection Settings 섹션으로 이동합니다. Enable Synchronization with AD/LDAP를 true로 설정합니다.
2. Sync Performance 섹션으로 이동해 Synchronization Interval (minutes)를 설정해 Mattermost 계정이 AD/LDAP와 속성을 동기화하는 주기를 지정합니다. 기본값은 60분입니다.

3. Mattermost v10.9부터는 LDAP 동기화 중에 LDAP 그룹의 멤버를 그룹 동기화 팀이나 채널에 자동으로 다시 추가하도록 설정할 수 있습니다. 이전에 제거된 멤버라도 다시 추가됩니다. 이 옵션을 사용하면 협업이 끊기지 않도록 유지하면서 조직별 요구 사항에 대응할 수 있으며, LDAP 그룹 멤버십 변경, 동기화 오류, 표준 그룹 동기화 규칙의 예외 때문에 의도치 않게 제거된 사용자를 매끄럽게 복구할 수 있습니다.

   참고

   mmctl ldap sync 명령이 이 서버 설정보다 우선합니다. 이 설정을 비활성화한 상태에서 --include-removed-members 플래그와 함께 mmctl 명령을 실행하면, LDAP 동기화 중에 제거된 멤버가 다시 추가됩니다.

필터를 사용한 AD/LDAP 로그인 설정

필터를 사용하면 로그인 시 지정한 사용자에게 역할을 부여할 수 있습니다. AD/LDAP 필터 설정에 접근하려면 System Console > Authentication > AD/LDAP로 이동해 AD/LDAP 마법사를 열고 User Filters 섹션으로 이동하세요.

사용자 필터

(선택) 사용자 객체를 검색할 때 사용할 AD/LDAP 필터를 입력합니다. 쿼리로 선택된 사용자만 Mattermost에 접근할 수 있습니다. AD/LDAP에서 비활성화된 사용자를 걸러 내는 쿼리는 (&(objectCategory=Person)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))입니다.

1. System Console > Authentication > AD/LDAP로 이동해 AD/LDAP 마법사를 엽니다.
2. User Filters 섹션으로 이동해 User Filter 필드를 입력합니다.
3. Test Filters 버튼으로 필터가 올바르게 동작하는지 확인합니다.
4. Save를 선택합니다.

사용자가 Mattermost에 접근할 때는 조직 로그인에 사용하는 것과 같은 사용자 이름과 비밀번호로 로그인합니다.

특정 그룹에 속한 사용자를 제외하는 데에도 필터를 사용할 수 있습니다. AD/LDAP에서 그룹을 걸러 내는 쿼리는 (&(memberof=cn=ACME_ALL,ou=Users,dc=sademo,dc=com)(!(memberof=cn=DEV_OPS,ou=Users,dc=sademo,dc=com)))입니다.

게스트 필터

(선택) 게스트 필터를 활성화하면, Mattermost는 AD/LDAP 역할이 게스트이고 Mattermost 워크스페이스에 초대된 외부 사용자를 식별합니다. 이 사용자들은 첫 로그인 즉시 기본 멤버 역할 대신 게스트 역할이 적용됩니다. 덕분에 시스템 콘솔에서 역할을 수동으로 지정할 필요가 없습니다.

이 필터를 제거하거나 변경해도 이미 활성 상태인 게스트는 멤버로 승격되지 않고 게스트 역할을 유지합니다. 게스트는 System Console > User Management에서 승격할 수 있습니다.

1. System Console > Authentication > Guest Access로 이동해 Guest Access를 true로 설정합니다.
2. System Console > Authentication > AD/LDAP로 이동해 AD/LDAP 마법사를 엽니다.
3. User Filters 섹션으로 이동해 Configure additional filters를 펼칩니다.
4. Guest Filter 필드를 입력합니다.
5. Test Filters 버튼으로 필터가 올바르게 동작하는지 확인합니다.
6. Save를 선택합니다.

게스트가 처음 로그인하면 채널에 추가되기 전까지 기본 랜딩 페이지가 표시됩니다.

이 기능에 대한 자세한 내용은 게스트 계정 문서를 참고하세요.

관리자 필터

(선택) 시스템 관리자를 지정하는 데 사용할 AD/LDAP 필터를 입력합니다. 쿼리로 선택된 사용자는 시스템 관리자로 Mattermost 워크스페이스에 접근할 수 있습니다. 기본적으로 시스템 관리자는 Mattermost 시스템 콘솔에 대한 모든 권한을 갖습니다. 이 속성으로 식별된 기존 멤버는 다음 로그인 시 멤버에서 시스템 관리자로 승격됩니다.

여기서 말하는 다음 로그인은 System Console > Session Lengths에 설정된 세션 길이를 기준으로 합니다. 접근 권한을 즉시 제한하려면 System Console > User Management에서 사용자를 수동으로 멤버로 강등하는 것을 권장합니다.

1. System Console > Authentication > AD/LDAP로 이동해 AD/LDAP 마법사를 엽니다.
2. User Filters 섹션으로 이동해 Configure additional filters를 펼칩니다.
3. Enable Admin Filter를 true로 설정합니다.
4. Admin Filter 필드를 입력합니다.
5. Test Filters 버튼으로 필터가 올바르게 동작하는지 확인합니다.
6. Save를 선택합니다.

이 필터를 사용하지 않을 때는 System Console > User Management에서 멤버를 수동으로 승격하거나 강등할 수 있습니다.

여러 도메인을 사용하는 AD/LDAP 배포 설정

여러 도메인을 사용하는 조직은 "포리스트(Forest)" 구성을 통해 여러 도메인을 묶어 Mattermost와 연동할 수 있습니다. 자세한 내용은 Forests as Collections of Domain Controllers that Trust Each Other를 참고하세요.

공통 루트를 공유하지 않는 여러 도메인이 포함된 포리스트 구성에서는 글로벌 카탈로그를 사용해 모든 도메인을 대상으로 검색할 수 있습니다. 이를 위해 config.json을 다음과 같이 수정하세요.

• LdapPort를 389 대신 3268로 설정합니다
• BaseDN을 " "(공백 문자 하나)로 설정합니다

자세한 내용은 Global Catalog and LDAP Searches를 참고하세요.

문제 해결/FAQ

다음은 자주 묻는 질문과 흔한 오류 메시지·문제에 대한 해결 방법입니다. 로그에 오류가 있는지 확인하면 문제의 원인을 파악하는 데 도움이 되므로 먼저 확인하기를 권장합니다.

Test Connection 버튼이 실패하면 연결 문제를 어떻게 해결하나요?

외부 시스템에서 AD/LDAP 사용자 쿼리를 실행해 AD/LDAP 연결 설정이 올바른지 확인하세요. LDAP Connection Test Example을 참고하세요. Mattermost 밖에서는 AD/LDAP 연결이 정상 동작하는 것으로 확인되었다면 다음을 시도해 보세요.

• AD/LDAP 시스템에서 Bind Username 형식을 확인합니다.
• 시스템 콘솔의 AD/LDAP Port와 Connection Security 설정을 확인합니다. (AD/LDAP Port가 389이면 보통 Connection Security는 None이고, 636이면 보통 Connection Security는 TLS입니다.)
• 로그에 x509: certificate signed by unknown authority가 보인다면 중간 SSL 인증서를 설치하거나 LDAP 서버가 전체 인증서 체인을 전송하도록 설정해 보세요.

이 방법들로 해결되지 않으면 지원 팀에 문의하세요.

AD/LDAP를 처음 설정하고 동기화하면 Mattermost에 사용자가 자동으로 생성되나요?

아니요. 각 사용자는 첫 로그인 시에 생성됩니다.

AD/LDAP 동기화를 시도했는데 상태가 완료되지 않고 Pending으로 표시되는 이유는 무엇인가요?

System Console > Authentication > AD/LDAP로 이동해 AD/LDAP 마법사를 열고 Connection Settings 섹션에서 Enable Synchronization with AD/LDAP 설정이 true인지 확인하세요.

문제가 계속되면 Test Filters 버튼을 선택해 사용자 필터의 형식이 올바른지 테스트해 보세요. 올바른 구문 형식에 대한 안내는 이 문서를 참고하세요.

또한 Mattermost에 AD/LDAP 사용자가 최소 한 명은 있어야 동기화가 완료됩니다.

Username Attribute, ID Attribute, Login ID Attribute의 차이는 무엇인가요?

비슷해 보이지만 목적이 다른 세 가지 AD/LDAP 속성이 있습니다.

1. Username Attribute: Mattermost 사용자 인터페이스에서 사용자를 식별하고 멘션하는 데 사용합니다. 예를 들어 Username Attribute가 john.smith로 설정되어 있으면, @john을 입력한 사용자는 자동 완성 목록에서 @john.smith를 보게 되고, @john.smith로 메시지를 게시하면 해당 사용자에게 멘션 알림이 전송됩니다.
2. ID Attribute: Mattermost의 고유 식별자로 사용합니다. ObjectGUID처럼 값이 변하지 않는 AD/LDAP 속성이어야 합니다. 사용자의 ID 속성이 바뀌면 기존 계정과 연결되지 않은 새 Mattermost 계정이 생성됩니다. 사용자가 이미 로그인한 뒤에 이 필드를 변경해야 한다면 mattermost ldap idmigrate mmctl 도구를 사용하세요.
3. Login ID Attribute: Mattermost에 로그인할 때 사용하는 AD/LDAP 서버의 속성입니다. 보통 위의 Username Attribute 필드와 같거나, 사용자가 쉽게 기억할 수 있는 다른 필드를 사용합니다.

사용자를 비활성화하려면 어떻게 하나요?

사용자가 AD/LDAP나 SAML을 통해 Mattermost에 로그인한 적이 있다면, 수동으로 비활성화할지 자동으로 비활성화할지 선택할 수 있습니다.

주요 방법은 세 가지입니다.

1. 사용자 삭제: AD/LDAP 서버에서 사용자를 완전히 제거하면 다음 동기화 때 Mattermost에서도 비활성화됩니다.
2. 사용자 필터: 사용자 필터를 설정해 Mattermost 접근을 허용할 AD/LDAP 사용자 집합만 선택합니다. 누군가 선택된 그룹에서 제거되면 다음 동기화 때 Mattermost에서 비활성화됩니다.
3. 수동 비활성화: System Console > User Management > Users로 이동해 사용자의 역할을 선택한 뒤 Deactivate를 선택합니다. 수동으로 비활성화한 사용자는 다시 로그인하면 스스로 재활성화할 수 있습니다.

AD/LDAP에서 비활성화된 사용자를 걸러 내려면 사용자 필터를 다음과 같이 설정해야 합니다.

(&(objectCategory=Person)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))

특정 그룹에 속한 사용자를 제외하는 데에도 필터를 사용할 수 있습니다. AD/LDAP에서 그룹을 걸러 내는 쿼리는 다음과 같습니다.

(&(memberof=cn=ACME_ALL,ou=Users,dc=sademo,dc=com)

(!(memberof=cn=DEV_OPS,ou=Users,dc=sademo,dc=com)))

위 1번이나 2번 방식으로 Mattermost에서 사용자가 비활성화되면, 해당 사용자의 현재 세션이 모두 취소되어 로그인하거나 Mattermost에 접근할 수 없게 됩니다.

여러 AD/LDAP 서버에 연결할 수 있나요?

현재 여러 AD/LDAP 서버에 연결하는 내장 기능은 없습니다. Mattermost에 연결하기 전에 인스턴스들을 포리스트로 묶어야 합니다. 포럼의 기능 요청에 추천을 남겨 주세요.

로그인할 때 AD/LDAP not available on this server 오류가 표시됩니다

설정 어딘가에 문제가 있다는 뜻입니다. Mattermost 설정에서 AD/LDAP가 활성화되어 있고 설정값이 올바른지 확인하기를 권장합니다.

그래도 문제가 계속되면 지원에 문의해 추가 문제 해결을 받으세요.

User not registered on AD/LDAP server 오류가 표시됩니다

AD/LDAP 서버로 보낸 쿼리가 아무 결과도 반환하지 않았다는 뜻입니다. 다음을 확인하기를 권장합니다.

1. 사용자 자격 증명이 올바르게 입력되었는지 확인하세요. ID Attribute로 설정된 필드로 로그인해야 합니다.
2. AD/LDAP 서버에 해당 사용자 계정이 존재하는지 확인하세요.
3. AD/LDAP 설정값이 올바른지 확인하세요.

그래도 문제가 계속되면 Mattermost 지원에 문의해 추가 문제 해결을 받으세요.

AD/LDAP에서 사용자 계정을 수정했더니 해당 사용자가 Mattermost에 로그인할 수 없습니다

사용자가 AD/LDAP 자격 증명으로 더 이상 Mattermost에 로그인할 수 없다면(예: An account with that email already exists 오류가 표시되거나 로그인 시 새 Mattermost 계정이 생성되는 경우), 해당 계정의 ID Attribute가 변경된 것입니다.

이 문제는 ID Attribute로 사용하는 필드의 값을 이전 값으로 되돌리면 해결할 수 있습니다. 현재 ID Attribute로 가끔 바뀌는 필드(예: 사용자 이름, 결혼 등으로 바뀌는 이메일)를 사용하고 있다면 GUID처럼 변하지 않는 필드로 전환하기를 권장합니다.

이를 위해 Login ID Attribute를 사용자가 로그인에 사용하기 원하는 값(예: 사용자 이름이나 이메일)으로 설정할 수 있습니다.

로그에 LDAP Result Code 4 "Size Limit Exceeded" 오류가 표시됩니다

AD/LDAP 서버 설정에 최대 페이지 크기가 지정되어 있고, Mattermost에서 보낸 쿼리가 그 한도를 초과하는 결과 집합을 반환하고 있다는 뜻입니다.

이 문제를 해결하려면 Mattermost 설정에서 최대 페이지 크기를 AD/LDAP 서버의 한도에 맞춰 설정하세요. 그러면 모든 결과를 한 번의 쿼리로 반환하는 대신, 최대 페이지 크기를 넘지 않는 결과 집합을 순차적으로 반환합니다. 최대 페이지 크기는 1500을 권장합니다.

그래도 오류가 계속된다면 아직 Mattermost에 로그인한 AD/LDAP 사용자가 한 명도 없을 가능성이 큽니다. AD/LDAP 사용자가 최소 한 명은 Mattermost에 로그인했는지 확인한 뒤 동기화를 다시 실행하세요. 그 시점에 오류가 사라질 것입니다.

로그에 Missing NameID Element 오류가 표시됩니다

AD/LDAP 서버 설정이 SAML 어설션에 NameID 요소를 포함하지 않는다는 뜻입니다. SAML 어설션에서 사용자를 식별하려면 NameID 요소가 필요합니다. NameID가 사용자의 이메일 주소처럼 고유한 사용자 식별자, 또는 시간이 지나도 변하지 않는 안정적인 다른 속성에 매핑되어 있는지 확인하세요.

로그에 Username Attribute is Missing 오류가 표시됩니다

SAML 어설션의 Username 속성이 누락되었거나 이름이 잘못되었다는 뜻입니다. 필수 속성이 모두 SAML 어설션에 포함되어 있는지 확인하세요. 속성 이름은 대소문자를 구분하며 Mattermost가 기대하는 값과 정확히 일치해야 합니다. AD/LDAP의 클레임 규칙을 수정해 LDAP 속성을 기대하는 발신 클레임 유형에 올바르게 매핑하고, 대소문자도 정확히 맞추세요(예: UserName이 아니라 Username).

Enter ID 사용자 필터가 보안 그룹을 읽을 수 있나요?

읽을 수 있습니다. 다만 다음을 확인하세요.

• 사용 중인 서비스 계정에 권한이 올바르게 설정되어 있어야 합니다.
• 각 사용자 객체가 해당 보안 그룹의 직접 멤버여야 합니다.

AD/LDAP 동기화 작업이 실패했는지 어떻게 알 수 있나요?

Mattermost는 AD/LDAP 마법사(System Console > Authentication > AD/LDAP)의 Sync History 섹션에서 각 AD/LDAP 동기화 작업의 상태를 제공합니다. 여기에서 갱신된 사용자 수와 작업의 성공·실패 여부를 확인할 수 있습니다.