From 860d8eb5b4ef979381d7f3e1b3a53ef7c6a09d40 Mon Sep 17 00:00:00 2001
From: Hugo <hnouts@grandlyon.com>
Date: Mon, 13 Jul 2020 17:23:16 +0200
Subject: [PATCH] proxy code explained

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

diff --git a/docs/proxy/description.md b/docs/proxy/description.md
index c2d04e2..b116902 100644
--- a/docs/proxy/description.md
+++ b/docs/proxy/description.md
@@ -176,10 +176,56 @@ To answer this problem, it was decided to run a proxy as a middleware that would
 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 flow
+
+stack -> proxy/auth -> enedis/auth -> proxy/redirect -> stack -> proxy/token -> enedis/token
+
+
 ## Proxy Code Explained
 
+!!! info "reminder"
+    Feel free to check the proxy [code](https://forge.grandlyon.com/pocs/cozy/cozy-oauth-proxy) at all time when reading this documentation.
+
+The proxy is coded in golang.
+
+It is composed of three endpoints as seen above. The first endpoint to be called is **/auth**.
+
+#### auth
+
+Originally called from a cozy-stack trying to setup its enedis konnector. The proxy gets this informations from the query:
+
+- clientId
+- state (as it was conceived by the cozy-stack)
+- redirect_uri (**will be used later to trace back the stack**)
+
+With all these informations, the proxy can contact enedis **/auth** endpoint to start the oauth dance.
+
+!!! warning "note"
+    See that a new composed state is sent to enedis, it is made of the former state conceived by the cozy-stack + the cozyOrigin instance name. This will be usefull when enedis is leading the oauth dance to the next step and we will need the name of the cozy to answer.
+
+Once the call is sent, enedis will point to the **/redirect** endpoint.
+
+#### redirect
+
+Retrieve the *code*, *usage_point_id*, and*state* answered by Enedis.
+
+Split the customed state that was modified in the **/auth** process. From this split it creates two variables :
+
+- state
+- host
+
+Finally redirect all these parameters in a query to the cozy-stack (the cozy-stack which is still waiting for an answer from its /auth call).
+
+#### token
+
+Gathering from query or parameters all params.
+
+Sends a post request to enedis /token endpoint. 
+The stack will store the response params in a *accounts* couchdb database.
+
 ## What Happens Next
\ No newline at end of file
-- 
GitLab