Matomo User Management

Matomo offers granular control over super users, administrators, and site-level permissions. Use this hub to organize how the collaborator gains, changes, and loses access across your Matomo instance(s), whether you're running Matomo Cloud or self-hosted on-premise deployments.

How Matomo Structures Access

User Role Hierarchy

Super Users (Full Platform Access)

• Own the platform configuration, plugin management, and system settings
• Can create, modify, and delete any site across the entire Matomo instance
• Manage user accounts and assign permissions to all sites
• Access sensitive configuration files and database settings (self-hosted)
• View and modify tracking codes, goals, funnels, and custom dimensions globally
• Keep this limited to core admins - grant temporarily to the collaborator only when absolutely necessary for platform administration tasks

Site-Level Permissions

• Permissions differ per site and include Admin, Write, View, and No Access
• A single user can have different roles across different sites:
  • production-website.com → Admin
  • staging-website.com → Write
  • qa-environment.com → View
  • legacy-site.com → No Access
• Document the exact list (including staging, QA, and regional sites) for the collaborator
• Ecommerce sites and log analytics sites should be explicitly called out

Role Capabilities by Site:

Authentication Tokens (token_auth)

• token_auth keys sit at the user level and enable API access
• Track them separately from UI roles because they persist even after UI permission changes
• Each user has a unique 32-character token (e.g., 3c1a8b39f8d4e6f2a7b5c9e0d2f4a6b8)
• API calls authenticate using this token, inheriting the user's site-level permissions
• Critical: Rotate token_auth whenever you change a user's role or remove access
• Store tokens in a secure vault (1Password, AWS Secrets Manager, HashiCorp Vault)

Token Use Cases:

• Reporting APIs for custom dashboards
• Data export pipelines to data warehouses
• Third-party integrations (CRMs, BI tools)
• Automated alert systems
• Custom tracking implementations

Matomo Cloud vs. Self-Hosted Differences

Matomo Cloud:

• User management via web UI only
• No server-level access required
• SSO/SAML available on Business plans and higher
• Automatic backups and updates managed by Matomo
• API rate limits enforced (varies by plan)

Self-Hosted On-Premise:

• User management via web UI and direct database manipulation
• May require server credentials (SSH, MySQL/MariaDB) for advanced tasks
• SSO/SAML via plugins (LoginLDAP, LoginOIDC, LoginSAML)
• You manage backups, updates, and server security
• API rate limits configurable via config/config.ini.php
• Additional access layers to track:
  • SSH access to the server
  • MySQL/MariaDB database credentials
  • File system access for logs and configuration
  • Access to cron jobs and background tasks

Access Requests at a Glance

• Add User Access walks through inviting the service account and assigning site permissions.
• Update Access & Roles outlines how to adjust site access, segments, or token_auth privileges.
• Remove User Access covers deprovisioning and audit evidence.

Add, Update, Remove - Lifecycle Overview

Add User Access

When to Add:

• New collaborator onboarding for analytics implementation
• Consultant needs access for site audit or optimization
• Third-party agency requires reporting access for client dashboards
• Internal team expansion (new analysts, marketers, developers)

Steps:

1. Create the user account in Administration → Users → Manage
2. Set Super User status (if required) or leave as normal user
3. Apply per-site roles for each website the collaborator needs access to:
   • Include production, staging, QA environments
   • Consider ecommerce sites and log analytics sites separately
4. Generate and securely share the user's token_auth if API access is required
5. Configure additional settings:
   • Email notifications for scheduled reports
   • Custom segments access (if collaborator should inherit existing segments)
   • Privacy settings (IP anonymization, user ID visibility)
6. Test access with the collaborator to ensure correct permissions

Documentation to Create:

• IAM ticket with justification and approval
• List of sites and assigned roles
• Token storage location (vault reference)
• Scheduled review date (30, 60, or 90 days)

Update User Access

When to Update:

• New properties or sites launch requiring additional access
• Scope narrows and read-only (View) access becomes sufficient
• Collaborator role changes from implementation to ongoing support
• Elevated privileges needed for specific projects (goals, custom dimensions, integrations)
• Security audit reveals over-provisioned permissions
• SSO/SAML group mappings are updated by IT

Steps:

1. Navigate to Administration → Users → Manage
2. Find the user and click Edit
3. Modify site permissions:
   • Add new sites with appropriate roles
   • Upgrade or downgrade existing site roles
   • Remove access to sites no longer in scope
4. Regenerate token_auth if permissions increase (grants additional API access)
5. Update documentation and notify the collaborator
6. Verify changes in the System → Audit Log

Common Update Scenarios:

• Implementation complete → Downgrade from Admin to View
• New brand acquisition → Add site access for new property
• Seasonal campaign → Temporary Admin access, then revert
• Security incident → Temporarily elevate to Super User for audit

Remove User Access

When to Remove:

• Contract ends or engagement completes
• Collaborator changes companies or roles
• Security incident requires immediate access revocation
• Compliance audit reveals dormant accounts
• Contractor transitions to different project

Steps:

1. Export scheduled reports and custom segments created by the collaborator
2. Transfer ownership to a retained admin or client team member
3. Navigate to Administration → Users → Manage
4. Delete the user account or revoke all site permissions (keeps audit trail)
5. Invalidate the user's token_auth by regenerating it or deleting the user
6. Update any integrations using the collaborator's token_auth
7. Document the removal in System → Audit Log export
8. For self-hosted: Remove SSH/database access separately

Evidence to Retain:

• Audit log showing user deletion event
• Screenshot of site permissions before removal
• Confirmation email to collaborator and client stakeholders
• List of integrations updated post-removal

Detailed Role Definitions

Super User Role

Access Scope:

• Full, unrestricted access to all Matomo features and all sites
• Can perform any action any other user can perform
• Access to sensitive system configuration and database settings
• Ability to grant or revoke Super User status for other users

Specific Capabilities:

• User Management: Create, edit, delete users; assign permissions globally
• Site Management: Add, edit, delete any site; manage tracking codes
• Plugin Management: Install, activate, deactivate, uninstall plugins
• System Configuration: Modify config/config.ini.php settings via UI or file system
• Database Access: Execute SQL queries, manage database structure (self-hosted)
• Privacy & GDPR: Configure anonymization, deletion schedules, consent management
• Tracking & Tag Manager: Manage tracking code, Tag Manager containers (if enabled)
• Diagnostics: View system logs, error logs, troubleshoot platform issues

When to Grant:

• Platform administrator managing the entire Matomo instance
• DevOps engineer responsible for server maintenance (self-hosted)
• Consultant performing platform migration or major upgrade
• Security auditor requiring full visibility (time-limited)

Security Recommendations:

• Limit to 2-3 individuals maximum
• Require MFA (multi-factor authentication) for all Super Users
• Review Super User list quarterly
• Use temporary Super User grants for consultants (revoke after task completion)
• Monitor System → Audit Log for Super User actions

Site Admin Role

Access Scope:

• Full administrative access to specific assigned sites
• Cannot access system-wide settings or other sites
• Cannot manage users globally (can only manage users for their assigned sites)
• Cannot install or configure plugins

Specific Capabilities:

• Site Settings: Modify site URLs, timezone, currency, ecommerce settings
• Goals & Conversions: Create, edit, delete goals; configure funnels
• Custom Dimensions: Create custom dimensions (visit-level or action-level)
• Segments: Create private or public segments for their sites
• Scheduled Reports: Set up email/SMS reports for themselves and others
• Site Users: Grant other users View or Write access to their sites (not Admin)
• Tracking Code: View and copy tracking code for their sites
• Data Management: Configure IP anonymization, delete old data for their sites
• Integrations: Configure site-specific integrations (Google Analytics import, etc.)

When to Grant:

• Collaborator implementing analytics for specific client websites
• Marketing team managing goals and campaigns for their sites
• Product manager overseeing analytics for their product's domain
• Consultant performing site audit and optimization

Best Practices:

• Default role for most collaborators during implementation
• Downgrade to Write or View after initial setup is complete
• Clearly document which sites (production vs. staging) have Admin access
• Review Admin access quarterly and revoke when no longer needed

Write Role (Contributor)

Access Scope:

• Can create and modify content (reports, segments, goals) for assigned sites
• Cannot change site settings or manage users
• Cannot access sensitive configuration or tracking codes

Specific Capabilities:

• Reports & Dashboards: Create custom reports, dashboards, and visualizations
• Goals: Create and edit goals (on some Matomo versions; check your instance)
• Segments: Create private segments; view public segments
• Annotations: Add annotations to reports (mark campaign launches, site changes)
• Scheduled Reports: Create email reports for themselves
• Data Export: Export data to CSV, Excel, JSON via UI or API

Limitations:

• Cannot modify site settings (URLs, timezone, ecommerce settings)
• Cannot manage users or assign permissions
• Cannot access tracking code or Tag Manager
• Cannot configure custom dimensions or advanced settings

When to Grant:

• Analysts who create reports but don't need configuration access
• Marketing team members analyzing campaign performance
• Collaborator transitioning from implementation to ongoing analysis
• External reporting consultant building dashboards for clients

View Role (Read-Only)

Access Scope:

• Read-only access to reports and dashboards for assigned sites
• Cannot create, modify, or delete anything
• Suitable for compliance-friendly access and executive stakeholders

Specific Capabilities:

• View Reports: Access all standard and custom reports
• View Dashboards: See dashboards created by others
• View Segments: Use existing segments to filter reports
• Export Data: Export visible data to CSV/Excel (limited to visible reports)
• View Goals: See goal performance and conversion data

Limitations:

• Cannot create custom reports or dashboards
• Cannot modify segments or goals
• Cannot schedule reports
• Cannot add annotations
• No API write access (read-only API calls only)

When to Grant:

• Executive stakeholders who review performance periodically
• Client teams who consume analytics but don't perform analysis
• Compliance officers auditing data collection practices
• Temporary access for audits or reviews
• Collaborator after engagement scope narrows to reporting-only

SSO and SCIM Integration

Single Sign-On (SSO) via SAML

Matomo supports SSO integration through SAML 2.0 for streamlined authentication:

Supported Identity Providers:

• Okta
• Azure Active Directory (Microsoft Entra ID)
• OneLogin
• Google Workspace (G Suite)
• Auth0
• Any SAML 2.0 compliant IdP

Setup Overview (Matomo Cloud):

1. Navigate to Administration → System → SAML
2. Enable SAML authentication
3. Configure IdP metadata (upload XML file or paste URL)
4. Map SAML attributes to Matomo user fields:
   • email → User email
   • firstName → User first name
   • lastName → User last name
5. Define role mappings (optional):
   • Map IdP groups to Matomo site permissions
   • Example: Matomo-Admins group → Admin access to all sites
6. Test SSO login with a test user
7. Enable "Force SSO login" to require SSO for all users (optional)

Setup for Self-Hosted:

Install the LoginSAML plugin:

cd /path/to/matomo
./console plugin:activate LoginSAML

Configure SAML in config/config.ini.php:

[LoginSAML]
saml_idp_metadata_url = "https://idp.example.com/metadata.xml"
saml_sp_entity_id = "https://matomo.example.com"
saml_sp_x509_certificate = "/path/to/cert.pem"
saml_sp_private_key = "/path/to/key.pem"

; Attribute mappings
saml_user_email_attribute = "email"
saml_user_firstname_attribute = "firstName"
saml_user_lastname_attribute = "lastName"

; Role mapping (map IdP groups to Matomo sites and permissions)
[LoginSAML_RoleMapping]
group[Matomo-SuperUsers] = "superuser"
group[Matomo-Site1-Admins] = "site:1:admin"
group[Matomo-Site1-Viewers] = "site:1:view"

Role Mapping Syntax:

• superuser → Grants Super User status
• site:[SITE_ID]:admin → Admin access to site with ID X
• site:[SITE_ID]:write → Write access
• site:[SITE_ID]:view → View access

Find site IDs: Administration → Websites → Manage

Testing SSO:

1. Open an incognito/private browser window
2. Navigate to your Matomo URL
3. Click "Sign in with SSO" (or it redirects automatically)
4. Authenticate with your IdP credentials
5. Verify correct sites and permissions appear in Matomo

LDAP/Active Directory Integration

For self-hosted Matomo instances, integrate with LDAP or Active Directory:

Install LoginLDAP Plugin:

cd /path/to/matomo
./console plugin:activate LoginLDAP

Configure LDAP in config/config.ini.php:

[LoginLdap]
servers[] = "ldap://ldap.example.com:389"
ldap_user_base_dn = "ou=users,dc=example,dc=com"
ldap_user_filter = "(&(objectClass=person)(uid=?))"
ldap_bind_dn = "cn=admin,dc=example,dc=com"
ldap_bind_password = "admin_password"

; User attribute mappings
ldap_user_email_attribute = "mail"
ldap_user_firstname_attribute = "givenName"
ldap_user_lastname_attribute = "sn"

; Group-based access control
ldap_group_base_dn = "ou=groups,dc=example,dc=com"
ldap_group_filter = "(&(objectClass=groupOfNames)(member=?))"
ldap_memberof_attribute = "memberOf"

; Role mappings
[LoginLdap_RoleMapping]
group[cn=matomo-admins,ou=groups,dc=example,dc=com] = "superuser"
group[cn=matomo-analysts,ou=groups,dc=example,dc=com] = "site:1:write,site:2:write"

Testing LDAP Authentication:

1. Log out of Matomo
2. Enter LDAP username (not email) at login screen
3. Enter LDAP password
4. Verify automatic role assignment based on group membership

Automated Provisioning Workflows

Scenario: New Hire Provisioning

Using Okta + SAML:

1. HR system adds new employee to Active Directory
2. AD syncs to Okta via directory integration
3. Employee is added to "Matomo-Analysts" group in Okta
4. Employee attempts to log in to Matomo via SSO
5. SAML assertion includes group membership claim
6. Matomo automatically creates user account with Write access to sites mapped to "Matomo-Analysts" group
7. No manual intervention required

Scenario: Role Change (Promotion)

1. Manager updates employee's role in HR system
2. Employee is added to "Matomo-Site-Admins" group in IdP
3. Next time employee logs in to Matomo via SSO:
   - SAML assertion includes updated group membership
   - Matomo updates user permissions to Admin for mapped sites
4. Previous Write access is retained for other sites

Scenario: Offboarding

1. HR system disables employee account
2. IdP (Okta/Azure AD) suspends user automatically
3. Next SAML login attempt fails (user is disabled in IdP)
4. Matomo retains the user account but access is effectively revoked
5. Admin manually deletes Matomo user account during cleanup (30 days later)
6. Audit log retains record of user's historical actions

API Access and Token Management

Understanding token_auth

Every Matomo user has a unique token_auth value, a 32-character hexadecimal string:

Example: 3c1a8b39f8d4e6f2a7b5c9e0d2f4a6b8

Where to Find token_auth:

1. Log in to Matomo as the user
2. Navigate to Administration → Personal → Security
3. Scroll to "Auth Token" section
4. Copy the token (click "Show" if hidden)

API Authentication Example:

# Fetch visits and actions for last 7 days
curl "https://matomo.example.com/index.php?module=API&method=VisitsSummary.get&idSite=1&period=day&date=last7&format=JSON&token_auth=3c1a8b39f8d4e6f2a7b5c9e0d2f4a6b8"

Rotating token_auth

When to Rotate:

• User role changes (permissions increase or decrease)
• User leaves the organization
• Token is accidentally exposed (committed to Git, shared in chat)
• Quarterly security review
• After a security incident

How to Rotate (UI Method):

1. Log in as the user (or as Super User on their behalf)
2. Navigate to Administration → Personal → Security
3. Scroll to "Auth Token" section
4. Click Regenerate Token
5. Confirm the action
6. Copy the new token and update all integrations

How to Rotate (API Method):

# Regenerate token for a user (requires Super User token)
curl -X POST "https://matomo.example.com/index.php" \
  -d "module=API" \
  -d "method=UsersManager.regenerateTokenAuth" \
  -d "userLogin=collaborator@agency.com" \
  -d "format=JSON" \
  -d "token_auth=YOUR_SUPERUSER_TOKEN"

How to Rotate (Database Method - Self-Hosted):

-- Connect to Matomo database
mysql -u matomo_user -p matomo_db

-- Find user's current token
SELECT login, token_auth FROM matomo_user WHERE login = 'collaborator@agency.com';

-- Generate new token (use a secure random generator)
-- Example new token: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

UPDATE matomo_user
SET token_auth = 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
WHERE login = 'collaborator@agency.com';

-- Verify update
SELECT login, token_auth FROM matomo_user WHERE login = 'collaborator@agency.com';

Generate secure token:

# Generate a random 32-character hex string
openssl rand -hex 16

Managing API Access at Scale

Inventory of Token Usage:

Create a spreadsheet or secrets management entry tracking:

Automate Token Rotation:

import requests
import os
from datetime import datetime, timedelta

MATOMO_URL = "https://matomo.example.com"
SUPERUSER_TOKEN = os.getenv("MATOMO_SUPERUSER_TOKEN")

def rotate_user_token(user_login):
    """Regenerate token_auth for a given user."""
    response = requests.post(
        f"{MATOMO_URL}/index.php",
        data={
            "module": "API",
            "method": "UsersManager.regenerateTokenAuth",
            "userLogin": user_login,
            "format": "JSON",
            "token_auth": SUPERUSER_TOKEN,
        }
    )
    result = response.json()
    if "value" in result:
        new_token = result["value"]
        print(f"✓ Rotated token for {user_login}: {new_token}")
        return new_token
    else:
        print(f"✗ Failed to rotate token for {user_login}: {result}")
        return None

def get_all_users():
    """Fetch list of all Matomo users."""
    response = requests.get(
        f"{MATOMO_URL}/index.php",
        params={
            "module": "API",
            "method": "UsersManager.getUsers",
            "format": "JSON",
            "token_auth": SUPERUSER_TOKEN,
        }
    )
    return response.json()

# Rotate tokens for users needing quarterly rotation
users = get_all_users()
for user in users:
    # Check if user's token is older than 90 days (implement date tracking)
    # For this example, rotate collaborators only
    if "collaborator" in user["login"] or "consultant" in user["login"]:
        new_token = rotate_user_token(user["login"])
        # Update your secrets vault here
        # update_vault(user["login"], new_token)

API Rate Limiting and Quotas

Matomo Cloud:

• Rate limits vary by plan (Starter, Business, Enterprise)
• Typical limit: 100 requests per minute per user
• Exceeding limit results in HTTP 429 (Too Many Requests)
• Contact Matomo support to increase limits

Self-Hosted:

Configure in config/config.ini.php:

[General]
; Enable API rate limiting
enable_api_rate_limit = 1

; Requests per hour per user
api_rate_limit_requests_per_hour = 6000

; Requests per minute per user (if not set, defaults to requests_per_hour / 60)
api_rate_limit_requests_per_minute = 100

; IP-based rate limiting (optional)
api_rate_limit_by_ip = 0

Monitor API Usage:

# Fetch API call logs (if logging is enabled)
tail -f /path/to/matomo/tmp/logs/matomo.log | grep "API.request"

# Count API calls by user token in the last hour
grep "token_auth=3c1a8b39" /path/to/matomo/tmp/logs/matomo.log | grep "$(date -u +%Y-%m-%d\ %H)" | wc -l

Security Best Practices

Principle of Least Privilege

Decision Matrix for Granting Access:

Multi-Factor Authentication (MFA)

Matomo Cloud (Native MFA):

1. Navigate to Administration → System → Security
2. Enable Require Multi-Factor Authentication
3. Users are prompted to enroll on next login
4. Supported methods:
   • TOTP (Google Authenticator, Authy, 1Password)
   • SMS (premium plans)
   • Hardware keys (U2F/WebAuthn, premium plans)

Self-Hosted (via Plugin):

Install the LoginOIDC or LoginSAML plugin and delegate MFA to your IdP:

cd /path/to/matomo
./console plugin:activate LoginOIDC

Configure your IdP (Okta, Azure AD) to require MFA, and Matomo inherits that requirement.

Per-User MFA Enforcement:

As a Super User, enforce MFA for specific users:

1. Administration → Users → Manage
2. Click on user's row
3. Check Require Multi-Factor Authentication
4. Save changes
5. User is prompted to enroll on next login

Session Management

Configure Session Timeout:

Edit config/config.ini.php:

[General]
; Session lifetime in seconds (default: 14 days)
session_cookie_lifetime = 1209600

; Absolute session timeout (default: 24 hours)
login_cookie_expire = 86400

; Auto-logout inactive users after 30 minutes
session_timeout = 1800

Force Logout After Password Change:

[General]
; Invalidate all sessions when user changes password
force_ssl = 1
login_password_recovery_revalidate_email_address = 1

IP Allowlisting (Self-Hosted)

Restrict Matomo access to specific IP ranges:

Via .htaccess (Apache):

<FilesMatch "index\.php">
    Order Deny,Allow
    Deny from all
    Allow from 203.0.113.0/24
    Allow from 198.51.100.50
</FilesMatch>

Via Nginx:

location / {
    allow 203.0.113.0/24;
    allow 198.51.100.50;
    deny all;
}

Via Matomo Config (Plugin: LoginAllowlist):

Install and configure the LoginAllowlist plugin:

[LoginAllowlist]
ip_allowlist[] = "203.0.113.0/24"
ip_allowlist[] = "198.51.100.50"

Password Policies

Enforce Strong Passwords (Self-Hosted):

Edit config/config.ini.php:

[General]
; Minimum password length
password_min_length = 12

; Require special characters, numbers, uppercase
password_complexity = 1

; Prevent password reuse (last N passwords)
password_history = 5

; Force password reset every 90 days
password_expiry_days = 90

Matomo Cloud:

Password policies are enforced by default:

• Minimum 10 characters
• Must include uppercase, lowercase, number, and special character
• Cannot reuse last 3 passwords

Governance and Compliance

Audit Trail Management

Accessing Audit Logs:

1. Navigate to Administration → System → Audit Log (Super User required)
2. Filter by:
   • User: Specific user login
   • Date Range: Last 7 days, 30 days, custom range
   • Event Type: User created, permission changed, site settings modified, etc.
3. Export logs to CSV for compliance storage

API Export:

# Export audit log for a specific user
curl "https://matomo.example.com/index.php?module=API&method=AuditLog.getAuditLog&filter_pattern=collaborator@agency.com&format=CSV&token_auth=SUPERUSER_TOKEN" \
  > auditlog_$(date +%Y%m%d).csv

Self-Hosted Database Query:

SELECT * FROM matomo_audit_log
WHERE user_login = 'collaborator@agency.com'
ORDER BY timestamp DESC
LIMIT 100;

Retention and Deletion Policies

Configure Data Retention:

1. Navigate to Administration → Privacy → Anonymize Data
2. Set retention periods:
   • Delete logs older than: 180 days
   • Delete reports older than: 365 days
3. Schedule automatic deletion via cron:

# Add to cron (runs daily at 2 AM)
0 2 * * * /path/to/matomo/console core:delete-logs-data --dates=180

GDPR and Privacy Compliance

Data Subject Access Requests (DSAR):

Export all data for a specific user ID:

./console gdpr:export-data-subjects \
  --visits-for-users="user123@example.com" \
  --output-dir=/tmp/gdpr-exports

Right to Erasure (Delete User Data):

./console gdpr:anonymize-data-subjects \
  --visits-for-users="user123@example.com"

Track Collaborator Access to Personal Data:

Configure Matomo to log when collaborators view sensitive data:

[Privacy]
; Log when users access IP addresses, user IDs, or geolocation
log_sensitive_data_access = 1

Review logs:

grep "Sensitive data accessed" /path/to/matomo/tmp/logs/matomo.log

Access Review Cadence

Quarterly Access Reviews:

Create a recurring calendar event to review:

1. All Super Users: Verify they still require platform-wide access
2. Site Admins: Confirm sites are still in scope for their role
3. Dormant Accounts: Identify users who haven't logged in for 90+ days
4. API Tokens: Validate tokens are still in use (check integration logs)

Automated Dormant Account Detection:

# List users who haven't logged in for 90+ days
./console usermanager:list-users --format=json \
  | jq -r '.[] | select(.last_seen < (now - 7776000)) | "\(.login) last seen: \(.last_seen)"'

Offboarding Checklist:

When a collaborator's contract ends:

• Export their scheduled reports
• Transfer ownership of custom dashboards and segments
• Delete or revoke all site permissions
• Regenerate token_auth (invalidates API access)
• Remove from SSO/SAML groups
• Remove SSH/database access (self-hosted)
• Export audit log showing their historical actions
• Document offboarding in IAM ticket
• Store evidence in compliance folder

Platform-Specific Considerations

Matomo Cloud

Access Management Limitations:

• No direct database access (all changes via UI or API)
• Cannot modify server configuration files
• Plugin installation restricted to Marketplace-approved plugins
• SSO/SAML available on Business plan and higher

Advantages:

• Automatic backups and disaster recovery
• Managed updates and security patches
• Built-in compliance features (GDPR, CCPA)
• Matomo support team assistance

Self-Hosted On-Premise

Additional Access Layers:

1. Server Access (SSH):

   • Required for: File system management, log analysis, manual updates
   • Grant only to: DevOps, platform administrators
   • Track separately from Matomo UI permissions

2. Database Access (MySQL/MariaDB):

   • Required for: Manual data exports, troubleshooting, direct queries
   • Grant only to: Database administrators, senior analysts (temporary)
   • Use read-only credentials when possible

3. File System Access:

   • Required for: Plugin installation, configuration changes, log review
   • Grant only to: Platform administrators
   • Ensure proper file permissions (www-data or apache user)

Example: Restricted Database User:

-- Create read-only user for analysts
CREATE USER 'analyst_readonly'@'%' IDENTIFIED BY 'secure_password';
GRANT SELECT ON matomo.matomo_log_visit TO 'analyst_readonly'@'%';
GRANT SELECT ON matomo.matomo_log_action TO 'analyst_readonly'@'%';
GRANT SELECT ON matomo.matomo_site TO 'analyst_readonly'@'%';
FLUSH PRIVILEGES;

Example: Restricted SSH User:

# Create user with limited shell access
sudo adduser matomo_viewer
sudo usermod -s /usr/bin/rbash matomo_viewer  # Restricted bash

# Allow only specific commands
sudo mkdir /home/matomo_viewer/bin
sudo ln -s /usr/bin/tail /home/matomo_viewer/bin/tail
sudo ln -s /usr/bin/grep /home/matomo_viewer/bin/grep
sudo ln -s /usr/bin/less /home/matomo_viewer/bin/less

# Restrict to log directory
sudo chown -R matomo_viewer:matomo_viewer /path/to/matomo/tmp/logs
sudo chmod 750 /path/to/matomo/tmp/logs

Troubleshooting Access Issues

User Cannot Log In

Symptoms:

• "Invalid username or password" error
• Redirect loop after SSO authentication
• Account locked after multiple failed attempts

Diagnosis:

1. Check account status:

   SELECT login, email, date_registered, superuser_access
   FROM matomo_user
   WHERE login = 'collaborator@agency.com';
   

2. Check for failed login attempts:

   grep "Failed login" /path/to/matomo/tmp/logs/matomo.log | grep "collaborator@agency.com"
   

3. Verify SSO configuration (if enabled):

   • Check IdP metadata URL is accessible
   • Verify SAML certificate hasn't expired
   • Confirm user exists in IdP directory

Solutions:

• Reset password: Administration → Users → Manage → Click user → Reset Password
• Unlock account: Wait 30 minutes or manually unlock in database:

  DELETE FROM matomo_brute_force_log WHERE login = 'collaborator@agency.com';
  

• Check SSO attribute mapping: Ensure email attribute matches exactly

User Has Access But Sees No Sites

Symptoms:

• User logs in successfully
• Dashboard is empty or shows "No data"
• Site switcher dropdown is empty

Diagnosis:

-- Check user's site permissions
SELECT u.login, s.idsite, s.name, a.access
FROM matomo_user u
JOIN matomo_access a ON u.login = a.login
JOIN matomo_site s ON a.idsite = s.idsite
WHERE u.login = 'collaborator@agency.com';

Solutions:

1. Grant site access:

   • Administration → Users → Manage → Click user → Add Site Access
   • Select site and assign role (Admin, Write, View)

2. Verify SSO role mapping:

   • Check user's IdP group memberships
   • Confirm SAML/LDAP role mapping is correct
   • Re-authenticate user to refresh group claims

3. Check for site-specific restrictions:

   • Some sites may have IP allowlisting enabled
   • Verify user is connecting from allowed IP range

API Calls Return "Invalid token_auth"

Symptoms:

• API returns: {"result":"error","message":"invalid token_auth"}
• Previously working integrations suddenly fail

Diagnosis:

1. Verify token hasn't been regenerated:

   SELECT login, token_auth FROM matomo_user WHERE login = 'collaborator@agency.com';
   

2. Check token permissions:

   • Token inherits user's site permissions
   • Verify user still has access to requested site

3. Validate API request format:

   # Test with known-good token
   curl "https://matomo.example.com/index.php?module=API&method=SitesManager.getSitesWithViewAccess&format=JSON&token_auth=YOUR_TOKEN"
   

Solutions:

• Update integrations with new token if it was rotated
• Check user's site access hasn't been revoked
• Verify API endpoint is correct (index.php, not /api/)

Permission Denied Errors

Symptoms:

• "You don't have permission to access this resource"
• Certain menu items or features are hidden
• "Access denied" when trying to save settings

Common Causes:

Documentation Templates

IAM Change Request Template

## Matomo Access Change Request

**Ticket ID:** IAM-2948
**Date:** 2024-01-20
**Requestor:** Sarah Johnson (Marketing Manager)
**Approver:** David Chen (CTO)

### User Information
- **Name:** Alex Martinez
- **Email:** alex.martinez@agency.com
- **Company:** Digital Analytics Partners
- **Matomo Instance:** matomo.acmecorp.com

### Change Type
- [X] Add user access
- [ ] Update user permissions
- [ ] Remove user access

### Access Details

**Role:**
- [ ] Super User (requires VP approval)
- [X] Site Admin
- [ ] Write
- [ ] View

**Sites and Permissions:**

| Site ID | Site Name | Current Role | New Role | Justification |
|---------|-----------|--------------|----------|---------------|
| 1 | www.acme.com (production) | None | Admin | Q1 2024 goals implementation |
| 2 | staging.acme.com | None | Admin | Testing environment for goal validation |
| 5 | blog.acme.com | None | Write | Dashboard creation only |

**API Access:**
- [X] Generate token_auth
- [ ] No API access required

**Additional Requirements:**
- [ ] SSO/SAML integration (add to "Matomo-Admins" Okta group)
- [X] MFA required
- [ ] IP allowlist restriction: N/A

### Duration
- [X] Permanent (contract-based, review quarterly)
- [ ] Temporary (specify end date): ___________

### Business Justification
Alex will implement event tracking and conversion goals for our Q1 marketing campaigns. Admin access is required to configure goals, custom dimensions, and tracking code modifications. Staging access ensures testing before production deployment.

### Security Attestation
- [X] Collaborator has signed NDA
- [X] Collaborator completed security awareness training
- [X] Least privilege principle applied
- [X] Access review scheduled for: 2024-04-20

### Implementation Checklist
- [ ] User account created in Matomo
- [ ] Site permissions assigned
- [ ] token_auth generated and stored in 1Password vault
- [ ] MFA enrollment confirmed
- [ ] Welcome email sent to collaborator
- [ ] Access documented in IAM tracking system
- [ ] Audit log entry exported

**Implemented by:** IT Admin (admin@acme.com)
**Implementation date:** ___________
**Verified by:** ___________

Access Inventory Spreadsheet

Create a Google Sheet or Excel file with these columns:

Update this spreadsheet after every access change.

Appendix: Quick Reference

Common CLI Commands (Self-Hosted)

# List all users
./console usermanager:list-users

# Create a new user
./console usermanager:create-user \
  --login=newuser@example.com \
  --password=SecurePass123! \
  --email=newuser@example.com \
  --alias="New User"

# Grant Super User access
./console usermanager:set-superuser-access newuser@example.com 1

# Revoke Super User access
./console usermanager:set-superuser-access newuser@example.com 0

# Set site permission
./console usermanager:set-site-permission \
  --login=newuser@example.com \
  --site-id=1 \
  --access=admin

# Remove site permission
./console usermanager:set-site-permission \
  --login=newuser@example.com \
  --site-id=1 \
  --access=noaccess

# Delete a user
./console usermanager:delete-user newuser@example.com

# Export audit log
./console auditlog:export --output-file=/tmp/audit.csv

Access Decision Tree

Does the collaborator need to modify platform settings or manage all sites?
├─ YES → Grant Super User (requires VP approval, time-limited)
└─ NO → Does the collaborator need to configure goals, tracking code, or site settings?
    ├─ YES → Grant Site Admin for specific sites
    └─ NO → Does the collaborator need to create reports and dashboards?
        ├─ YES → Grant Write access
        └─ NO → Grant View (read-only) access

Recommended Access Lifecycle

Implementation Phase (0-3 months):

• Role: Admin
• Sites: Production + Staging + QA
• API: Yes (token_auth for testing)
• Review: Monthly

Maintenance Phase (3-12 months):

• Role: Write or Admin (goals only)
• Sites: Production only
• API: Yes (if pipelines are managed)
• Review: Quarterly

Reporting-Only Phase (12+ months):

• Role: View
• Sites: Production only
• API: No (read-only dashboards)
• Review: Biannually

Offboarding:

• Remove all access
• Transfer reports/segments
• Rotate all tokens
• Export audit logs