-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
323d95a
commit 403900e
Showing
6 changed files
with
180 additions
and
149 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| ## Glossary | ||
|
|
||
| |Term|Description| | ||
| |------|-------------| | ||
| |Private App|An application/service/ETL tool that is developed by a user who wants to be able to programmatically interact with the Gateway. | | ||
| |AppID and ClientID |Tokens that are generated when creating a new Private App. Each Private App will have a unique AppID and ClientID that needs to be sent with each API request to authenticate and approve the action. | | ||
| |Team Admin/Developer |A role that can be assigned to a user when they are part of a ‘team’ on the Gateway. Please see the documentation [here](https://www.healthdatagateway.org/about/how-to-manage-teams-on-the-gateway) on roles and permissions on the Gateway. | | ||
| |Authenticated API Endpoint |While a lot of the Gateway APIs are accessible without authentication, any endpoint changing data requires authentication. The ClientID acts as an authentication token. | | ||
|
|
||
| ## Introduction | ||
|
|
||
| The Private Apps feature enables developers to create a Private App and corresponding ClientID which is used as a token to authenticate requests made to the Gateway API. This guide offers step-by-step instructions for setting up and managing Private Apps on the Gateway. | ||
|
|
||
| ## How to Create a new Private App | ||
|
|
||
| _Please note that HDR UK cannot create Private Apps on behalf of users._ | ||
|
|
||
| ### Step 1: Sign into the Gateway | ||
|
|
||
| Sign in to the Gateway with your preferred login provider. Make sure you have a ‘team’ set up on the Gateway. If you are not a member of an existing ‘team’ you may need to ask a Team Admin to add you to the team (see documentation [here](https://www.healthdatagateway.org/about/how-to-manage-teams-on-the-gateway) on how to manage ‘team’ on the Gateway). If you need assistance with this step, contact the HDR UK Technology Team using the link below. | ||
|
|
||
| [https://www.healthdatagateway.org/about/contact-us](https://www.healthdatagateway.org/about/contact-us) | ||
|
|
||
|
|
||
| ### Step 2: Access the Gateway Private App management page | ||
|
|
||
| Providing you have the necessary roles (Team Admin or Developer), you can access the feature by following these steps: | ||
|
|
||
| - Navigate to your Team Management page by clicking on your name in the top-right corner of the window, and selecting the your ’team’ from the dropdown list. | ||
| - In the menu on the left-hand side, select Integrations > Private Apps. | ||
| - Click on the Create Private App button to initiate the process (Fig 1) | ||
|
|
||
|  | ||
| _Fig 1: How to create a new Private App_ | ||
|
|
||
| ### Step 3: Enter Private App details | ||
|
|
||
| To create a new Private App you will need to enter the following information (Fig 2): | ||
|
|
||
| - Public App name: Name of the App you wish to create. | ||
| - Description: A brief description of the App. | ||
| - Notification contacts: Gateway user accounts for relevant notification recipients. | ||
|
|
||
|  | ||
| _Fig 2: App info_ | ||
|
|
||
|
|
||
| ### Step 4: Define permissions | ||
|
|
||
| Use the permissions matrix (Fig 3) to assign the appropriate permissions for secure integration. Your App will only be allowed to use APIs for the permissions you have defined. App permissions are the responsibility of your ‘team’. | ||
|
|
||
| If you have any questions about defining Private App permissions, please contact the HDR UK Technology Team using the URL below. | ||
|
|
||
| [https://www.healthdatagateway.org/about/contact-us ](https://www.healthdatagateway.org/about/contact-us) | ||
|
|
||
|  | ||
| _Fig 3: Permissions matrix_ | ||
|
|
||
| We recommend only assigning permissions that the App will need and suggest a minimal permissions approach, for example: if an App is going to be managing Datasets we would recommend `datasets.create`, `datasets.read`, `datasets.update`, and `datasets.delete`. There would be no need to grant the App permissions to manage Tools or Data Uses in this instance. | ||
|
|
||
| Once the desired permissions are set, click the Save & Finish button to complete the Private App setup. Please note, at the current time, only functionality for Datasets has been enabled on the Gateway. | ||
|
|
||
| ### Step 5: Authentication Keys | ||
|
|
||
| Click on the newly created App entry. The AppID and ClientID will be accessible in the Authentication tab after completing the App setup (Fig 4). Both the AppID and Client ID are crucial as any requests to an authenticated Gateway API endpoint will require these to validate the request. Please see the documentation _link_ which demonstrates how to make an authenticated API request to the Gateway. | ||
|
|
||
|  | ||
| _Fig 4: Authentication_ | ||
|
|
||
|
|
||
| ## Manage APIs | ||
|
|
||
| ### List of Private Apps | ||
|
|
||
| Via the Private App management page, click on the Manage Private Apps button (Fig 5) to see a list of enabled and disabled Private Apps . | ||
|
|
||
|  | ||
| _Fig 5: Manage Private Apps_ | ||
|
|
||
| Each App is listed with its title, creation date, App ID, and a brief description. The list (Fig 6) can be filtered by App status. | ||
|
|
||
|  | ||
| _Fig 6: List of Private Apps_ | ||
|
|
||
|
|
||
| ### Update a Private App | ||
|
|
||
| Select the App you wish to modify, and then update the App information and permissions settings. Click the Save button to store the updated information on the Gateway. A pop-up window will confirm the successful App update . | ||
|
|
||
| The App’s ClientID will not automatically regenerate when permissions or information is changed. If you are making significant changes to the permissions of an App we recommend either disabling or deleting the old Private App and creating a new one. | ||
|
|
||
| Please note that deleting an App is an irreversible action. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| ## How to manage Private Apps | ||
|
|
||
| ### List Private Apps | ||
|
|
||
| Via the Private App management page, click on the Manage Private Apps button (Fig 1) to see a list of enabled and disabled Private Apps . | ||
|
|
||
|  | ||
| _Fig 1: Manage Private Apps_ | ||
|
|
||
| Each App is listed with its title, creation date, App ID, and a brief description. The list (Fig 2) can be filtered by App status. | ||
|
|
||
|  | ||
| _Fig 2: List of Private Apps_ | ||
|
|
||
|
|
||
| ### Update a Private App | ||
|
|
||
| Select the App you wish to modify, and then update the App information and permissions settings. Click the Save button to store the updated information on the Gateway. A pop-up window will confirm the successful App update . | ||
|
|
||
| The App’s ClientID will not automatically regenerate when permissions or information is changed. If you are making significant changes to the permissions of an App we recommend either disabling or deleting the old Private App and creating a new one. | ||
|
|
||
| Please note that deleting an App is an irreversible action. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| ## What is a Private App | ||
|
|
||
| Private apps allow you to use the Gateway’s APIs to access specific data from your Gateway Team. You can define what features/services each Private App is able to access from the management page. An access token is generated called the “ClientID” which must be sent with each request to the Gateway APIs. | ||
|
|
||
| Private Apps are perfect for users who want to programmatically interact with the features and data on the Gateway and how you interact with the Gateway APIs is entirely in your control. | ||
|
|
||
|
|
||
| ## Glossary | ||
|
|
||
| |Term|Description| | ||
| |------|-------------| | ||
| |Private App|An application/service/ETL tool that is developed by a user who wants to be able to programmatically interact with the Gateway. | | ||
| |AppID and ClientID |Tokens that are generated when creating a new Private App. Each Private App will have a unique AppID and ClientID that needs to be sent with each API request to authenticate and approve the action. | | ||
| |Team Admin/Developer |A role that can be assigned to a user when they are part of a ‘team’ on the Gateway. Please see the documentation [here](https://www.healthdatagateway.org/about/how-to-manage-teams-on-the-gateway) on roles and permissions on the Gateway. | | ||
| |Authenticated API Endpoint |While a lot of the Gateway APIs are accessible without authentication, any endpoint changing data requires authentication. The ClientID acts as an authentication token. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,53 +1,58 @@ | ||
| site_name: Gateway Integrations Guide | ||
| site_name: Gateway Technical Guides | ||
| theme: | ||
| name: material | ||
| #custom_dir: docs/overrides | ||
| palette: | ||
| scheme: hdruk | ||
| logo: images/logo.png | ||
| favicon: images/favicon.png | ||
| features: | ||
| - navigation.footer | ||
| - navigation.instant | ||
| - navigation.expand | ||
| - content.code.copy | ||
| - content.code.annotate | ||
| - toc.follow | ||
| name: material | ||
| #custom_dir: docs/overrides | ||
| palette: | ||
| scheme: hdruk | ||
| logo: images/logo.png | ||
| favicon: images/favicon.png | ||
| features: | ||
| - navigation.footer | ||
| - navigation.instant | ||
| - navigation.expand | ||
| - content.code.copy | ||
| - content.code.annotate | ||
| - toc.follow | ||
| extra_css: | ||
| - stylesheets/custom.css | ||
| - stylesheets/custom.css | ||
|
|
||
| nav: | ||
| - Home: index.md | ||
| - Gateway 2.0: | ||
| - Login: fe-login.md | ||
| - API Management: fe-creating-an-app.md | ||
| - FMA Setup: fe-creating-fma.md | ||
| - Metadata: | ||
| - Create: creating-metadata.md | ||
| - Validate: metadata-validation.md | ||
| - Exemplars: example-metadata.md | ||
| - Using the API: | ||
| - Datasets: | ||
| - Create: creating-a-dataset.md | ||
| - Retrieve: retrieving-a-dataset.md | ||
| - Update: updating-a-dataset.md | ||
| - Delete: deleting-a-dataset.md | ||
| - Using FMA: | ||
| - Test Server Example: fma-test-server.md | ||
| - Home: index.md | ||
| - Accessing Our APIs: | ||
| - What is a Private App: private-app-what.md | ||
| - Create a Private App: private-app-create.md | ||
| - Manage a Private App: private-app-manage.md | ||
| - Using the Gateway: | ||
| - Login: fe-login.md | ||
| - FMA Setup: fe-creating-fma.md | ||
| - Integrations: | ||
| - HDR UK Datasets Integration: integrations-hdruk-metadata.md | ||
| - Metadata: | ||
| - Create: creating-metadata.md | ||
| - Validate: metadata-validation.md | ||
| - Exemplars: example-metadata.md | ||
| - Using the API: | ||
| - Datasets: | ||
| - Create: creating-a-dataset.md | ||
| - Retrieve: retrieving-a-dataset.md | ||
| - Update: updating-a-dataset.md | ||
| - Delete: deleting-a-dataset.md | ||
| - Using FMA: | ||
| - Test Server Example: fma-test-server.md | ||
| plugins: | ||
| - search | ||
| - search | ||
|
|
||
| markdown_extensions: | ||
| - admonition | ||
| - pymdownx.details | ||
| - pymdownx.highlight: | ||
| anchor_linenums: true | ||
| line_spans: __span | ||
| pygments_lang_class: true | ||
| - pymdownx.inlinehilite | ||
| - pymdownx.snippets | ||
| - pymdownx.superfences | ||
| - pymdownx.tabbed: | ||
| alternate_style: true | ||
| - attr_list | ||
| - md_in_html | ||
| - admonition | ||
| - pymdownx.details | ||
| - pymdownx.highlight: | ||
| anchor_linenums: true | ||
| line_spans: __span | ||
| pygments_lang_class: true | ||
| - pymdownx.inlinehilite | ||
| - pymdownx.snippets | ||
| - pymdownx.superfences | ||
| - pymdownx.tabbed: | ||
| alternate_style: true | ||
| - attr_list | ||
| - md_in_html |