Description
This section of documentation refers to the Oauth protocols 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 and grdf konnector documentation.
Oauth Dance
To access customer data, one must first obtain customer authorization. This authorization is materialized by an access token and it must be obtained by the APIs exposed by each energy providers.
These APIs implement Oauth 2.0 protocol, it requires authentication from the customer along with its given consent.
See both Enedis and Grdf use cases before going further.
Cozy Oauth Protocol
CouchDB
The CouchDB database must hold all information needed for the konnector authentication to work properly.
Auth information are stored in the secrets/io-cozy-account_types database. You can create manually the document by entering these parameters for each konnector:
| Name | Description |
|---|---|
| _id | Name of your konnector, for instance: enedisgrandlyon |
| grant_mode | authorization_code |
| client_id | Application id given by the API provider |
| client_secret | Secret also given by the API provider |
| auth_endpoint | Authorize endpoint to request when starting the oauth protocol |
| token_endpoint | Token endpoint to request, will be called when the auth endpoint response reaches the stack |
| token_mode | get |
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 information 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 all cozy applications are hosted on different personal clouds, 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 issue, two solutions are possible depending on what the energy supplier is willing to do.
- Providers could allow wildcard subdomains when registering the callback URI, it would parse the subdomain and adapt its redirection when answering /auth call.
https//*.cozygrandlyon.cloud/account/redirect -> parse subdomain before .cozy
xyz.cozygrandlyon.cloud/account/redirect -> redirect to xyz
toto.cozygrandlyon.cloud/account/redirect -> redirect to toto
- If the provider (Enedis for instance) is not accepting wildcards, then we put a proxy as a middleware to provide a generic endpoint to cater for all Oauth2 redirection.
Result
With that in mind, the proxy is now the one calling the auth and token provider endpoints. The instance name will be contained in redirect_uri, the stack will insert this parameters by itself in the /auth call.
3 endpoints are created in the proxy for each energy supplier:
- One for the auth
- One for the token
- One for the redirect uri
Proxy flow
Proxy Code Explained
Feel free to check the proxy code at all time when reading this documentation.
The proxy is coded in golang.
It is composed of six endpoints as seen above. The first endpoint to be called is /auth.
auth
Originally called from a cozy-stack trying to setup its konnector. The proxy gets these information from the query:
- client_id
- duration
- redirect_uri (auto inserted by the cozy-stack, except if you specify skip_redirect_uri:true in the CouchDB)
- response_type
- state (as it was conceived by the cozy-stack)
The state will be merged with the instance name, then decomposed again when reaching /redirect. This way the proxy is able to keep track of the cozy instance originally calling.
With all these information, the proxy can contact the provider /auth endpoint to start the oauth dance.
Enedis
See that a new composed state is sent to enedis, it is made of the former state conceived by the cozy-stack + the original instance name. This will be useful 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.
Grdf
To be redacted
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).
The state must be recovered without the instance name, otherwise the cozy-stack won't recognized it and the handshake will fail.
token
Gathering from query or parameters all params.
Sends a post request to the provider /token endpoint. The stack will store the response params in a accounts CouchDB database.