사전 인증 시크릿

Mattermost v11.11번역일: 2026-09-02원본 보기

Enterprise Advanced 플랜에서 사용할 수 있습니다.

Mattermost 서버 v10.12 및 모바일 v2.32부터, Mattermost 배포는 리버스 프록시를 사용해 데스크톱 및 모바일 요청이 Mattermost 서버에 도달하기 전에 인증 시크릿을 검증할 수 있습니다. 이는 X-Mattermost-Preauth-Secret 헤더를 확인하는 방식으로 보안 계층을 하나 더 추가합니다.

인증 시크릿은 모바일 및 데스크톱 애플리케이션에서만 지원됩니다. 시크릿이 필요한 경우 데스크톱에서는 사용자에게 직접 입력을 요청하고, 모바일에서는 고급 옵션에 시크릿 입력란이 표시됩니다. 웹 브라우저 클라이언트는 이 기능을 지원하지 않습니다.

인증 시크릿 검증에 실패하면 리버스 프록시는 403 상태 코드와 함께 X-Reject-Reason: pre-auth 헤더를 반환해야 합니다. 이 헤더를 통해 모바일 및 데스크톱 애플리케이션이 인증 실패를 정확히 식별하고 사용자에게 적절한 오류 메시지를 제공할 수 있습니다.

중요

인증 헤더를 사용할 수 없는 특정 엔드포인트는 허용 목록에 추가하는 것을 권장합니다. 어떤 엔드포인트가 해당되는지는 인증 구성에 따라 다릅니다.

  • /api/v4/notifications/ack — 알림 확인 기능이 정상 동작하는 데 필요합니다.
  • /static/*, /api/v4/config/client, /login/desktop — SAML, OAuth, OpenID처럼 브라우저로 리디렉션되는 인증 흐름에 필요합니다.

인증 구성에 따라 추가로 필요한 엔드포인트:

  • SAML: /login/sso/saml
  • OpenID: /oauth/{service:[A-Za-z0-9]+}/complete, /oauth/{service:[A-Za-z0-9]+}/login, /oauth/{service:[A-Za-z0-9]+}/mobile_login, /oauth/{service:[A-Za-z0-9]+}/signup
  • OAuth: /api/v3/oauth/{service:[A-Za-z0-9]+}/complete, /signup/{service:[A-Za-z0-9]+}/complete, /login/{service:[A-Za-z0-9]+}/complete

이 엔드포인트들을 허용 목록에 두는 이유는, 외부 아이덴티티 공급자를 거치는 OAuth 리디렉션처럼 인증 헤더를 제공할 수 없는 인증 흐름에서 접근되기 때문입니다.

NGINX 구성 예시

다음은 인증 시크릿 헤더를 검증하는 NGINX 부분 구성 예시입니다.

server {
    # ...

    # Define the expected auth secret
    set $expected_secret "your-secure-auth-secret-here";

    # Whitelist endpoints where auth secret may not be available
    location = /api/v4/notifications/ack {
       # Pass through without verifying auth secret validation
       # ...
    }

    location = /api/v4/config/client {
       # Pass through without verifying auth secret validation
       # ...
    }

    location = /login/desktop {
       # Pass through without verifying auth secret validation
       # ...
    }

    location ^~ /static/ {
       # Pass through without verifying auth secret validation
       # ...
    }

    # Additional whitelisted endpoints based on authentication configuration
    # Uncomment and configure as needed for your setup:
    # Note: Replace {service:[A-Za-z0-9]+} with your specific service names
    # (e.g., google, gitlab, openid, office365) or use the regex pattern for multiple services

    # SAML
    # location = /login/sso/saml {
    #    # ...
    # }

    # OpenID/OAuth patterns (use regex for multiple services)
    # location ~ ^/oauth/[A-Za-z0-9]+/(complete|login|mobile_login|signup)$ {
    #    # ...
    # }
    # Or for specific services:
    # location ~ ^/oauth/(google|gitlab|office365)/(complete|login|mobile_login|signup)$ {
    #    # ...
    # }
    # location ~ ^/api/v3/oauth/[A-Za-z0-9]+/complete$ {
    #    # ...
    # }
    # location ~ ^/(signup|login)/[A-Za-z0-9]+/complete$ {
    #    # ...
    # }

    location / {
        # Check if X-Mattermost-Preauth-Secret header matches expected value
        if ($http_x_mattermost_preauth_secret != $expected_secret) {
            add_header X-Reject-Reason pre-auth always;
            add_header Cache-Control "no-store" always;
            return 403 "Forbidden: Invalid pre-authentication secret";
        }

        # ...
    }
}

your-secure-auth-secret-here를 모바일 및 데스크톱 애플리케이션에 설정할 강력하고 고유한 시크릿으로 교체하세요. 이 시크릿은 안전하게 보관하고, 보안 관행의 일환으로 주기적으로 교체하세요.

Apache2 구성 안내는 Configuring Apache2 as a proxy for Mattermost Server 문서를 참고하세요.

시크릿 교체

인증 시크릿을 교체하려면 다음과 같이 진행합니다.

  1. 새 시크릿을 생성합니다: openssl rand -base64 32.
  2. 리버스 프록시 구성을 새 시크릿으로 업데이트합니다.
  3. 리버스 프록시를 다시 로드합니다.

  4. 사용자에게 알립니다.

    • 데스크톱 사용자: 별도 조치가 필요하지 않습니다. 다음 연결 시도 시 새 시크릿 입력이 자동으로 요청됩니다.
    • 모바일 사용자: 앱에서 Servers를 탭하고 왼쪽으로 스와이프한 뒤 Edit > Advanced Options를 탭하여 Authentication secret을 직접 수정해 시크릿을 업데이트합니다.

보안 고려 사항

Desktop

Mattermost 데스크톱 애플리케이션은 운영 체제의 보안 자격 증명 저장소와 연동되는 Electron의 safeStorage API를 사용해 인증 시크릿을 저장합니다.

  • Windows: Windows Credential Manager
  • macOS: Keychain Access
  • Linux: Secret Service API(kwallet, gnome-libsecret 또는 호환 백엔드 필요)

Electron의 보안 저장소 동작에 대한 자세한 내용은 Electron safeStorage 문서를 참고하세요.

주의

보안 자격 증명 저장소를 사용할 수 없는 Linux 시스템에서는 인증 시크릿이 평문으로 저장될 수 있습니다. 다음과 같은 경우에 발생합니다.

  • 사용할 수 있는 시크릿 저장소 백엔드가 없는 경우(kwallet, gnome-libsecret 등)
  • 데스크톱 환경이 인식되지 않는 경우
  • 시스템이 Electron의 basic_text 저장소로 폴백하는 경우

해당 파일은 다른 사용자의 무단 접근을 막는 권한으로 저장되지만, 시크릿 자체는 암호화되지 않은 상태로 남습니다. 환경에 인증 시크릿을 배포하기 전에 보안 영향을 검토하세요.

Mobile

Mattermost 모바일 애플리케이션은 플랫폼 기본 보안 저장소를 사용해 인증 시크릿을 저장합니다.

  • iOS: iOS Keychain
  • Android: Android Keystore system

모바일의 인증 시크릿은 항상 암호화됩니다. 데스크톱 Linux 시스템과 달리 모바일 플랫폼에는 평문 폴백이 없습니다.

인증 시크릿은 REST API 호출, WebSocket 연결, 공유 확장 및 알림 핸들러의 요청을 포함한 모든 네트워크 요청에 포함됩니다.