From 21f7d22b0053fe2a9434e44325031a3fa2731544 Mon Sep 17 00:00:00 2001
From: Hugo <hnouts@grandlyon.com>
Date: Tue, 7 Jul 2020 19:01:07 +0200
Subject: [PATCH] work in progress - proxy desc

---
 docs/proxy/description.md | 73 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 72 insertions(+), 1 deletion(-)

diff --git a/docs/proxy/description.md b/docs/proxy/description.md
index c41607f..c2d04e2 100644
--- a/docs/proxy/description.md
+++ b/docs/proxy/description.md
@@ -105,10 +105,81 @@ Regarding Enedis, two endpoints are exposed:
 On success, response will contain **access_token** or **refresh_token**, **usage_point_id** among other things. All informations will be stored by the cozy-stack in a cozy-accounts database.
 
 ### Cozy Oauth Protocol
-#### Cozy Account
+
+!!! info "cozy oauth flow documentation" 
+    [https://docs.cozy.io/en/cozy-stack/konnectors-workflow/#reminder-oauth-flow](https://docs.cozy.io/en/cozy-stack/konnectors-workflow/#reminder-oauth-flow)
+
+#### Couchdb
+
+It is necessary to add in a couchdb database all informations needed for the konnector authentication to work properly.
+
+Auth informations are stored in the **secrets/io-cozy-account_types** database.
+You can create manually the document by entering these parameters:
+
+<table>
+  <colgroup>
+    <col width="30%">
+    <col width="70%">
+  </colgroup>
+  <thead>
+    <tr class="header">
+      <th>Name</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>_id</td>
+      <td>Name of your konnector, for instance: enedisgrandlyon</td>
+    </tr>
+    <tr>
+      <td>grant_mode</td>
+      <td>authorization_code</td>
+    </tr>
+    <tr>
+      <td>client_id</td>
+      <td>Application id given by the API provider</td>
+    </tr>
+    <tr>
+      <td>client_secret</td>
+      <td>Secret also given by the API provider</td>
+    </tr>
+    <tr>
+      <td>auth_endpoint</td>
+      <td>Authorize endpoint to request when starting the oauth protocol</td>
+    </tr>
+    <tr>
+      <td>token_endpoint</td>
+      <td>Token endpoint to request, will be called when the auth endpoint response reaches the stack</td>
+    </tr>
+    <tr>
+      <td>token_mode</td>
+      <td>get</td>
+    </tr>
+  </tbody>
+</table>
+
+Once the document is created, when launching the konnector from the cozy-home or inside the running application. The oauth flow will start.
+
+The cozy-stack will request the authorize endpoint, then call the token endpoint with the code received from the auth step.
+
+If the token request is a success. An account/service-name database will be added in couchdb containing all informations needed for authentication and the konnector will be free to work on all endpoints within its scope.
+
 ### Why we Need a Proxy
+
+The Oauth dance could be easily wrapped up with the two requests seen above. But since Ecolyo is an application hosted on multiple personnal cloud, following this guideline would mean that we need a **client_id** and a **client_secret** for each one of all the applications running.
+
+To answer this problem, it was decided to run a proxy as a middleware that would provide a generic endpoint to cater for all Oauth2 redirections and redirect to the stack that was originally calling the protocol.
+
 #### Result
 
+Henceforth the proxy is now the one calling the auth and token endpoints. It's also the proxy that is registered as redirect_uri.
+
+3 endpoints are created in the proxy:
+- One for the auth (called by the cozy-stack)
+- One for the token (also called by the cozy-stack)
+- One for the redirect_uri (called by the service provider, Enedis)
+
 ## Proxy Code Explained
 
 ## What Happens Next
\ No newline at end of file
-- 
GitLab