참고

Keycloak 서버가 FIPS 모드로 실행되는 경우 PKCS12 와 JKS 를 사용할 수 없으므로 아카이브 형식 목록에 BCFKS 만 표시됩니다. BCFKS 키 저장소를 내보낸 다음 계속하기 전에 PKCS12 로 변환하세요:

keytool -importkeystore -srckeystore keystore.bcfks -srcstoretype BCFKS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath /path/to/bc-fips-<version>.jar -destkeystore keystore.p12 -deststoretype PKCS12

-providerpath 가 Bouncy Castle FIPS JAR을 가리키도록 지정하세요. keytool 은 원본 및 대상 저장소 비밀번호를 묻습니다. 변환된 keystore.p12 는 아래 Mattermost에서 SAML 구성의 4단계에 있는 추출 명령과 함께 사용할 수 있습니다.

keytool 에는 개인 키만 단독으로 내보내는 명령이 없으므로 키만 따로 내보낼 방법을 찾지 말고 위와 같이 전체 키 저장소를 변환하세요.

다른 방법으로, 키 쌍을 로컬에서 생성하고 인증서만 Keycloak으로 가져오면 키 저장소 변환이 전혀 필요하지 않으며 FIPS 서버와 비 FIPS 서버 모두에서 작동합니다:

openssl req -x509 -newkey rsa:2048 -nodes -days 1095 -subj "/CN=mattermost" -keyout mattermost.key -out mattermost.crt

Mattermost는 암호 구문으로 보호된 개인 키를 읽을 수 없으므로 -nodes 를 유지하세요. -days 의 기본값은 30이므로 명시적으로 설정하세요. -keyout 과 -out 이 없으면 인증서는 표준 출력으로 나가고 개인 키는 구성에 따라 달라지는 기본 파일 이름으로 저장되므로 두 옵션을 유지하세요.

mattermost.crt 만 이 탭의 암호화 키 섹션으로 가져온 다음 아래 4단계에서 두 파일을 모두 업로드하고, 해당 명령이 생성했을 파일을 이미 가지고 있으므로 openssl pkcs12 추출 명령은 건너뜁니다.

다음으로 내보내기 를 클릭하고 다음 값을 업데이트한 다음 keystore.p12 파일을 다운로드합니다.

• 아카이브 형식: PKCS12
• 키 별칭: mattermost
• 키 비밀번호: mattermost
• 저장소 비밀번호: mattermost

8. 클라이언트 스코프 탭으로 이동합니다.

   먼저 이메일, 이름, 성을 위한 미리 정의된 매퍼를 추가합니다.

   1. mattermost-dedicated 를 선택합니다.
   2. 미리 정의된 매퍼 추가 를 클릭합니다.
   3. X500 email, X500 givenName 및 X500 surname 속성을 선택합니다.
   4. 추가 를 클릭합니다.

   다음으로 사용자 이름과 id를 위한 매퍼를 추가합니다.

   1. Add Mapper -> By Configuration -> User Property를 선택합니다.
   2. 이름 을 Username 으로 설정합니다.
   3. 속성 을 username 으로 설정합니다 (대소문자를 구분하며 소문자여야 합니다).
   4. SAML 속성 이름 을 username 으로 설정합니다.
   5. 저장 을 선택합니다.

   

   6. 위 단계를 반복하고 id 의 커스텀 속성을 사용하여 ID 속성을 생성합니다.

   

완료되면 매퍼는 다음과 같아야 합니다:

9. Keycloak에서 메타데이터 URL 가져오기:

   1. Realm 내에서 Realm Settings 를 선택합니다.
   2. 일반 탭 하단에 SAML 2.0 Identity Provider Metadata 엔드포인트가 표시됩니다. 마우스 오른쪽 버튼으로 클릭하여 이 URL을 복사합니다. 다음 단계를 위해 저장합니다.

   

Mattermost에서 SAML 구성#

1. Mattermost 시스템 콘솔 에서 Authentication > SAML 로 이동합니다.

2. ID 공급자 메타데이터 URL 을 위 단계에서 복사한 값으로 설정하고 IdP에서 SAML 메타데이터 가져오기 를 선택합니다. 메타데이터 가져오기는 Keycloak 구성과 관련된 필드를 채웁니다.

   이 가져오기에 문제가 있으면 mattermost.log 파일에서 자세한 정보를 확인할 수 있습니다. 디버그 로깅을 활성화한 후 다시 시도합니다.

   

3. 다음 필드를 설정합니다:

   • 서명 검증: false
   • 서비스 제공자 로그인 URL: http://your-mattermost-url.com/login/sso/saml
   • 서비스 제공자 식별자: mattermost

   서비스 제공자 식별자는 두 번째 Keycloak 단계에서 구성한 클라이언트 ID 와 일치합니다.

   

4. Keycloak 구성의 6단계에서 다운로드한 키를 사용하여 암호화를 구성합니다.

   1. .p12 파일에서 .crt 파일을 생성합니다.

   openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.crt -nodes -legacy
   

   2. .p12 파일에서 .key 파일을 생성합니다.

   openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.key -nodes -nocerts -legacy
   

   3. Mattermost 시스템 콘솔 내에서 이 두 파일을 업로드합니다. 업로드 를 선택해야 합니다.

   • 서비스 제공자 개인 키: mattermost.key
   • 서비스 제공자 개인 인증서: mattermost.crt
   • 요청 서명: true
   • 서명 알고리즘: RSAwithSHA256
   • 정규화 알고리즘: Exclusive XML Canonicalization 1.0 (omits comments)

   

5. Mattermost에서 사용자 정보를 업데이트할 SAML 어설션의 속성을 설정합니다.

   아래 속성은 위 7단계와 8단계에서 가져온 것입니다. 이 값들은 Keycloak 내에서 SAML 속성 이름 이어야 합니다. 자세한 내용은 SAML 구성 설정 문서를 참조하세요.

   • 이메일 속성: email
   • 사용자 이름 속성: username
   • Id 속성: id

   

6. 저장 을 선택합니다.

SAML이 올바르게 작동하는지 확인하려면 Mattermost에서 로그아웃하거나 새 시크릿 브라우저 창에서 Mattermost를 열고 로그인 페이지에서 SAML로 로그인 을 선택한 다음 기존 Keycloak 계정으로 로그인합니다.

SAML 로그인으로 마이그레이션될 Mattermost의 기존 사용자가 있는 경우 사용자 마이그레이션을 계획하고 그에 따라 사용자를 업데이트하세요.

config.json 을 편집하여 Keycloak용 SAML을 구성할 수도 있습니다. Mattermost 서버를 시작하기 전에 config.json 을 편집하여 SAML 구성 설정을 기반으로 SAML을 활성화합니다. 변경 사항이 적용되려면 Mattermost 서버를 재시작해야 합니다.

Keycloak에서 SAML 사용자를 게스트로 구성#

1. Mattermost에서 System Console > Authentication > SAML 로 이동합니다.

2. 어떤 SAML 사용자가 게스트인지 지정하려면 게스트 속성 을 설정합니다.

   

3. Keycloak 관리 인터페이스에서 게스트를 위한 사용자 속성 매퍼를 추가합니다.

1. 왼쪽(LHS) 메뉴에서 클라이언트 를 선택합니다.

2. 목록에서 mattermost 를 선택합니다.

• 클라이언트 스코프 탭을 선택합니다.
• 스코프 목록에서 mattermost dedicated 를 선택합니다.
• 매퍼 추가 드롭다운을 클릭하고 구성으로 를 선택합니다.
• 열리는 모달에서 사용자 속성 을 선택합니다.
• 표시된 대로 이름, 사용자 속성 및 SAML 속성 이름 값을 추가합니다.

4. Keycloak에서 사용자 세부 정보 아래에 속성을 추가하여 어떤 사용자가 게스트인지 지정합니다.

1. 왼쪽(LHS) 메뉴에서 사용자 를 선택합니다.

2. 원하는 사용자의 사용자 이름을 선택합니다.

3. 속성 탭을 선택하고 + 속성 추가 를 선택합니다.

4. 키와 값을 추가합니다.

SAML 로그인 구성 외에도 선택적으로 SAML 계정을 AD/LDAP와 동기화하도록 구성할 수 있습니다. 구성 시:

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

AD/LDAP와 SAML 동기화를 구성하려면:

1. System Console > Authentication > SAML 2.0 으로 이동한 다음 AD/LDAP와 SAML 계정 동기화 활성화 를 true 로 설정합니다.

2. System Console > Authentication > AD/LDAP 로 이동하여 AD/LDAP 마법사를 열고 연결 설정 섹션으로 이동한 다음 AD/LDAP와 동기화 활성화 를 true 로 설정합니다.

3. 동기화 시 게스트 사용자를 무시하려면 System Console > Authentication > SAML 2.0 으로 이동한 다음 AD/LDAP와 동기화할 때 게스트 사용자 무시 를 true 로 설정합니다.

4. 구성 설정 문서에 따라 나머지 AD/LDAP 설정을 지정하여 Mattermost를 AD/LDAP 서버와 연결합니다.

   AD/LDAP 로그인을 활성화하지 않으려면 System Console > Authentication > AD/LDAP 마법사로 이동하고 연결 설정 섹션으로 이동한 다음 AD/LDAP로 로그인 활성화 를 false 로 설정합니다.

5. Mattermost가 SAML 사용자 계정을 AD/LDAP와 얼마나 자주 동기화하는지 지정하려면 System Console > Authentication > AD/LDAP 마법사로 이동하고 동기화 성능 섹션으로 이동한 다음 동기화 간격 을 분 단위로 설정합니다. 기본 설정은 60분입니다. 계정 비활성화 후 즉시 동기화하려면 동기화 기록 섹션으로 이동하고 AD/LDAP 지금 동기화 를 선택합니다.

6. Mattermost가 AD/LDAP 서버에 성공적으로 연결할 수 있는지 확인하려면 System Console > Authentication > AD/LDAP 마법사로 이동하고 연결 설정 섹션으로 이동한 다음 연결 테스트 를 선택합니다.

AD/LDAP와의 동기화가 활성화되면 사용자 속성이 이메일 주소를 기반으로 AD/LDAP와 동기화됩니다. 주어진 이메일 주소를 가진 사용자가 AD/LDAP 계정을 가지지 않으면 다음 AD/LDAP 동기화 시 Mattermost에서 비활성화됩니다.

계정을 다시 활성화하려면:

1. AD/LDAP 서버에 사용자를 추가합니다.
2. System Console > Environment > Web Server 로 이동하여 모든 캐시 삭제 를 선택하여 Mattermost의 모든 캐시를 지웁니다.
3. System Console > Authentication > AD/LDAP 마법사로 이동하여 동기화 기록 섹션으로 이동한 다음 AD/LDAP 지금 동기화 를 선택하여 AD/LDAP 동기화를 실행합니다.
4. System Console > Environment > Web Server 로 이동하여 모든 캐시 삭제 를 다시 선택하여 Mattermost의 모든 캐시를 다시 지웁니다. 이렇게 하면 Mattermost에서 계정이 다시 활성화됩니다.

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

AD/LDAP 데이터로 SAML 데이터 재정의#

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

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

이 프로세스에서 기존 사용자 계정이 비활성화되지 않도록 하려면 두 시스템에서 데이터를 내보내고 ID 데이터를 비교하여 SAML ID가 LDAP ID와 일치하는지 확인하세요. Mattermost 내에서 AD/LDAP와 SAML 모두에 대한 ID 속성을 동일한 데이터를 보유하는 필드에 매핑하면 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 마법사로 이동하고 동기화 기록 섹션으로 이동한 다음 AD/LDAP 지금 동기화 를 선택하여 AD/LDAP 동기화를 실행합니다.

SAML에서 지원되는 암호화 옵션은 무엇입니까?#

인증 구성 설정 문서에서 지원되는 SAML 암호화 방법을 참고하세요.

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

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

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

이 프로세스는 이메일 바인딩과의 하위 호환성을 위해 설계되었습니다. 다음은 새 계정 생성 시와 구성 후 로그인하는 계정에 적용되는 프로세스입니다.

• SAML로 인증된 사용자는 Id 속성(구성된 경우)을 사용하거나 SAML에서 받은 이메일을 통해 SAML 서비스 사용자에 바인딩됩니다.
• 사용자가 로그인을 시도하고 SAML 서버가 유효한 인증으로 응답하면 서버는 SAML 인증의 "Id" 필드를 사용하여 사용자를 검색합니다.
• 해당 ID에 바인딩된 사용자가 이미 존재하면 해당 사용자로 로그인됩니다.
• 해당 ID에 바인딩된 사용자가 존재하지 않으면 이메일을 기반으로 검색합니다.
• 이메일에 바인딩된 사용자가 존재하면 이메일로 로그인하고 인증 데이터를 이메일 대신 ID로 업데이트합니다.
• ID 또는 이메일에 바인딩된 사용자가 존재하지 않으면 ID로 SAML 계정에 바인딩된 새 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 공급자(Identity Provider, 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 브라우저 확장 프로그램 사용), 내 각 요소의 Name 속성을 확인하세요.
• 각 Mattermost 속성 필드를 어설션에 있는 정확한 Name 값(네임스페이스 접두사 포함)으로 설정하거나, Mattermost에서 사용할 짧은 이름으로 클레임을 발행하도록 IdP를 재구성하세요.

Microsoft ADFS를 통한 SAML을 통합 Windows 인증(IWA)으로 구성할 수 있습니까?#

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

그러나 IWA는 Electron의 제한으로 인해 Mattermost 데스크톱 앱에서는 지원되지 않습니다. 해결 방법으로 데스크톱 앱처럼 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에서 자세히 알아보세요.

:start-after: :nosearch:

7. 키 탭으로 이동합니다.

• 클라이언트 서명 필요: 꺼짐

• 어설션 암호화: 켜짐

  1. 생성 을 클릭합니다.
  2. private.key 파일을 다운로드합니다.
  3. 확인 을 클릭합니다.

  

  경고

위에 표시된 대로 클라이언트 서명 필요 를 꺼진 상태로 두세요. 아래 Mattermost 섹션의 4단계에서 요청 서명 을 활성화하면 Mattermost는 인증 요청에 서명하지만, Keycloak은 이 탭에서 Mattermost 서비스 제공자 인증서를 서명 키로 함께 가져온 경우에만 해당 서명을 검증합니다. Mattermost 서비스 제공자 인증서를 가져오지 않고 클라이언트 서명 필요 를 켜면 Keycloak이 Mattermost의 인증 요청을 거부합니다.

참고

Keycloak 서버가 FIPS 모드로 실행되는 경우 PKCS12 와 JKS 를 사용할 수 없으므로 아카이브 형식 목록에 BCFKS 만 표시됩니다. BCFKS 키 저장소를 내보낸 다음 계속하기 전에 PKCS12 로 변환하세요:

keytool -importkeystore -srckeystore keystore.bcfks -srcstoretype BCFKS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath /path/to/bc-fips-<version>.jar -destkeystore keystore.p12 -deststoretype PKCS12

-providerpath 가 Bouncy Castle FIPS JAR을 가리키도록 지정하세요. keytool 은 원본 및 대상 저장소 비밀번호를 묻습니다. 변환된 keystore.p12 는 아래 Mattermost에서 SAML 구성의 4단계에 있는 추출 명령과 함께 사용할 수 있습니다.

keytool 에는 개인 키만 단독으로 내보내는 명령이 없으므로 키만 따로 내보낼 방법을 찾지 말고 위와 같이 전체 키 저장소를 변환하세요.

다른 방법으로, 키 쌍을 로컬에서 생성하고 인증서만 Keycloak으로 가져오면 키 저장소 변환이 전혀 필요하지 않으며 FIPS 서버와 비 FIPS 서버 모두에서 작동합니다:

openssl req -x509 -newkey rsa:2048 -nodes -days 1095 -subj "/CN=mattermost" -keyout mattermost.key -out mattermost.crt

Mattermost는 암호 구문으로 보호된 개인 키를 읽을 수 없으므로 -nodes 를 유지하세요. -days 의 기본값은 30이므로 명시적으로 설정하세요. -keyout 과 -out 이 없으면 인증서는 표준 출력으로 나가고 개인 키는 구성에 따라 달라지는 기본 파일 이름으로 저장되므로 두 옵션을 유지하세요.

mattermost.crt 만 이 탭의 암호화 키 섹션으로 가져온 다음 아래 4단계에서 두 파일을 모두 업로드하고, 해당 명령이 생성했을 파일을 이미 가지고 있으므로 openssl pkcs12 추출 명령은 건너뜁니다.

다음으로 내보내기 를 클릭하고 다음 값을 업데이트한 다음 keystore.p12 파일을 다운로드합니다.

• 아카이브 형식: PKCS12
• 키 별칭: mattermost
• 키 비밀번호: mattermost
• 저장소 비밀번호: mattermost

8. 클라이언트 스코프 탭으로 이동합니다.

   먼저 이메일, 이름, 성을 위한 미리 정의된 매퍼를 추가합니다.

   1. mattermost-dedicated 를 선택합니다.
   2. 미리 정의된 매퍼 추가 를 클릭합니다.
   3. X500 email, X500 givenName 및 X500 surname 속성을 선택합니다.
   4. 추가 를 클릭합니다.

   다음으로 사용자 이름과 id를 위한 매퍼를 추가합니다.

   1. Add Mapper -> By Configuration -> User Property를 선택합니다.
   2. 이름 을 Username 으로 설정합니다.
   3. 속성 을 username 으로 설정합니다 (대소문자를 구분하며 소문자여야 합니다).
   4. SAML 속성 이름 을 username 으로 설정합니다.
   5. 저장 을 선택합니다.

   

   6. 위 단계를 반복하고 id 의 커스텀 속성을 사용하여 ID 속성을 생성합니다.

   

완료되면 매퍼는 다음과 같아야 합니다:

9. Keycloak에서 메타데이터 URL 가져오기:

   1. Realm 내에서 Realm Settings 를 선택합니다.
   2. 일반 탭 하단에 SAML 2.0 Identity Provider Metadata 엔드포인트가 표시됩니다. 마우스 오른쪽 버튼으로 클릭하여 이 URL을 복사합니다. 다음 단계를 위해 저장합니다.

   

Mattermost에서 SAML 구성#

1. Mattermost 시스템 콘솔 에서 Authentication > SAML 로 이동합니다.

2. ID 공급자 메타데이터 URL 을 위 단계에서 복사한 값으로 설정하고 IdP에서 SAML 메타데이터 가져오기 를 선택합니다. 메타데이터 가져오기는 Keycloak 구성과 관련된 필드를 채웁니다.

   이 가져오기에 문제가 있으면 mattermost.log 파일에서 자세한 정보를 확인할 수 있습니다. 디버그 로깅을 활성화한 후 다시 시도합니다.

   

3. 다음 필드를 설정합니다:

   • 서명 검증: false
   • 서비스 제공자 로그인 URL: http://your-mattermost-url.com/login/sso/saml
   • 서비스 제공자 식별자: mattermost

   서비스 제공자 식별자는 두 번째 Keycloak 단계에서 구성한 클라이언트 ID 와 일치합니다.

   

4. Keycloak 구성의 6단계에서 다운로드한 키를 사용하여 암호화를 구성합니다.

   1. .p12 파일에서 .crt 파일을 생성합니다.

   openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.crt -nodes -legacy
   

   2. .p12 파일에서 .key 파일을 생성합니다.

   openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.key -nodes -nocerts -legacy
   

   3. Mattermost 시스템 콘솔 내에서 이 두 파일을 업로드합니다. 업로드 를 선택해야 합니다.

   • 서비스 제공자 개인 키: mattermost.key
   • 서비스 제공자 개인 인증서: mattermost.crt
   • 요청 서명: true
   • 서명 알고리즘: RSAwithSHA256
   • 정규화 알고리즘: Exclusive XML Canonicalization 1.0 (omits comments)

   

5. Mattermost에서 사용자 정보를 업데이트할 SAML 어설션의 속성을 설정합니다.

   아래 속성은 위 7단계와 8단계에서 가져온 것입니다. 이 값들은 Keycloak 내에서 SAML 속성 이름 이어야 합니다. 자세한 내용은 SAML 구성 설정 문서를 참조하세요.

   • 이메일 속성: email
   • 사용자 이름 속성: username
   • Id 속성: id

   

6. 저장 을 선택합니다.

SAML이 올바르게 작동하는지 확인하려면 Mattermost에서 로그아웃하거나 새 시크릿 브라우저 창에서 Mattermost를 열고 로그인 페이지에서 SAML로 로그인 을 선택한 다음 기존 Keycloak 계정으로 로그인합니다.

SAML 로그인으로 마이그레이션될 Mattermost의 기존 사용자가 있는 경우 사용자 마이그레이션을 계획하고 그에 따라 사용자를 업데이트하세요.

config.json 을 편집하여 Keycloak용 SAML을 구성할 수도 있습니다. Mattermost 서버를 시작하기 전에 config.json 을 편집하여 SAML 구성 설정을 기반으로 SAML을 활성화합니다. 변경 사항이 적용되려면 Mattermost 서버를 재시작해야 합니다.

Keycloak에서 SAML 사용자를 게스트로 구성#

1. Mattermost에서 System Console > Authentication > SAML 로 이동합니다.

2. 어떤 SAML 사용자가 게스트인지 지정하려면 게스트 속성 을 설정합니다.

   

3. Keycloak 관리 인터페이스에서 게스트를 위한 사용자 속성 매퍼를 추가합니다.

1. 왼쪽(LHS) 메뉴에서 클라이언트 를 선택합니다.

2. 목록에서 mattermost 를 선택합니다.

• 클라이언트 스코프 탭을 선택합니다.
• 스코프 목록에서 mattermost dedicated 를 선택합니다.
• 매퍼 추가 드롭다운을 클릭하고 구성으로 를 선택합니다.
• 열리는 모달에서 사용자 속성 을 선택합니다.
• 표시된 대로 이름, 사용자 속성 및 SAML 속성 이름 값을 추가합니다.

4. Keycloak에서 사용자 세부 정보 아래에 속성을 추가하여 어떤 사용자가 게스트인지 지정합니다.

1. 왼쪽(LHS) 메뉴에서 사용자 를 선택합니다.

2. 원하는 사용자의 사용자 이름을 선택합니다.

3. 속성 탭을 선택하고 + 속성 추가 를 선택합니다.

4. 키와 값을 추가합니다.

SAML 로그인 구성 외에도 선택적으로 SAML 계정을 AD/LDAP와 동기화하도록 구성할 수 있습니다. 구성 시:

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

AD/LDAP와 SAML 동기화를 구성하려면:

1. System Console > Authentication > SAML 2.0 으로 이동한 다음 AD/LDAP와 SAML 계정 동기화 활성화 를 true 로 설정합니다.

2. System Console > Authentication > AD/LDAP 로 이동하여 AD/LDAP 마법사를 열고 연결 설정 섹션으로 이동한 다음 AD/LDAP와 동기화 활성화 를 true 로 설정합니다.

3. 동기화 시 게스트 사용자를 무시하려면 System Console > Authentication > SAML 2.0 으로 이동한 다음 AD/LDAP와 동기화할 때 게스트 사용자 무시 를 true 로 설정합니다.

4. 구성 설정 문서에 따라 나머지 AD/LDAP 설정을 지정하여 Mattermost를 AD/LDAP 서버와 연결합니다.

   AD/LDAP 로그인을 활성화하지 않으려면 System Console > Authentication > AD/LDAP 마법사로 이동하고 연결 설정 섹션으로 이동한 다음 AD/LDAP로 로그인 활성화 를 false 로 설정합니다.

5. Mattermost가 SAML 사용자 계정을 AD/LDAP와 얼마나 자주 동기화하는지 지정하려면 System Console > Authentication > AD/LDAP 마법사로 이동하고 동기화 성능 섹션으로 이동한 다음 동기화 간격 을 분 단위로 설정합니다. 기본 설정은 60분입니다. 계정 비활성화 후 즉시 동기화하려면 동기화 기록 섹션으로 이동하고 AD/LDAP 지금 동기화 를 선택합니다.

6. Mattermost가 AD/LDAP 서버에 성공적으로 연결할 수 있는지 확인하려면 System Console > Authentication > AD/LDAP 마법사로 이동하고 연결 설정 섹션으로 이동한 다음 연결 테스트 를 선택합니다.

AD/LDAP와의 동기화가 활성화되면 사용자 속성이 이메일 주소를 기반으로 AD/LDAP와 동기화됩니다. 주어진 이메일 주소를 가진 사용자가 AD/LDAP 계정을 가지지 않으면 다음 AD/LDAP 동기화 시 Mattermost에서 비활성화됩니다.

계정을 다시 활성화하려면:

1. AD/LDAP 서버에 사용자를 추가합니다.
2. System Console > Environment > Web Server 로 이동하여 모든 캐시 삭제 를 선택하여 Mattermost의 모든 캐시를 지웁니다.
3. System Console > Authentication > AD/LDAP 마법사로 이동하여 동기화 기록 섹션으로 이동한 다음 AD/LDAP 지금 동기화 를 선택하여 AD/LDAP 동기화를 실행합니다.
4. System Console > Environment > Web Server 로 이동하여 모든 캐시 삭제 를 다시 선택하여 Mattermost의 모든 캐시를 다시 지웁니다. 이렇게 하면 Mattermost에서 계정이 다시 활성화됩니다.

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

AD/LDAP 데이터로 SAML 데이터 재정의#

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

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

이 프로세스에서 기존 사용자 계정이 비활성화되지 않도록 하려면 두 시스템에서 데이터를 내보내고 ID 데이터를 비교하여 SAML ID가 LDAP ID와 일치하는지 확인하세요. Mattermost 내에서 AD/LDAP와 SAML 모두에 대한 ID 속성을 동일한 데이터를 보유하는 필드에 매핑하면 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 마법사로 이동하고 동기화 기록 섹션으로 이동한 다음 AD/LDAP 지금 동기화 를 선택하여 AD/LDAP 동기화를 실행합니다.

SAML에서 지원되는 암호화 옵션은 무엇입니까?#

인증 구성 설정 문서에서 지원되는 SAML 암호화 방법을 참고하세요.

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

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

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

이 프로세스는 이메일 바인딩과의 하위 호환성을 위해 설계되었습니다. 다음은 새 계정 생성 시와 구성 후 로그인하는 계정에 적용되는 프로세스입니다.

• SAML로 인증된 사용자는 Id 속성(구성된 경우)을 사용하거나 SAML에서 받은 이메일을 통해 SAML 서비스 사용자에 바인딩됩니다.
• 사용자가 로그인을 시도하고 SAML 서버가 유효한 인증으로 응답하면 서버는 SAML 인증의 "Id" 필드를 사용하여 사용자를 검색합니다.
• 해당 ID에 바인딩된 사용자가 이미 존재하면 해당 사용자로 로그인됩니다.
• 해당 ID에 바인딩된 사용자가 존재하지 않으면 이메일을 기반으로 검색합니다.
• 이메일에 바인딩된 사용자가 존재하면 이메일로 로그인하고 인증 데이터를 이메일 대신 ID로 업데이트합니다.
• ID 또는 이메일에 바인딩된 사용자가 존재하지 않으면 ID로 SAML 계정에 바인딩된 새 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 공급자(Identity Provider, 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 브라우저 확장 프로그램 사용), 내 각 요소의 Name 속성을 확인하세요.
• 각 Mattermost 속성 필드를 어설션에 있는 정확한 Name 값(네임스페이스 접두사 포함)으로 설정하거나, Mattermost에서 사용할 짧은 이름으로 클레임을 발행하도록 IdP를 재구성하세요.

Microsoft ADFS를 통한 SAML을 통합 Windows 인증(IWA)으로 구성할 수 있습니까?#

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

그러나 IWA는 Electron의 제한으로 인해 Mattermost 데스크톱 앱에서는 지원되지 않습니다. 해결 방법으로 데스크톱 앱처럼 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에서 자세히 알아보세요.

:start-after: :nosearch: