Adds guide for OAuth2 plugin, #PG-4998

app/helpers/Content/Category/IntegrateCategory.php

@@ -31,6 +31,7 @@ public function getItems()
             new Guide('reporting-introduction'),
             new RemoteLink('Integrations', 'https://matomo.org/integrate/'),
             new Guide('tagmanager/introduction'),
+            new Guide('oauth2'),
             new Guide('ab-tests'),
             new Guide('heatmap-session-recording'),
             new Guide('crash-analytics'),

docs/5.x/authentication-in-depth.md

@@ -9,6 +9,7 @@ There are different ways a user can authenticate in Matomo:
 * Using username / password and the regular login form. 
 * The [logme](https://matomo.org/faq/how-to/faq_30/) feature can be used to log someone in using username and password in the URL. 
 * Using a `token_auth` URL parameter for our HTTP API's and widgets.
+* Using OAuth2 bearer tokens for external applications when the OAuth2 plugin is installed.
 
 ## Username and password login
 
@@ -64,6 +65,14 @@ When there is a request and we can use a session, then Matomo [checks first if t
 * When a `token_auth` parameter is set by us, then we usually POST the token_auth. This is for security reasons so the token_auth won't appear in server logs. Otherwise a sysadmin could see the token in the logs and do all sort of actions on behalf of another user.
 * Remember that users should not share the token_auth as it is the same as them sharing their username/password.
 
+## OAuth2
+
+If the [OAuth2](/guides/oauth2) plugin is installed, external applications can authenticate against Matomo using OAuth2 access tokens.
+
+This is mainly useful when integrating third-party or custom applications that should not receive a long-lived `token_auth`. In that case the application first obtains an access token through the plugin's OAuth2 endpoints and then sends that token as a bearer token when calling supported Matomo APIs.
+
+Depending on the application type, you would typically use either the Authorization Code flow with PKCE or the Client Credentials flow. For the integration flow and request examples, see the [OAuth2 guides](/guides/oauth2).
+
 ## Alternative login plugins
 
 It is possible to write plugins that provide [alternative Login methods](https://plugins.matomo.org/search?query=login&post_type=product) like [LDAP](https://plugins.matomo.org/LoginLdap), [SAML](https://plugins.matomo.org/LoginSaml), etc.

docs/5.x/oauth2.md

@@ -0,0 +1,18 @@
+---
+category: Integrate
+subGuides:
+  - oauth2/setup
+  - oauth2/authorization-code
+  - oauth2/client-credentials
+  - oauth2/api-usage
+  - oauth2/faq
+---
+# OAuth2
+
+This section contains guides that will help you authenticate external applications against Matomo using OAuth2.
+
+**OAuth2** is a plugin for Matomo that adds a first-party OAuth2 Authorization Server. It allows external applications to access Matomo APIs using OAuth2 access tokens instead of sending a `token_auth`.
+
+The plugin supports the **Authorization Code** flow with **PKCE**, **Client Credentials**, and **Refresh Token** support. OAuth clients can be managed in Matomo under **Administration => Platform => OAuth2**. In Matomo Cloud, this screen is available under **Administration => Export => OAuth2**.
+
+If you are looking for general API authentication details, also see [Authentication In Depth](/guides/authentication-in-depth) and [Querying the Reporting API](/guides/querying-the-reporting-api).

docs/5.x/oauth2/api-usage.md

@@ -0,0 +1,38 @@
+---
+category: Integrate
+title: OAuth2 API Usage
+---
+# Calling Matomo APIs with OAuth2
+
+Once your application has obtained an access token, it can call Matomo APIs using the `Authorization` header.
+
+```text
+Authorization: Bearer ACCESS_TOKEN
+```
+
+## Example API request
+
+```bash
+curl 'https://matomo.example.com/index.php' \
+  -H 'Authorization: Bearer ACCESS_TOKEN' \
+  -d 'module=API' \
+  -d 'method=VisitsSummary.get' \
+  -d 'idSite=1' \
+  -d 'period=day' \
+  -d 'date=today' \
+  -d 'format=json'
+```
+
+## OAuth2 compared to `token_auth`
+
+By default, many Matomo API guides use `token_auth` examples because `token_auth` is available in every Matomo installation.
+
+When the OAuth2 plugin is installed, external applications can use OAuth2 bearer tokens instead. This avoids sharing a long-lived auth token with the external application and lets you choose a grant type that matches the integration.
+
+If you are integrating a backend service with no user interaction, the Client Credentials flow is usually the best fit. If your application acts on behalf of a user, use the Authorization Code flow.
+
+## Notes
+
+* Use HTTPS whenever you send access tokens.
+* The plugin currently allows only one scope per request.
+* Keep using the standard `token_auth` flow in integrations where the OAuth2 plugin is not installed.

docs/5.x/oauth2/authorization-code.md

@@ -0,0 +1,132 @@
+---
+category: Integrate
+title: OAuth2 Authorization Code Flow
+---
+# OAuth2 Authorization Code Flow
+
+Use the Authorization Code flow when your application acts on behalf of a Matomo user.
+
+## Flow overview
+
+The Authorization Code flow works like this:
+
+1. Your application redirects the user to the Matomo authorization endpoint.
+2. The user logs in and approves access.
+3. Matomo redirects back with an authorization `code`.
+4. Your application exchanges the code for an access token.
+5. Your application calls Matomo APIs using `Authorization: Bearer ACCESS_TOKEN`.
+
+## PKCE for public clients
+
+Public clients should use PKCE. PKCE requires a `code_verifier` and a derived `code_challenge`.
+
+Example values:
+
+```text
+code_verifier = dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+code_challenge = E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+```
+
+Where:
+
+```text
+code_challenge = BASE64URL(SHA256(code_verifier))
+```
+
+## Redirect the user to the authorization endpoint
+
+### Public client with PKCE
+
+```text
+https://matomo.example.com/index.php?module=OAuth2&action=authorize
+&response_type=code
+&client_id=analytics_app
+&redirect_uri=https://example-app.com/oauth/callback
+&scope=matomo:read
+&state=abc123
+&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+&code_challenge_method=S256
+```
+
+### Confidential client
+
+```text
+https://matomo.example.com/index.php?module=OAuth2&action=authorize
+&response_type=code
+&client_id=analytics_app
+&redirect_uri=https://example-app.com/oauth/callback
+&scope=matomo:read
+&state=abc123
+```
+
+After the user approves access, Matomo redirects back to your application:
+
+```text
+https://example-app.com/oauth/callback?code=AUTHORIZATION_CODE&state=abc123
+```
+
+## Exchange the authorization code for tokens
+
+The requested scope needs to match the client configuration. At the time of writing, the plugin allows only one scope per request.
+
+### PKCE token request
+
+```bash
+curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -d 'grant_type=authorization_code' \
+  -d 'client_id=analytics_app' \
+  -d 'redirect_uri=https://example-app.com/oauth/callback' \
+  -d 'code=AUTHORIZATION_CODE' \
+  -d 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
+```
+
+### Confidential client token request
+
+```bash
+curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -d 'grant_type=authorization_code' \
+  -d 'client_id=analytics_app' \
+  -d 'client_secret=7fa9c0f81b8b4a12' \
+  -d 'redirect_uri=https://example-app.com/oauth/callback' \
+  -d 'code=AUTHORIZATION_CODE'
+```
+
+## Example token response
+
+```json
+{
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "def50200a1b9"
+}
+```
+
+## Refresh an access token
+
+### Public client
+
+```bash
+curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -d 'grant_type=refresh_token' \
+  -d 'client_id=analytics_app' \
+  -d 'refresh_token=def50200a1b9'
+```
+
+### Confidential client
+
+```bash
+curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -d 'grant_type=refresh_token' \
+  -d 'client_id=analytics_app' \
+  -d 'client_secret=7fa9c0f81b8b4a12' \
+  -d 'refresh_token=def50200a1b9'
+```
+
+## What to read next
+
+Once you have an access token, see [Calling Matomo APIs with OAuth2](/guides/oauth2/api-usage).

docs/5.x/oauth2/client-credentials.md

@@ -0,0 +1,42 @@
+---
+category: Integrate
+title: OAuth2 Client Credentials Flow
+---
+# OAuth2 Client Credentials Flow
+
+Use the Client Credentials flow when a backend service needs to access Matomo APIs without user interaction.
+
+Typical examples include:
+
+* Internal analytics dashboards
+* Scheduled exports
+* Backend integrations
+
+## Request an access token
+
+```bash
+curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -d 'grant_type=client_credentials' \
+  -d 'client_id=analytics_app' \
+  -d 'client_secret=7fa9c0f81b8b4a12' \
+  -d 'scope=matomo:read'
+```
+
+## Example token response
+
+```json
+{
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+Depending on your client configuration, a refresh token may also be available through the token endpoint for supported grant types.
+
+## When to use this flow
+
+Use this flow only for trusted server-side applications that can keep credentials secret.
+
+If the application needs a user to log in and approve access, use the [Authorization Code flow](/guides/oauth2/authorization-code) instead.

docs/5.x/oauth2/faq.md

@@ -0,0 +1,57 @@
+---
+category: Integrate
+title: OAuth2 Developer FAQ
+---
+# OAuth2 Developer FAQ
+
+## Which grant types are supported?
+
+The plugin supports:
+
+* Authorization Code with PKCE
+* Client Credentials
+* Refresh Token
+
+## Which scopes are available?
+
+The plugin provides these scopes:
+
+* `matomo:read`
+* `matomo:write`
+* `matomo:admin`
+* `matomo:superuser`
+
+At the time of writing, only one scope can be requested at a time.
+
+## When should I use a public client?
+
+Use a public client when your application cannot safely store a client secret, for example in a browser or mobile app. Public clients should use PKCE.
+
+## When should I use a confidential client?
+
+Use a confidential client when your application runs on a trusted backend and can safely protect the client secret.
+
+## Where do I manage OAuth clients?
+
+Use one of these screens:
+
+```text
+Administration => Platform => OAuth2   (Matomo On-Premise)
+Administration => Export => OAuth2     (Matomo Cloud)
+```
+
+## Which endpoints does the plugin expose?
+
+The plugin exposes these endpoints:
+
+* `/index.php?module=OAuth2&action=authorize`
+* `/index.php?module=OAuth2&action=token`
+
+Optional cleaner routes can also be configured:
+
+* `/oauth2/authorize`
+* `/oauth2/token`
+
+## Can I still use `token_auth`?
+
+Yes. The OAuth2 plugin adds an alternative authentication method for external applications. Existing `token_auth` based integrations continue to be relevant for Matomo installations where the plugin is not enabled.