Amend authentication docs.

Author: lukasgraf

documentation/reference/qfieldcloud/logins.en.md renamed to documentation/reference/qfieldcloud/auth.en.md

@@ -1,42 +1,55 @@
 ---
-title: Third-party login
-tx_slug: documentation_reference_qfieldcloud_sso_auth
+title: Authentication
+tx_slug: documentation_reference_qfieldcloud_auth
 ---
 
-# Third-party authentication
+# Authentication
 
-QFieldCloud and QField / QFieldSync clients allow authentication using regular login and password, for a user that is already registered on QFieldCloud.
+QFieldCloud and QField / QFieldSync clients allow authentication using regular username and password, or, if configured, **OpenID Connect** with a third-party identity provider.
 
-It is also possible to authenticate using a third-party identity provider (e.g. Google, [OpenID Connect](https://openid.net/developers/how-connect-works/)).
+## OpenID Connect authentication
+
+[OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) is an industry standard authentication protocol on top of [OAuth2](https://oauth.net/2/) that allows to delegate authentication to an identity provider (IDP) such as Google, Microsoft, or any other OpenID Connect compliant provider. This allows users to log in to QFieldCloud using their existing accounts with these providers, without needing to create a separate account for QFieldCloud.
+
+OIDC can be used directly for signing up with QFieldCloud, or for signing in to an existing QFieldCloud account (matched via verified email address).
 
 Here is a sequence diagram of how a third-party login happens in QFieldCloud (in the browser):
 
 ```mermaid
 sequenceDiagram
     autonumber
 
-    actor User
+    actor User as User (Browser)
     participant QFC as QFieldCloud
 
     User ->> QFC: Access login page
     QFC -->> User: Display login form with configured third-party login buttons
 
     User ->> QFC: Click third-party login button
 
+    QFC -->> User: Redirect to IDP for login
     create participant IDP as Identity Provider
-    QFC ->> IDP: Redirect to IDP for login
-    IDP -->> User: Display IDP's login form
+    User ->> IDP: Follow redirect to IDP login page
+    IDP -->> User: Display IDP's login page
 
-    User ->> IDP: Log in using IDP's credentials
-    destroy IDP
+    User ->> IDP: Authenticate using IDP credentials
 
-    IDP ->> QFC: Redirect back with auth details
+    IDP -->> User: Redirect to QFieldCloud callback URL with authorization code
+    User ->>+ QFC: Hand authorization code to QFieldCloud
+    QFC ->> IDP: Exchange authorization code for access token and ID token
+    IDP -->> QFC: Return access token + ID token
+
+    Note over QFC: Validate ID token signature
+
+    QFC ->> IDP: Request user profile information
+    destroy IDP
+    IDP -->> QFC: Return user profile information
 
-    alt User does not already have a QFieldCloud account
-    note over QFC: QFieldCloud account is created using IDP auth details
+    alt If user does not already have a QFieldCloud account
+    note over QFC: QFieldCloud account is created using IDP profile infos
     end
 
-    QFC -->> User: User is logged in
+    QFC -->>- User: Log user in (establish session)
 ```
 
 Here is a sequence diagram of how third-party authentication happens in QField and QFieldSync:

mkdocs.yml

@@ -105,6 +105,7 @@ nav:
           - reference/qfieldcloud/workflow.md
           - reference/qfieldcloud/concepts.md
           - reference/qfieldcloud/projects.md
+          - reference/qfieldcloud/auth.md
           - reference/qfieldcloud/permissions.md
           - reference/qfieldcloud/jobs.md
           - reference/qfieldcloud/secrets.md