From a31a85734b5e4b4176fb7927095c9e2751da5b62 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Sun, 7 Jan 2018 10:42:38 +0100 Subject: [PATCH 1/5] Add documentation for the new login flow Fixes #620 Signed-off-by: Roeland Jago Douma --- .../client_apis/LoginFlow/index.rst | 51 +++++++++++++++++++ developer_manual/client_apis/index.rst | 7 +++ 2 files changed, 58 insertions(+) create mode 100644 developer_manual/client_apis/LoginFlow/index.rst diff --git a/developer_manual/client_apis/LoginFlow/index.rst b/developer_manual/client_apis/LoginFlow/index.rst new file mode 100644 index 000000000..5b68f4343 --- /dev/null +++ b/developer_manual/client_apis/LoginFlow/index.rst @@ -0,0 +1,51 @@ +.. _loginflowindex: + +========== +Login Flow +========== + +This document provides a quick overview of the new login flow that should be used by clients to obtain +login credentials. This will assure that each client gets it own set of credentials. This has several advantages: + +1. The client never stores the password of the user +2. The user can revoke on a per client basis from the web + +Opening the webview +------------------- + +The client should open a webview to :code:`/index.php/login/flow`. Be sure to set the :code:`OCS-APIREQUEST` +header to :code:`true`. + +The client will register an URL handler to catch urls of the :code:`nc` protocol. This is required the obtain the +credentials in the final stage. + +This should be a one time webview. Which means: +* There should be no cookies set when creating the webview +* Passwords should not be stored +* No state should be preserved after the webview has terminated + +To have a good user experince please to considet he following things: +* set the proper :code:`ACCEPT_LANGUAGE` header +* set a proper :code:`USER_AGENT` header + + +Login in the user +----------------- + +The user will now see a webpage telling them they will grant access to :code:`USER_AGENT`. When they follow the setps +they will be asked to login. If they have two factor authentication enabled they will require this to login. But since +this is all in the webview itself the client does not need to care about this. + + +Obtaining the login credentials +------------------------------- + +On the final login the server will do a redirect to a url of the following format: + +.. code:: + + nc://login/server:&user:&password: + + +This information will be used by the client to create a new account. +After this the webview is destroyed including all the state the webview holds. diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst index bb3cf41fc..25a0c14d6 100644 --- a/developer_manual/client_apis/index.rst +++ b/developer_manual/client_apis/index.rst @@ -24,10 +24,17 @@ Other OCS API documentations: * `Notifications API - Register a device for push notifications `_ +Login Flow +---------- + +Clients can obtain an apptoken via the login flow. See :doc:`LoginFlow/index` + + .. toctree:: :maxdepth: 2 :hidden: WebDAV/index OCS/index + LoginFlow/index From 2de2c65237279268e60c45f89ba8c89103bbc56f Mon Sep 17 00:00:00 2001 From: Tobias Kaminsky Date: Tue, 9 Jan 2018 07:29:53 +0100 Subject: [PATCH 2/5] Typos --- developer_manual/client_apis/LoginFlow/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/developer_manual/client_apis/LoginFlow/index.rst b/developer_manual/client_apis/LoginFlow/index.rst index 5b68f4343..e4b8f8b47 100644 --- a/developer_manual/client_apis/LoginFlow/index.rst +++ b/developer_manual/client_apis/LoginFlow/index.rst @@ -16,7 +16,7 @@ Opening the webview The client should open a webview to :code:`/index.php/login/flow`. Be sure to set the :code:`OCS-APIREQUEST` header to :code:`true`. -The client will register an URL handler to catch urls of the :code:`nc` protocol. This is required the obtain the +The client will register an URL handler to catch urls of the :code:`nc` protocol. This is required to obtain the credentials in the final stage. This should be a one time webview. Which means: @@ -24,15 +24,15 @@ This should be a one time webview. Which means: * Passwords should not be stored * No state should be preserved after the webview has terminated -To have a good user experince please to considet he following things: -* set the proper :code:`ACCEPT_LANGUAGE` header +To have a good user experince please consider the following things: +* set a proper :code:`ACCEPT_LANGUAGE` header * set a proper :code:`USER_AGENT` header Login in the user ----------------- -The user will now see a webpage telling them they will grant access to :code:`USER_AGENT`. When they follow the setps +The user will now see a webpage telling them they will grant access to :code:`USER_AGENT`. When they follow the steps they will be asked to login. If they have two factor authentication enabled they will require this to login. But since this is all in the webview itself the client does not need to care about this. From f47c0c4e0ccca3945b128f27767ae0f319772c02 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Tue, 9 Jan 2018 14:45:13 +0100 Subject: [PATCH 3/5] Explain parameters Signed-off-by: Roeland Jago Douma --- developer_manual/client_apis/LoginFlow/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/developer_manual/client_apis/LoginFlow/index.rst b/developer_manual/client_apis/LoginFlow/index.rst index e4b8f8b47..13bdd4276 100644 --- a/developer_manual/client_apis/LoginFlow/index.rst +++ b/developer_manual/client_apis/LoginFlow/index.rst @@ -46,6 +46,9 @@ On the final login the server will do a redirect to a url of the following forma nc://login/server:&user:&password: +* server: The address of the server to connect to. The server may specify a protocol (http or https). If no protocol is specified the client will assume https. +* username: The username that the client must use to login +* password: The password that the client must use to login and store securely This information will be used by the client to create a new account. After this the webview is destroyed including all the state the webview holds. From e03f433d062483c5260b6500616c7deb7bb51619 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Thu, 11 Jan 2018 09:39:25 +0100 Subject: [PATCH 4/5] Note about subfolder Signed-off-by: Roeland Jago Douma --- developer_manual/client_apis/LoginFlow/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/developer_manual/client_apis/LoginFlow/index.rst b/developer_manual/client_apis/LoginFlow/index.rst index 13bdd4276..7bb2f8d5f 100644 --- a/developer_manual/client_apis/LoginFlow/index.rst +++ b/developer_manual/client_apis/LoginFlow/index.rst @@ -52,3 +52,5 @@ On the final login the server will do a redirect to a url of the following forma This information will be used by the client to create a new account. After this the webview is destroyed including all the state the webview holds. + +.. note:: On nextcloud 12 the returned server is just the server address without any possible subfolder. This is corrected in Nextcloud 13. From 7e05981dd123ab51f65e361a1a0aded6f31954bd Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Tue, 30 Jan 2018 11:42:13 +0100 Subject: [PATCH 5/5] Fix typo Signed-off-by: Morris Jobke --- developer_manual/client_apis/LoginFlow/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_manual/client_apis/LoginFlow/index.rst b/developer_manual/client_apis/LoginFlow/index.rst index 7bb2f8d5f..d65704b22 100644 --- a/developer_manual/client_apis/LoginFlow/index.rst +++ b/developer_manual/client_apis/LoginFlow/index.rst @@ -53,4 +53,4 @@ On the final login the server will do a redirect to a url of the following forma This information will be used by the client to create a new account. After this the webview is destroyed including all the state the webview holds. -.. note:: On nextcloud 12 the returned server is just the server address without any possible subfolder. This is corrected in Nextcloud 13. +.. note:: On Nextcloud 12 the returned server is just the server address without any possible subfolder. This is corrected in Nextcloud 13.