Matomo MCP Authentication Fails With 401 Behind Apache

[kylebarrow]

Environment

• Matomo hosted at analytics.bunnyapartment.com
• Apache: Apache/2.4.67 (Debian)
• PHP: 8.4.21
• PHP SAPI: Apache 2 Handler
• Document root: /var/www/matomo

Issue

Matomo MCP requests were failing with 401 Unauthorized, even when the client was sending the expected Authorization header.

Cause

Apache was not exposing the incoming Authorization header to PHP as HTTP_AUTHORIZATION. As a result, Matomo/MCP could not read the bearer token or auth credentials and treated the request as unauthenticated.

Solution

Add the following line to Matomo’s .htaccess file:

SetEnvIf Authorization "^(.*)$" HTTP_AUTHORIZATION=$1

Result

After adding this rule, Apache forwards the Authorization header into the PHP environment as HTTP_AUTHORIZATION, allowing Matomo MCP authentication to succeed instead of returning 401.

[mneudert]

Hey @kylebarrow,

thank you for making us aware of this issue.

Transferred this to the core repository to be solved e.g. by providing a global ,htaccess file, a new diagnostic check, and/or some documentation. Documentation should be expanded to the developer documentation to update the token_auth usage guidance to include Authorization headers.

[mneudert]

For reproduction of the issue in DDEV the following command chain should be viable:

# switch from Nginx to Apache
ddev config --webserver-type=apache-fpm
ddev restart

# switch from FPM to mod_php
ddev exec -u root apt update
ddev exec -u root apt install libapache2-mod-php7.2
ddev exec -u root supervisorctl restart apache2

Now any request using Authorization: Bearer $TOKEN should be rejected as if no token was provided at all.

This should, at least in the packages used by the local DDEV setup, not affect an FPM installation. The php-fpm package provides config files (e.g. /etc/apache2/conf-available/php7.2-fpm.conf) that pass the header forward:

# Redirect to local php-fpm if mod_php is not available
<IfModule !mod_php7.c>
<IfModule proxy_fcgi_module>
    # Enable http authorization headers
    <IfModule setenvif_module>
    SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
    </IfModule>
...