Wiki source code of Human Data Gateway
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
3.1 | 1 | == Introduction == |
| |
1.1 | 2 | |
| |
3.1 | 3 | This page describes how to access data via the Human Data Gateway (HDG). The HDG service was installed to control access to sensitive human data which is shared in strongly pseudonymized form. |
| |
1.1 | 4 | |
| |
3.1 | 5 | === What datasets are available? === |
| 6 | |||
| 7 | Datasets that are released in Knowledge Graph v2 or v3 are available. The [[KG's controlled access filter>>https://search.kg.ebrains.eu/?facet_type[0]=Dataset&facet_Dataset_dataAccessibility[0]=Controlled%20access]] can be used to list datasets accessed via the HDG. | ||
| 8 | |||
| 9 | == Access via the UI == | ||
| 10 | |||
| 11 | (% class="wikigeneratedid" %) | ||
| 12 | In order to access those datasets, the following steps are involved: | ||
| 13 | |||
| 14 | 1. A user finds a dataset in the Knowledge Graph and logs in to the KG (or vice versa) | ||
| 15 | 1. The user requests access to the dataset from the Get Data section of the dataset card. | ||
| 16 | 1. The HDG service verifies that the user is authenticated. | ||
| 17 | 1. An e-mail is then sent to the user with the [[Data Use Agreement>>https://ebrains.eu/terms/#data-use-agreement]] and a link. | ||
| 18 | 1. By clicking the link in the e-mail, the user accepts the terms and proves s/he has access to the e-mail. The same link can be used multiple times within a predefined period (currently 24 hours). | ||
| 19 | 1. Clicking the link directs the user to the HDG service which: | ||
| 20 | 11. verifies that the user is authenticated, and | ||
| 21 | 11. logs the consent to the DUA and the access to the data. | ||
| 22 | 11. redirects the user to a data-proxy UI interface providing access to the objects in the dataset | ||
| 23 | 1. The user can browse the dataset contents. | ||
| 24 | |||
| 25 | == Programmatic access == | ||
| 26 | |||
| 27 | Programmatic access to the HDG service was mainly designed to allow other services to consume controlled data on behalf of the end-user. For example, a user can browse a controlled brain scan. The image viewer will then programmatically access the HDG controlled data and the end-user will validate the access in her/his e-mail. | ||
| 28 | |||
| 29 | === Access to datasets shared via the Human Data Gateway === | ||
| 30 | |||
| 31 | You can now browse Knowledge Graph datasets through the data proxy as an authenticated user via the datasets API: [[https:~~/~~/data-proxy.ebrains.eu/api/docs#/datasets>>https://data-proxy.ebrains.eu/api/docs#/datasets]] | ||
| 32 | |||
| |
2.1 | 33 | To get access to datasets protected by the HDG, use the (% style="background-color:lightgray" %)datasets/{dataset_id}(%%) endpoint. |
| |
1.1 | 34 | |
| |
2.1 | 35 | 1. First perform a (% style="background-color:lightgray" %)POST /datasets/{dataset_id}(%%) request to start the HDG flow. |
| |
3.1 | 36 | 1. An e-mail is then sent to the user with the Data Use Agreement and a link. By clicking the link, users accept the DUA and prove they have access to the e-mail. |
| 37 | 1. Once the access has been validated, the user is redirected by default to the Knowledge Graph page of the dataset. This redirection can be customized for third-party integration. | ||
| |
1.1 | 38 | |
| |
2.1 | 39 | **Note:** For publicly available datasets, the (% style="background-color:lightgray" %)datasets/{dataset_id}(%%) endpoint can be used via GET, without the extra validation round. |
| |
1.1 | 40 | |
| |
3.1 | 41 | === Example of programmatic integration for a third party === |
| |
1.1 | 42 | |
| 43 | 1. A user wants to access a KG dataset in your third-party application. | ||
| |
2.1 | 44 | 1. The third-party application calls (% style="background-color:lightgray" %)GET /datasets/{dataset_id}(%%) with the user token in order to get information about the dataset or download it. |
| |
1.1 | 45 | (% start="1" style="list-style-type:upper-alpha" %) |
| 46 | 11. The dataset is not protected ~-~-> A successful response is sent. | ||
| |
3.1 | 47 | 11. The dataset is protected ~-~-> An HTTP 401 response is sent back. In the 401 JSON response, a (% style="background-color:lightgray" %)can_request_access(%%) field is specified. If true, it means that it is possible to request access to that dataset using (% style="background-color:lightgray" %)POST /datasets/{dataset_id}(%%). |
| 48 | 1. The third-party application asks the user if they want to request access, and if so then sends (% style="background-color:lightgray" %)POST /datasets/{dataset_id}?redirect_uri=https:~/~/mythirdpartyapp.eu/{dataset_id}(%%). | ||
| |
1.1 | 49 | 1. If the request is successful, an e-mail is sent to the user. |
| |
3.1 | 50 | 1. Once the user has clicked on the e-mail link, access is granted and the user is redirected to (% style="background-color:lightgray" %)https:~/~/mythirdpartyapp.eu/{dataset_id}(%%). |
| |
2.1 | 51 | 1. (% style="background-color:lightgray" %)GET /datasets/{dataset_id}(%%) now answers with successful responses. |
| |
1.1 | 52 | |
| |
3.1 | 53 | === Front-end implementation === |
| |
1.1 | 54 | |
| |
3.1 | 55 | The UI access described above implements this flow and is available at (% style="background-color:lightgray" %)https:~/~/data-proxy.ebrains.eu/datasets/{dataset_id}(%%). |
| |
1.1 | 56 | |
| |
3.1 | 57 |