Skip to content
Snippets Groups Projects
Commit cc4d2572 authored by Hugo's avatar Hugo
Browse files

added doc to proxy / konnectors and added plantuml_mardown schemas

parent b01a9224
Branches
Tags
No related merge requests found
Pipeline #10174 passed
Stage: build
Stage: deploy
Hide whitespace changes
Inline Side-by-side
docs/ecolyo/application/services.md
+ 15
− 8
View file @ cc4d2572
!!! warning ""
:construction: Section under Construction :construction:
## Cron Services - Monthly Report
## Cron Services
In order to build an automated task within our cozy-stack, we can create *services* which are javascript files called from a trigger job.
On Ecolyo, we add a trigger that is launched every month with a *cron* attribute. On that trigger we link a .js script then we instanciate this script with cozy-client.
For instance on Ecolyo, to schedule a mail that alert the user a new **monthly report** is available in the application, we add a trigger that is launched every month with a *cron* attribute. On that trigger we link a .js script then we instanciate this script with cozy-client.
### Manifest config example
### Service.js
![Manifest.webapp](monthly-service.png)
### Manifest Config
File location is determined after the build, see [here](https://forge.grandlyon.com/web-et-numerique/llle_project/ecolyo/-/tree/build/services/monthlyReport).
![Manifest.webapp](monthly-service.png)
!!! note "Cron"
See the cron definition at [cozy-stack](https://docs.cozy.io/en/cozy-stack/jobs/#cron-syntax).
### Services
Located under **src\targets\services**
#### Monthly report notification
!!! note "Cron Definition"
[cozy-stack](https://docs.cozy.io/en/cozy-stack/jobs/#cron-syntax)
Fetches metadata to customize the mail (Public name, instance url).
### Testing
\ No newline at end of file
Send mail containing a link to the user instance so that he can be warned about the update of its monthly report and visualize it.
docs/ecolyo/konnectors/grdf.md
+ 20
− 5
View file @ cc4d2572
......@@ -32,13 +32,28 @@ This token holds several meta datas, including the pce_id (id of user's meter) t
- Further jobs will not need to change scope again and will only ask for refresh tokens.
### Flow summarized
![Konnector flow](/img/flowgrdf.jpeg)
### Konnector Flow summarized
```plantuml
Start -> Restart: No Pce_id
Restart -> GetData
GetData -> Grdf_Data_Endpoint
GetData <-- Grdf_Data_Endpoint: Token forbidden scope too low
GetData -> Refresh_Call
Refresh_Call -> Proxy
Proxy -> Grdf_Token_Endpoint: client_credential option
Proxy <-- Grdf_Token_Endpoint: new token
GetData <-- Proxy
Restart <-- GetData
Restart -> GetData
GetData -> ProcessData
ProcessData -> StoreData
```
!!! info "to do"
:construction: Request PCE's frequency :construction:
Grdf owns different type of meters, some are read twice a year (every six months therefore called 6M), others are 1M or 1D
:construction: Add request PCE's frequency :construction:
Grdf owns different type of meters, some are read twice a year (every six months therefore called 6M), others are 1M or 1D. Ecolyo could warn the user if its meter is not suited for the application use.
## Launch on standalone
......
docs/proxy/description.md
+ 11
− 132
View file @ cc4d2572
......@@ -13,137 +13,7 @@ To access customer data, one must first obtain customer authorization. This auth
These APIs implement 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.
> [Authorize API](https://datahub-enedis.fr/data-connect/documentation/authorize-v1/) swagger
Regarding Enedis, two endpoints are exposed:
#### /dataconnect/v1/oauth2/authorize
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>client_id</td>
<td>Unique identifier of the Application</td>
</tr>
<tr>
<td>response_type</td>
<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).
#### /v1/oauth2/token
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</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.
#### Consent Handling
Consent is replaced everytime a new oauth dance is launched (for 6 months, hardcoded in **/authorize** request).
User can revoke its consent from the Enedis website, no external endpoints are available for this purpose.
If a consent has been revoked or expired. A 403 error will be thrown saying: *No consent can be found for this customer and this usage point*.
Ecolyo can warn the user that the service is unable to continue and ask to give new consent.
### Grdf Adict
!!! info "grdf documentation"
Visit https://site.grdf.fr/web/grdf-adict/technique to explore all the services exposed by Grdf.
> Prod endpoints are: https://sofit-sso-oidc.grdf.fr/openam/
Regarding Grdf Adict Oauth connexion, two endpoints are exposed:
!!! warning "Oauth connexion still in Beta"
Grdf Adict Oauth service is called Client Connect and is still in early beta. It is currently lacking a *state* parameter in the Oauth dance.
#### /oauth2/realms/externeGrdf/authorize
#### /oauth2/realms/externeGrdf/access_token
The */access_token* endpoint can be called with two different *grant_type* parameter.
- *authorization_code* gives an access token and will also retrieve the consents list given by the user in session.
- *client_credentials* gives only the access token allowing us to request the data service.
The grdf Konnector would only need to call the *client_credentials* to get a refresh token.
#### Consent Handling
Consent is represented by an access right. This access holds characteristics specific to the consent of the end customer.
##### Optional: Revoke consent from external applications
It is possible to cancel a consent that was given from the user to our service (for test or development purpose for instance).
**api.grdf.fr/adict/v1/droit_acces/{id_accreditation}**
See both **[Enedis](./use_cases/enedis.md)** and **[Grdf](./use_cases/grdfadict.md)** use cases before going further.
### Cozy Oauth Protocol
!!! info "cozy oauth flow documentation"
......@@ -234,7 +104,16 @@ With that in mind, the proxy is now the one calling the auth and token provider
#### Proxy flow
stack -> proxy/auth -> provider/auth -> proxy/redirect -> stack -> proxy/token -> provider/token
```plantuml
Stack -> Proxy: calls
Proxy -> Provider: calls
Proxy <-- Provider: responds with oauth code on proxy/redirect
Stack <-- Proxy: redirect to user instance
Stack -> Proxy: calls
Proxy -> Provider: calls for token or refresh
Proxy <-- Provider: responds
Stack <-- Proxy: token
```
## Proxy Code Explained
......
docs/proxy/use_cases/enedis.md
+ 101
− 0
View file @ cc4d2572
### Enedis Data Connect
!!! info "enedis documentation"
Create an account on https://datahub-enedis.fr/ to explore all the services exposed by Enedis.
> [Authorize API](https://datahub-enedis.fr/data-connect/documentation/authorize-v1/) swagger
Regarding Enedis, two endpoints are exposed:
#### Authorize
##### /dataconnect/v1/oauth2/authorize
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>client_id</td>
<td>Unique identifier of the Application</td>
</tr>
<tr>
<td>response_type</td>
<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
##### /v1/oauth2/token
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</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.
#### Consent Handling
Consent is replaced everytime a new oauth dance is launched (for 6 months, hardcoded in **/authorize** request).
User can revoke its consent from the Enedis website, no external endpoints are available for this purpose.
If a consent has been revoked or expired. A 403 error will be thrown saying: *No consent can be found for this customer and this usage point*.
Ecolyo can warn the user that the service is unable to continue and ask to give new consent.
\ No newline at end of file
docs/proxy/use_cases/grdfadict.md
+ 33
− 0
View file @ cc4d2572
### Grdf Adict
!!! info "grdf documentation"
Visit https://site.grdf.fr/web/grdf-adict/technique to explore all the services exposed by Grdf.
> Prod endpoints are: https://sofit-sso-oidc.grdf.fr/openam/
Regarding Grdf Adict Oauth connexion, two endpoints are exposed:
!!! warning "Oauth connexion still in Beta"
Grdf Adict Oauth service is called Client Connect and is still in early beta. It is currently lacking a *state* parameter in the Oauth dance.
#### Authorize
##### /oauth2/realms/externeGrdf/authorize
#### Token
##### /oauth2/realms/externeGrdf/access_token
The */access_token* endpoint can be called with two different *grant_type* parameter.
- *authorization_code* gives an access token and will also retrieve the consents list given by the user in session.
- *client_credentials* gives only the access token allowing us to request the data service.
The grdf Konnector would only need to call the *client_credentials* to get a refresh token.
#### Consent Handling
Consent is represented by an access right. This access holds characteristics specific to the consent of the end customer.
##### Optional: Revoke consent from external applications
It is possible to cancel a consent that was given from the user to our service (for test or development purpose for instance).
**api.grdf.fr/adict/v1/droit_acces/{id_accreditation}**
mkdocs.yml
+ 2
− 0
View file @ cc4d2572
......@@ -14,6 +14,8 @@ theme:
markdown_extensions:
- admonition
- plantuml_markdown:
server: http://www.plantuml.com/plantuml
- attr_list
- pymdownx.emoji
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment