How do you configure and secure OAuth 2.0 in Matomo?

OAuth 2.0 in Matomo is configured at the application level and controlled by superusers. Settings define how tokens are issued, how long they remain valid, and what permissions they can request. Security considerations include how clients store credentials and how tokens are handled throughout their lifecycle.

Configuring OAuth 2.0 in Matomo

These frequently asked questions explain how OAuth 2.0 is configured in Matomo, including who can manage it, how token settings work, and how permissions are controlled.

1. Who can configure OAuth 2.0 in Matomo?
   Only superusers can create and manage OAuth clients and settings.

2. Can token lifetimes be configured?
   Yes. You can configure the following via OAuth 2.0 settings:

   • Access token lifetime.
   • Refresh token lifetime.
   • Authorisation code lifetime.

3. What happens when a refresh token expires?
   Once expired, the user must re-authorise the application to obtain new tokens.

4. Can OAuth clients request more permissions than configured?
   No. The scopes requested by a client cannot exceed the scopes defined during client configuration.

Security considerations and edge cases

These questions cover important security behaviours and edge cases to consider when implementing OAuth 2.0 in Matomo.

1. Can a public client use a client secret?
   No. Public clients cannot securely store secrets and must not use a client secret.

2. What happens if an authorisation code expires?
   Authorisation codes are short-lived. If expired, the authorisation process must be restarted.

3. What happens if a token is leaked?
   The token can be used until it expires. To mitigate risk:

   • Use short token lifetimes.
   • Rotate credentials.
   • Revoke or regenerate client credentials if needed.

Read more about how OAuth 2.0 tokens work in Matomo.