From b48eb6e9cc3eaeffb672eefeaae7fa4f6c6fe2a9 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoitm@matrix.org>
Date: Fri, 5 Jun 2020 19:14:31 +0200
Subject: [PATCH] SSO Update the documentation

---
 docs/signin.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 54 insertions(+), 3 deletions(-)

diff --git a/docs/signin.md b/docs/signin.md
index e7368137ae..348e29cbdf 100644
--- a/docs/signin.md
+++ b/docs/signin.md
@@ -58,7 +58,7 @@ We get credential (200)
 ```json
 {
   "user_id": "@alice:matrix.org",
-  "access_token": "MDAxOGxvY2F0aW9uIG1hdHREDACTEDb2l0MDgxNjptYXRyaXgub3JnCjAwMTZjaWQgdHlwZSA9IGFjY2VzcwowMDIxY2lkIG5vbmNlID0gfnYrSypfdTtkNXIuNWx1KgowMDJmc2lnbmF0dXJlIOsh1XqeAkXexh4qcofl_aR4kHJoSOWYGOhE7-ubX-DZCg",
+  "access_token": "MDAxOGxvY2F0aW9uIG1hdHREDACTEDb2l0MDgxNjptYXRyaXgub3JnCjAwMTZjaWQgdHlwZSA9IGFjY2VzcwowMDIxY2lr",
   "home_server": "matrix.org",
   "device_id": "GTVREDALBF",
   "well_known": {
@@ -117,7 +117,7 @@ We get the credentials (200)
 ```json
 {
   "user_id": "@alice:matrix.org",
-  "access_token": "MDAxOGxvY2F0aW9uIG1hdHJpeC5vcmREDACTEDZXJfaWQgPSBAYmVub2l0MDgxNjptYXRyaXgub3JnCjAwMTZjaWQgdHlwZSA9IGFjY2VzcwowMDIxY2lkIG5vbmNlID0gNjtDY0MwRlNPSFFoOC5wOgowMDJmc2lnbmF0dXJlIGiTRm1mYLLxQywxOh3qzQVT8HoEorSokEP2u-bAwtnYCg",
+  "access_token": "MDAxOGxvY2F0aW9uIG1hdHJpeC5vcmREDACTEDZXJfaWQgPSBAYmVub2l0MDgxNjptYXRyaXgub3Jnfrfdegfszsefddvf",
   "home_server": "matrix.org",
   "device_id": "WBSREDASND",
   "well_known": {
@@ -145,12 +145,63 @@ Not supported yet in RiotX
   "flows": [
     {
       "type": "m.login.sso"
+    },
+    {
+      "type": "m.login.token"
     }
   ]
 }
 ```
 
-In this case, the user can click on "Sign in with SSO" and the web screen will be displayed on the page `https://homeserver.with.sso/_matrix/static/client/login/` and the credentials will be passed back to the native code through the JS bridge
+In this case, the user can click on "Sign in with SSO" and the native web browser, or a ChromeCustomTab if the device supports it, will be launched on the page
+
+> https://homeserver.with.sso/_matrix/client/r0/login/sso/redirect?redirectUrl=riotx%3A%2F%2Friotx
+
+The parameter `redirectUrl` is set to `riotx://riotx`.
+
+ChromeCustomTabs are an intermediate way to display a WebPage, between a WebView and using the external browser. More info can be found [here](https://developer.chrome.com/multidevice/android/customtabs)
+
+The browser will then take care of the SSO login, which may include creating a third party account, entering an email, or any other possibility.
+
+During the process, user may be asked to validate an email by clicking on a link it contains. The link has to be opened in the browser which initiates the authentication. This is why we cannot use WebView anymore.
+
+Once the process is finished, the web page will call the `redirectUrl` with an extra parameter `loginToken`
+
+> riotx://riotx?loginToken=MDAxOWxvY2F0aW9uIG1vemlsbGEub3JnCjAwMTNpZGVudGlmaWVy
+
+This navigation is intercepted by RiotX by the `LoginActivity`, which will then ask the homeserver to convert this `loginToken` to an access token
+
+RiotX is generating a `txn_id` parameter, to avoid a replay of the request if the loginToken has been leaked.
+*Note*: for the moment RiotX does not send any `session` parameter in this request.
+
+> curl -X POST --data $'{"type":"m.login.token","token":"MDAxOWxvY2F0aW9uIG1vemlsbGEub3JnCjAwMTNpZGVudGlmaWVy","txn_id":"5114076e-40f0-477f-aa50-8ea2442d9dc1"}' 'https://homeserver.with.sso/_matrix/client/r0/login'
+
+```json
+{
+  "type": "m.login.token",
+  "token": "MDAxOWxvY2F0aW9uIG1vemlsbGEub3JnCjAwMTNpZGVudGlmaWVy",
+  "txn_id": "5114076e-40f0-477f-aa50-8ea2442d9dc1"
+}
+```
+
+We get the credentials (200)
+
+```json
+{
+  "user_id": "@alice:homeserver.with.sso",
+  "access_token": "MDAxOWxvY2F0aW9uIG1vemlsbGEub3JnCjAwMTNpZGVudGlmaWVyIGtleQowMDEwY2lkIGdlbiA9IDEKMDAyY2NpZCB1c2",
+  "home_server": "homeserver.with.sso",
+  "device_id": "DETBTVAHCH",
+  "well_known": {
+    "m.homeserver": {
+      "base_url": "https:\/\/homeserver.with.sso\/"
+    },
+    "m.identity_server": {
+      "base_url": "https:\/\/vector.im"
+    }
+  }
+}
+```
 
 ## Reset password