readme and demo

orthanc-team · Feb 13, 2024 · bcabcdf · bcabcdf
1 parent e48b4ac
commit bcabcdf
Show file tree

Hide file tree

Showing 4 changed files with 65 additions and 17 deletions.
diff --git a/minimal-setup/keycloak/README.md b/minimal-setup/keycloak/README.md
@@ -40,7 +40,7 @@ To start the setup, type: `docker compose up`.  Some containers will restart mul
 - Add the `external` label to a few of the studies
 - On one of the uploaded studies, click on the `Share` button and then on `Share` in the dialog box and then on `Copy and close`
 - Keep the link in your clipboard.  You may share this link with an external user.
-- Go to `Profile` -> `Logout`
+- In the left panel, go to `Admin` -> `Logout`
 
 ## As a guest user
 
@@ -64,4 +64,42 @@ If you wish to access this demo from a remote computer, you must configure the d
 Update these settings:
 - orthanc: ORTHANC_JSON -> OrthancExplorer2 -> Keycloak -> "Url": "http://mydomain.com/keycloak/"
 - keycloak: KC_HOSTNAME_URL: "http://mydomain.com/keycloak"
-- keycloak: KC_HOSTNAME_ADMIN_URL: "http://mydomain.com/keycloak"
+- keycloak: KC_HOSTNAME_ADMIN_URL: "http://mydomain.com/keycloak"
+
+# Enabling API keys
+
+If you wish to enable support for api-keys authentication, you should log in the Keycloak admin console and:
+- in http://localhost/keycloak/admin/master/console/ (login/pwd: `admin`/`change-me`), left panel: Clients
+- In the `orthanc` realm
+- select `admin-cli`
+- `Settings` tab --> enable `Client authentication`
+- `Settings` tab --> enable `Service accounts roles`
+- click on Save button!!
+- then, `Credentials` tab is available to get the `Client secret`.  Copy it in the `docker-compose.yml` file in `KEYCLOAK_CLIENT_SECRET`
+- `Service accounts roles` tab --> `Assign role` button
+- **select `Filter by clients` in the combo box** and `view-users` in the search filter
+- check `realm-management view-users` and click `Assign`
+
+Then, you should add an API-key to a user.  Still in the Keycloak admin area:
+- In the `orthanc` realm
+- Open `Users` and select the `external` user
+- In the `Attributes` tab, click `Add an attribute` and enter:
+- `api-key` as the Key and `api-key-for-external-user-that-should-be-a-long-random-string` as the Value.
+- Click `Save`
+
+Then, in the `docker-compose.yml` uncomment the 2 lines related to these 2 env var:
+- `ENABLE_KEYCLOAK_API_KEYS`
+- `KEYCLOAK_CLIENT_SECRET`
+- make sure that the Orthanc Authorization plugin contains this line:
+  `"TokenHttpHeaders" : [ "api-key" ],`
+
+And restart the Docker setup:
+- `docker compose up`
+
+Then, in a terminal, type this command to access the API with an api-key.
+
+```bash
+curl -H "api-key: api-key-for-external-user-that-should-be-a-long-random-string" -d '{"Level": "Study", "Query": {"PatientID": "*"}}'  http://localhost:8043/tools/find
+```
+
+This should only list the studies with the `external` label.
diff --git a/minimal-setup/keycloak/docker-compose.yml b/minimal-setup/keycloak/docker-compose.yml
@@ -67,6 +67,7 @@ services:
               "stone-webviewer",
               "orthanc-explorer-2"
             ],
+            "TokenHttpHeaders" : [ "api-key" ],
             "CheckedLevel": "studies"
           },
           "DicomWeb": {
@@ -76,7 +77,7 @@ services:
         }
 
   orthanc-auth-service:
-    image: orthancteam/orthanc-auth-service:23.12.2
+    image: orthancteam/orthanc-auth-service:api-keys
     # always disable port mapping in production !!!
     # ports: ["8000:8000"]
     # permissions can be customized in the permissions.json file
@@ -87,6 +88,8 @@ services:
     environment:
       SECRET_KEY: "change-me-I-am-a-secret-key"
       ENABLE_KEYCLOAK: "true"
+#      ENABLE_KEYCLOAK_API_KEYS: "true"
+#      KEYCLOAK_CLIENT_SECRET: "change-me-I-am-a-secret-you-get-in-keycloak-admin-ui"
       PUBLIC_ORTHANC_ROOT: "http://localhost/orthanc/"
       PUBLIC_LANDING_ROOT: "http://localhost/orthanc/ui/app/token-landing.html"
       PUBLIC_OHIF_ROOT: "http://localhost/ohif/"

diff --git a/release-notes.md b/release-notes.md
@@ -4,7 +4,10 @@ SPDX-FileCopyrightText: 2022 - 2024 Orthanc Team SRL <[email protected]>
 SPDX-License-Identifier: GPL-3.0-or-later
 -->
 
-- added support for Api-keys through a new configuration file `API_KEYS_FILE_PATH`
+- added support for Api-keys that can be defined as user custom attributes `api-key`
+  in Keycloak.  This requires the definition of 3 new env vars: `ENABLE_KEYCLOAK_API_KEYS`,
+  `KEYCLOAK_CLIENT_SECRET` and `KECLOAK_ADMIN_URI`.  This also requires you to configure
+  the `admin-cli` client in Keycloak.
 
 v 24.1.1
 ========

diff --git a/sources/README-dockerhub-orthanc-auth-service.md b/sources/README-dockerhub-orthanc-auth-service.md
@@ -9,18 +9,22 @@ SPDX-License-Identifier: CC0-1.0
 Web service to run next to Orthanc to handle sharing of studies by issuing [JWT](https://jwt.io/) that can then be passed
 in authorization headers that will be checked by the [Authorization plugin](https://book.orthanc-server.com/plugins/authorization.html).
 
-| Environment variables       | Default value                          | Description                                                                                                                                                         |
-|-----------------------------|:---------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| ENABLE_KEYCLOAK             | false                                  | Connects the auth-service to keycloak to handle users                                                                                                               |
-| KEYCLOAK_URI                | http://keycloak:8080/realms/orthanc/   | The URI of the realm to use.                                                                                                                                        |
-| PERMISSIONS_FILE_PATH       | /orthanc-auth-service/permissions.json | Path to a file containing the mapping between keycloak roles and permissions.                                                                                       |
-|                             |                                        |                                                                                                                                                                     |
-| PUBLIC_ORTHANC_ROOT         | -                                      | The public root URL to Orthanc when using links to access resources. e.g: `http://localhost/orthanc/`                                                               |
-| PUBLIC_LANDING_ROOT         | -                                      | The landing page URL for links.  This page will check the token validity and redirect to e.g. a viewer.  e.g.: `http://localhost/orthanc/ui/app/token-landing.html` |
-| PUBLIC_OHIF_ROOT            | -                                      | The public root URL to OHIF when using links to access resources. e.g: `https://ohif.my.site/`                                                                      |
-| USERS                       | -                                      | Define a list of user/pwd that can access this webservice.                                                                                                          |
-|                             |                                        |                                                                                                                                                                     |
-| MEDDREAM_TOKEN_SERVICE_URL  | -                                      | The URL to the MedDream token service. e.g `http://meddream-token-service:8088/v3/generate`                                                                         |
-| PUBLIC_MEDDREAM_ROOT        | -                                      | The public root URL to access the MedDream viewer. e.g `http://localhost/meddream/`                                                                                 |
+| Environment variables      | Default value                              | Description                                                                                                                                                         |
+|----------------------------|:-------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ENABLE_KEYCLOAK            | false                                      | Connects the auth-service to keycloak to handle users                                                                                                               |
+| KEYCLOAK_URI               | http://keycloak:8080/realms/orthanc/       | The URI of the realm to use.                                                                                                                                        |
+| PERMISSIONS_FILE_PATH      | /orthanc-auth-service/permissions.json     | Path to a file containing the mapping between keycloak roles and permissions.                                                                                       |
+|                            |                                            |                                                                                                                                                                     |
+| ENABLE_KEYCLOAK_API_KEYS   | false                                      | Enables the API keys support in Keycloak                                                                                                                            | 
+| KEYCLOAK_ADMIN_URI         | http://keycloak:8080/admin/realms/orthanc/ | The URI of admin API of the realm to use.                                                                                                                           |
+| KEYCLOAK_CLIENT_SECRET     | -                                          | `admin-cli` client secret used to authenticate to the Keycloak admin API                                                                                            |
+|                            |                                            |                                                                                                                                                                     |
+| PUBLIC_ORTHANC_ROOT        | -                                          | The public root URL to Orthanc when using links to access resources. e.g: `http://localhost/orthanc/`                                                               |
+| PUBLIC_LANDING_ROOT        | -                                          | The landing page URL for links.  This page will check the token validity and redirect to e.g. a viewer.  e.g.: `http://localhost/orthanc/ui/app/token-landing.html` |
+| PUBLIC_OHIF_ROOT           | -                                          | The public root URL to OHIF when using links to access resources. e.g: `https://ohif.my.site/`                                                                      |
+| USERS                      | -                                          | Define a list of user/pwd that can access this webservice.                                                                                                          |
+|                            |                                            |                                                                                                                                                                     |
+| MEDDREAM_TOKEN_SERVICE_URL | -                                          | The URL to the MedDream token service. e.g `http://meddream-token-service:8088/v3/generate`                                                                         |
+| PUBLIC_MEDDREAM_ROOT       | -                                          | The public root URL to access the MedDream viewer. e.g `http://localhost/meddream/`                                                                                 |
 
 3 demo setups are available [here](https://github.com/orthanc-team/orthanc-auth-service/tree/main/minimal-setup).