diff --git a/minimal-setup/keycloak/README.md b/minimal-setup/keycloak/README.md index 7ef4678..9f70cb0 100644 --- 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" \ No newline at end of file +- 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. \ No newline at end of file diff --git a/minimal-setup/keycloak/docker-compose.yml b/minimal-setup/keycloak/docker-compose.yml index 711529b..c089298 100644 --- 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 index 12b9e15..d34b58d 100644 --- a/release-notes.md +++ b/release-notes.md @@ -4,7 +4,10 @@ SPDX-FileCopyrightText: 2022 - 2024 Orthanc Team SRL 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 index ff7f697..d162bc7 100644 --- 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).