From 7e8f1057b7a1fa9898fea776f39a7ac197ee9a2c Mon Sep 17 00:00:00 2001
From: Jonathan Klee <jonathan.klee@e.email>
Date: Fri, 31 Oct 2025 08:57:12 +0100
Subject: [PATCH] chore: Bootstrap SSO documentation

---
 README.md         |  1 +
 doc/sso/README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 doc/sso/README.md

diff --git a/README.md b/README.md
index ff1700d85..11d532734 100644
--- a/README.md
+++ b/README.md
@@ -36,3 +36,4 @@ The most important libraries which are used by DAVx⁵ (alphabetically):
 * [okhttp](https://square.github.io/okhttp) – [Apache License, Version 2.0](https://square.github.io/okhttp/#license)
 
 See _About / Libraries_ in the app for all used libraries and their licenses.
+
diff --git a/doc/sso/README.md b/doc/sso/README.md
new file mode 100644
index 000000000..c3f3c3ba5
--- /dev/null
+++ b/doc/sso/README.md
@@ -0,0 +1,77 @@
+# Murena ID in /e/OS Account Manager
+
+## Overview
+
+/e/OS Account Manager simplifies user authentication across /e/OS services with an uniq Murena ID, especially for **Murena Workspace** accounts. Users log in once to access multiple services (email, drive, calendar, contacts, etc.) without repeated credential entry, enhancing both security and user experience.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant AccountManager as /e/OS AccountManager
+    participant IdP as Identity Provider (OIDC Server)
+    participant ResourceServer as Murena Workspace
+
+    User->>AccountManager: Initiates login
+    AccountManager->>IdP: Redirects to identity provider for authentication
+    IdP-->>User: Presents login page
+    User->>IdP: Enters credentials
+    IdP->>IdP: Validates credentials
+    IdP-->>User: Returns authorization code
+    User->>AccountManager: Authorization code
+    AccountManager->>IdP: Exchanges code for ID token, refresh token & access token
+    IdP-->>AccountManager: Returns ID token, refresh token & access token
+    AccountManager->>ResourceServer: Requests resource with access token
+    ResourceServer-->>AccountManager: Returns protected resource
+    AccountManager-->>User: Grants access to services
+```
+
+## Communication between /e/OS AccountManager and Android AccountManager
+
+When a user has logged in, **/e/OS Account Manager** stores the access token in a JSON `AuthState` and save the latter in the **Android AccountManager**:
+
+```mermaid
+sequenceDiagram
+    participant eAM as /e/OS AccountManager
+    participant AM as android.os.AccountManager
+
+    eAM->>+AM: setUserData(account, "auth_state", AuthState)
+```
+
+## Communication between clients and /e/OS AccountManager
+
+A **client** (e.g. Mail, Calendar, eDrive etc) who wants to communication with **MurenaWorkspace** will first need to get an access token stored in **Android AccountManager**:
+
+```mermaid
+sequenceDiagram
+    participant Mail
+    participant AM as android.os.AccountManager
+    Mail->>+AM: getUserData(account, "auth_state")
+    AM-->>-Mail: AuthState (JSON containing the access token)
+```
+
+
+## Communication between clients and MurenaWorkspace
+
+This client will integrate the access token in its HTTP requests:
+
+`Authorization: Bearer <client_access_token>`
+
+### Mail
+
+```mermaid
+sequenceDiagram
+    participant Mail
+    participant MW as MurenaWorkspace
+
+    Mail->>+MW: SMTP Request with `Authorization: Bearer <access_token>` header
+```
+
+### eDrive
+
+```mermaid
+sequenceDiagram
+    participant eDrive
+    participant MW as MurenaWorkspace
+
+    eDrive->>+MW: HTTP Request with `Authorization: Bearer <access_token>` header
+```
-- 
GitLab