snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/main/deployment-guide/server/pre-authentication-secrets.mdx

@@ -0,0 +1,157 @@
+---
+title: "Pre-authentication secrets"
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PlanAvailability slug="ent-adv" />
+
+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/&#123;service:[A-Za-z0-9]+&#125;/complete`, `/oauth/&#123;service:[A-Za-z0-9]+&#125;/login`, `/oauth/&#123;service:[A-Za-z0-9]+&#125;/mobile_login`, `/oauth/&#123;service:[A-Za-z0-9]+&#125;/signup`
+- OAuth: `/api/v3/oauth/&#123;service:[A-Za-z0-9]+&#125;/complete`, `/signup/&#123;service:[A-Za-z0-9]+&#125;/complete`, `/login/&#123;service:[A-Za-z0-9]+&#125;/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.
+
+</Important>
+
+## NGINX configuration example
+
+Here's an example partial NGINX configuration that validates the authentication secret header:
+
+``` text
+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](https://support.mattermost.com/hc/en-us/articles/41170740463764-Configuring-Apache2-as-a-proxy-for-Mattermost-Server-Unofficial).
+
+## 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
+
+<Tabs>
+<TabItem value="desktop" label="Desktop">
+
+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](https://www.electronjs.org/docs/latest/api/safe-storage).
+
+<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.
+
+</Warning>
+
+</TabItem>
+<TabItem value="mobile" label="Mobile">
+
+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.
+
+</TabItem>
+</Tabs>
+