:construction: Section under Construction :construction:
\ No newline at end of file
!!! warning ""
:construction: Section under Construction :construction:
This section of documentation refers to the Enedis Oauth protocol working hand in hand with our custom proxy and the cozy-stack.
To fully understand its whereabouts, you should also look at the [enedis konnector](./konnectors/enedis.md) documentation.
!!! info "proxy code source"
Feel free to check the proxy [code](https://forge.grandlyon.com/pocs/cozy/cozy-oauth-proxy) at all time when reading this documentation.
## Oauth Dance
In order to access customer data from Ecolyo, one must first obtain customer authorization. This authorization is materialized by an access token and it must be obtained by the Authorization API exposed by Enedis.
The API is implemented on Oauth 2.0 protocol, it requires authentication from the customer along with its given consent.
### Enedis Data Connect
!!! info "enedis documentation"
Create an account on https://datahub-enedis.fr/ to explore all the services exposed by Enedis.
<td>Authorization scenario requested. It will always be "code" as Enedis implemented a code grant authorization</td>
</tr>
<tr>
<td>state</td>
<td>Security parameter allowing to maintain the state between the request and the redirection. ** Maximum length of 100 characters ! **</td>
</tr>
<tr>
<td>duration</td>
<td>Duration of the consent requested by the application, ISO 8601 format. It cannot exceed 3 years</td>
</tr>
</tbody>
</table>
!!! important "Important"
The response targets the redirect-uri registered with Enedis (the redirect-uri is our proxy and the response will be explained in details further below when explaining the proxy endpoints mechanics).
#### /token
<table>
<colgroup>
<colwidth="30%">
<colwidth="70%">
</colgroup>
<thead>
<trclass="header">
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>redirect_uri</td>
<td>URI defined when the application was created. Must be secured in https</td>
</tr>
<tr>
<td>content-type</td>
<td>application/json</td>
</tr>
<tr>
<td>grant_type</td>
<td>Authorization type to get an access token. This must be set to “authorization_code” when using an authorization code, and to “refresh_token” when using a refresh token</td>
</tr>
<tr>
<td>client_id</td>
<td>Unique identifier of the Application</td>
</tr>
<tr>
<td>client_secret</td>
<td>Secret of the client application, associated with its client_id</td>
</tr>
<tr>
<td>refresh_token</td>
<td>Refresh token returned to the previous POST request to the /token endpoint</td>
</tr>
<tr>
<td>code</td>
<td>Authorization code returned to the GET request of /authorize endpoint</td>
</tr>
</tbody>
</table>
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.
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>
<colwidth="30%">
<colwidth="70%">
</colgroup>
<thead>
<trclass="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)
