There are different ways a user can authenticate in Matomo:
token_auth URL parameter for our HTTP API's and widgets.When a username and password combination is used to log in, then we search in the user table for the matching user and check if the provided password is correct. We are storing passwords using PHP's password_hash.
On successful login we create a session and store a cookie for the session in the user's browser.
This also all applies to the "logme" feature.
Token auths are stored hashed with a salt in the user_token_auth table. See how to create a token auth.
Each user can have multiple tokens. They all have the same permissions and it's not possible to set different permissions or scopes for different tokens.
Token auths are used for the Tracking API, the Reporting API and when embedding widgets
When a token_auth URL parameter is provided, then we don't create a session. This means when a widget is embedded all requests done from this widget need to include the token_auth parameter.
When it is a token_auth, then the authentication happens here. Please note that Matomo will always first authenticate using the anonymous user, and then call the same method again later using the token only. Meaning if you are using the debugger you will see the authenticate method being called twice.
In JavaScript we are adding the correct token_auth value automatically to all requests if you are doing an API request. For all other requests you need to add the token manually. You can add the token_auth to a request either using ajaxRequest.withTokenInUrl(); when it is a request using ajaxHelper.
The Matomo UI uses the token_auth URL parameter to load and change all kind of data. Because the token auths are stored hashed, we cannot get the plain text value of a token and thus not use any configured token_auth from the user_token_auth DB table for these requests.
That's why we create a random token_auth when a user logs into the Matomo UI and store this token as part of the session. To learn more about the session read below. The token is only valid for the specific session and it won't work for anyone else.
When there is a "&force_api_session=1" parameter either in the request GET or POST then we will be starting a session after all even if it is an HTTP API call. In that case we then compare the provided token_auth value from the URL against the token_auth value from the session. At the time of writing this logic is mostly handled here.
For actions that change data we require this parameter to be posted for slightly better security. For API requests that read data it can be a regular URL parameter.
In Javascript there is a method piwik.broadcast.isWidgetizeRequestWithoutSession() that we usually use to decide if we need to append the "force_api_session" URL parameter or not see example.
We are storing session data in the session table.
The session data looks like {data: base64 encoded session data}. If you wanted to see the actual stored data you need to base64 decode the value from the data attribute.
If you are searching for your session ID in the session.id column this won't work as the IDs are stored hashed for security reasons. This way a user with DB access cannot take over someone else's session.
When there is a request and we can use a session, then Matomo checks first if the user is authenticated using the session cookie. If that's not the case, then it falls back to the regular authentication.
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.It is possible to write plugins that provide alternative Login methods like LDAP, SAML, etc.
How this is done is not documented yet unfortunately.