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
No related tags found
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 "" !!! warning ""
:construction: Section under Construction :construction: :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. 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" Fetches metadata to customize the mail (Public name, instance url).
[cozy-stack](https://docs.cozy.io/en/cozy-stack/jobs/#cron-syntax)
### Testing 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.
\ No newline at end of file
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 ...@@ -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. - Further jobs will not need to change scope again and will only ask for refresh tokens.
### Flow summarized ### Konnector Flow summarized
![Konnector flow](/img/flowgrdf.jpeg) ```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" !!! info "to do"
:construction: Request PCE's frequency :construction: :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
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 ## 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 ...@@ -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. These APIs implement Oauth 2.0 protocol, it requires authentication from the customer along with its given consent.
### Enedis Data Connect See both **[Enedis](./use_cases/enedis.md)** and **[Grdf](./use_cases/grdfadict.md)** use cases before going further.
!!! 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}**
### Cozy Oauth Protocol ### Cozy Oauth Protocol
!!! info "cozy oauth flow documentation" !!! 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 ...@@ -234,7 +104,16 @@ With that in mind, the proxy is now the one calling the auth and token provider
#### Proxy flow #### 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 ## 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: ...@@ -14,6 +14,8 @@ theme:
markdown_extensions: markdown_extensions:
- admonition - admonition
- plantuml_markdown:
server: http://www.plantuml.com/plantuml
- attr_list - attr_list
- pymdownx.emoji - pymdownx.emoji
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment