Pre-authentication secrets

plans-img-yellow Available on Enterprise Advanced plans

From Mattermost server v10.12 and mobile v2.32, Mattermost deployments can use a reverse proxy to validate authentication secrets before allowing desktop and mobile requests to reach the Mattermost server. This adds an additional security layer by checking for the X-Mattermost-Preauth-Secret header.

Authentication secrets are only supported for mobile and desktop applications. When a secret is required, desktop prompts users directly while mobile displays the secret field in Advanced Options. Web browser clients don’t support this feature.

When authentication secret validation fails, the reverse proxy must return the X-Reject-Reason: pre-auth header along with the 403 status code. This header allows mobile and desktop applications to specifically identify authentication failures and provide appropriate error messaging to users.

Important

We recommend whitelisting certain endpoints where the authentication header may not be available. The specific endpoints depend on your authentication configuration:

  • /api/v4/notifications/ack - Required for proper notification acknowledgement functionality

  • /static/*, /api/v4/config/client and /login/desktop - Required for authentication flows that redirect to the browser, such as SAML, OAuth and OpenID

Additional endpoints based on your authentication setup:

  • 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

These endpoints are whitelisted because they’re accessed during authentication flows where the authentication header can’t be provided, such as OAuth redirects through external identity providers.

NGINX configuration example

Here’s an example partial NGINX configuration that validates the authentication secret header:

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";
        }

        # ...
    }
}

Replace your-secure-auth-secret-here with a strong, unique secret that will be configured in your mobile and desktop applications. Store this secret securely and rotate it regularly as part of your security practices.

For Apache2 configuration guidance, see Configuring Apache2 as a proxy for Mattermost Server.

Rotate secrets

To rotate an authentication secret:

  1. Generate a new secret: openssl rand -base64 32.

  2. Update your reverse proxy configuration with the new secret.

  3. Reload the reverse proxy.

  4. Notify users:

  • Desktop users: No action needed. They’ll be automatically prompted for the new secret on their next connection attempt.

  • Mobile users: Manually update the secret by editing the server in the app by tapping Servers, swiping left, tapping Edit > Advanced Options and updating the Authentication secret.

Security considerations

The Mattermost desktop application stores authentication secrets using Electron’s safeStorage API, which integrates with the operating system’s secure credential storage:

  • Windows: Windows Credential Manager

  • macOS: Keychain Access

  • Linux: Secret Service API (requires kwallet, gnome-libsecret, or compatible backend)

For more information about Electron’s secure storage behavior, see the Electron safeStorage documentation.

Warning

On Linux systems where no secure credential storage is available, the authentication secret may be stored in plain text. This occurs when:

  • No secret store backend is available (kwallet, gnome-libsecret, etc.)

  • The desktop environment is not recognized

  • The system falls back to Electron’s basic_text storage

The file is stored with permissions to prevent unauthorized access by other users, though the secret remains unencrypted. Consider the security implications before deploying authentication secrets in your environment.

The Mattermost mobile application stores authentication secrets using platform-native secure storage:

  • iOS: iOS Keychain

  • Android: Android Keystore system

Mobile authentication secrets are always encrypted. Unlike desktop Linux systems, there is no plaintext fallback on mobile platforms.

The authentication secret is included in all network requests, including REST API calls, WebSocket connections, and requests from share extensions and notification handlers.