Mercurial > hg > orthanc-book
changeset 920:1d9e0aa08fdd
auth plugin
| author | Alain Mazy <am@osimis.io> |
|---|---|
| date | Fri, 17 Mar 2023 16:59:14 +0100 |
| parents | 5c1ce758f748 |
| children | 33e8cb14142f |
| files | Sphinx/source/plugins/authorization.rst |
| diffstat | 1 files changed, 148 insertions(+), 65 deletions(-) [+] |
line wrap: on
line diff
--- a/Sphinx/source/plugins/authorization.rst Fri Mar 17 12:58:14 2023 +0100 +++ b/Sphinx/source/plugins/authorization.rst Fri Mar 17 16:59:14 2023 +0100 @@ -16,23 +16,20 @@ <https://hg.orthanc-server.com/orthanc-authorization/file/default>`__ is freely available under the terms of the AGPLv3 license. +Binaries +-------- -Compilation ------------ - -.. highlight:: bash +Binaries are available: -The procedure to compile this plugin is similar of that for the -:ref:`core of Orthanc <binaries>`. The following commands should work -for most UNIX-like distribution (including GNU/Linux):: +- in the `Windows Installers <https://www.orthanc-server.com/download-windows.php>`__ . +- in the `MacOS package <https://www.orthanc-server.com/static.php?page=download-mac>`__ . +- in the :ref:`osimis/orthanc Docker images <docker-osimis>` - $ mkdir Build - $ cd Build - $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release - $ make +Release notes +------------- -The compilation will produce a shared library ``OrthancAuthorization`` -that contains the authorization plugin. +Release notes are available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/NEWS>`__. + Usage ----- @@ -52,10 +49,9 @@ "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" ], "Authorization" : { - "WebService" : "http://localhost:8000/", + "WebServiceRootUrl" : "http://localhost:8000/", "WebServiceUsername": "my-user", - "WebServicePassword": "my-password", - "WebServiceIdentifier": "my-id" + "WebServicePassword": "my-password" } } @@ -69,11 +65,6 @@ This section describes how a Web service suitable for the authorization plugin can be designed. -**Note:** The behavior described in this section is implemented by the -``AuthorizationWebService`` C++ class in the source code. It is -possible to define a different authorization back-end by deriving -from interface ``IAuthorizationService``. - Incoming request ^^^^^^^^^^^^^^^^ @@ -90,7 +81,7 @@ "level" : "patient", "method" : "get", "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", - "identifier": "my-id" + "server-id": "my-id" } In this example, the user is accessing an URI that is related to some @@ -113,7 +104,7 @@ contains its ``SOPInstanceUID``. * The ``orthanc-id`` field gives the :ref:`Orthanc identifier <orthanc-ids>` of the resource. -* The ``identifier`` field contains the value of the ``WebServiceIdentifier`` +* The ``server-id`` field contains the value of the ``WebServiceIdentifier`` configuration or ``null`` if this configuration is not defined. This allows the WebService to identity which Orthanc instance is calling it (new in v 0.3.0). @@ -213,7 +204,7 @@ [...] "Authorization" : { "WebService" : "http://localhost:8000/", - "TokenHttpHeaders" : [ "hello" ] + "TokenHttpHeaders" : [ "token" ] } } @@ -221,7 +212,7 @@ In such a situation, if some HTTP client issues the following call:: - # curl -H 'hello: world' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 + # curl -H 'token: my-token' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 .. highlight:: json @@ -232,8 +223,8 @@ "level" : "patient", "method" : "get", "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", - "token-key" : "hello", - "token-value" : "world" + "token-key" : "token", + "token-value" : "my-token" } .. highlight:: text @@ -251,8 +242,8 @@ "level" : "patient", "method" : "get", "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", - "token-key" : "hello", - "token-value" : "world" + "token-key" : "token", + "token-value" : "my-token" } **Note 1:** It is allowed to provide a list of HTTP tokens or a list @@ -273,46 +264,113 @@ .. highlight:: json +The full list of configuration is available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/Plugin/DefaultConfiguration.json>`__. + Here is the list of all the configuration options:: { - "Name" : "MyOrthanc", - [...] - "Authorization" : { - "WebService" : "http://localhost:8000/", - "WebServiceUsername": "my-user", // new in v 0.3.0 - "WebServicePassword": "my-password", // new in v 0.3.0 - "WebServiceIdentifier": "my-id", // new in v 0.3.0 - "TokenGetArguments" : [ "user" ], - "TokenHttpHeaders" : [ "hello" ], - "StandardConfigurations": [ // new in v 0.4.0 - "osimis-web-viewer", - "stone-webviewer" - ], - "UncheckedResources" : [ - "/series", - "/instances", - "/patients", - "/studies", - "/plugins/explorer.js", - "/system" - ], - "UncheckedFolders" : [ - "/app/", - "/web-viewer/app/", - "/web-viewer/libs/", - "/wsi/app/" - ], - "CheckedLevel" : "studies", // new in v 0.4.0 - "UncheckedLevels" : [ - "patients", - "series", - "instances" - ] - } + "Authorization" : { + // The Base URL of the auth webservice. This is an alias for all 3 next configurations: + // // "WebServiceUserProfileUrl" : " ROOT /user/get-profile", + // // "WebServiceTokenValidationUrl" : " ROOT /tokens/validate", + // // "WebServiceTokenCreationBaseUrl" : " ROOT /tokens/", + // // "WebServiceTokenDecoderUrl" : " ROOT /tokens/decode", + // You should define it only if your auth webservice implements all 3 routes ! + // "WebServiceRootUrl" : "http://change-me:8000/", + + // The URL of the auth webservice route implementing user profile (optional) + // (this configuration was previously named "WebService" and its old name is still accepted + // for backward compatibility) + // "WebServiceUserProfileUrl" : "http://change-me:8000/user/profile", + + // The URL of the auth webservice route implementing resource level authorization (optional) + // "WebServiceTokenValidationUrl" : "http://change-me:8000/tokens/validate", + + // The Base URL of the auth webservice route to create tokens (optional) + // "WebServiceTokenCreationBaseUrl" : "http://change-me:8000/tokens/", + + // The URL of the auth webservice route implementing token decoding (optional) + // "WebServiceTokenDecoderUrl": "http://change-me:8000/tokens/decode" + + // The username and password to connect to the webservice (optional) + //"WebServiceUsername": "change-me", + //"WebServicePassword": "change-me", + + // An identifier added to the payload of each request to the auth webservice (optional) + //"WebServiceIdentifier": "change-me" + + // The name of the HTTP headers that may contain auth tokens + //"TokenHttpHeaders" : [], + + // the name of the GET arguments that may contain auth tokens + //"TokenGetArguments" : [], + + // A list of predefined configurations for well-known plugins + // "StandardConfigurations": [ // new in v 0.4.0 + // "osimis-web-viewer", + // "stone-webviewer", + // "orthanc-explorer-2" + // ], + + //"UncheckedResources" : [], + //"UncheckedFolders" : [], + //"CheckedLevel" : "studies", + //"UncheckedLevels" : [], + + // Definition of required "user-permissions". This can be fully customized. + // You may define other permissions yourself as long as they match the permissions + // provided in the user-profile route implemented by the auth-service. + // You may test your regex in https://regex101.com/ by selecting .NET (C#) and removing the leading ^ and trailing $ + // The default configuration is suitable for Orthanc-Explorer-2 (see TBD sample) + "Permissions" : [ + ["post", "^/auth/tokens/decode$", ""], + ["post", "^/tools/lookup$", ""], // currently used to authorize downloads in Stone (to map the StudyInstanceUID into an OrthancID. Not ideal -> we should define a new API that has the resource ID in the path to be able to check it at resource level) but, on another hand, you do not get any Patient information from this route + + // elemental browsing in OE2 + ["post", "^/tools/find$", "all|view"], + ["get" , "^/(patients|studies|series|instances)/([a-f0-9-]+)$", "all|view"], + ["get" , "^/(patients|studies|series|instances)/([a-f0-9-]+)/(studies|study|series|instances)$", "all|view"], + ["get" , "^/instances/([a-f0-9-]+)/(tags|header)$", "all|view"], + ["get" , "^/statistics$", "all|view"], + + // create links to open viewer or download resources + ["put", "^/auth/tokens/(viewer-instant-link|meddream-instant-link)$", "all|view"], + ["put", "^/auth/tokens/(download-instant-link)$", "all|download"], + + // share a link to open a study + ["put", "^/auth/tokens/(stone-viewer-publication|meddream-viewer-publication|osimis-viewer-publication)$", "all|share"], + + // uploads + ["post", "^/instances$", "all|upload"], + + // monitor jobs you have created + ["get" , "^/jobs/([a-f0-9-]+)$", "all|send|modify|anonymize|q-r-remote-modalities"], + + // interacting with peers/modalities/dicomweb + ["post", "^/(peers|modalities)/(.*)/store$", "all|send"], + ["get" , "^/(peers|modalities)$", "all|send|q-r-remote-modalities"], + ["post", "^/modalities/(.*)/echo$", "all|send|q-r-remote-modalities"], + ["post", "^/modalities/(.*)/query$", "all|q-r-remote-modalities"], + ["get", "^/queries/([a-f0-9-]+)/answers$", "all|q-r-remote-modalities"], + ["post", "^/modalities/(.*)/move$", "all|q-r-remote-modalities"], + ["get" , "^/DICOM_WEB_ROOT/servers$", "all|send|q-r-remote-modalities"], + ["get" , "^/DICOM_WEB_ROOT/(servers)/(.*)/stow$", "all|send"], + + // modifications/anonymization + ["post", "^/(patients|studies|series|instances)/([a-f0-9-]+)/modify(.*)$", "all|modify"], + ["post", "^/(patients|studies|series|instances)/([a-f0-9-]+)/anonymize(.*)$", "all|anonymize"], + + // deletes + ["delete" , "^/(patients|studies|series|instances)/([a-f0-9-]+)$", "all|delete"], + + // settings + ["put", "^/tools/log-level$", "all|settings"], + ["get", "^/tools/log-level$", "all|settings"] + ] + } } -The following options have been described above: ``WebService``, +The following options have been described above: ``WebServiceRootUrl``, ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the remaining options: @@ -347,7 +405,7 @@ "AuthenticationEnabled": false, "Authorization" : { - "WebService" : "http://localhost:8000/shares/validate", + "WebServiceTokenValidationUrl" : "http://localhost:8000/shares/validate", "StandardConfigurations": [ "stone-webviewer" ], @@ -355,6 +413,13 @@ } } +.. _orthanc-explorer-authorization: + +Integration with the Orthanc Explorer 2 +--------------------------------------- + +More info to come soon. + .. _orthanc-explorer-authorization: @@ -374,3 +439,21 @@ Please note that the Orthanc Explorer has not been designed to handle the authorization so, when an authorization is not granted, it will simply display an empty page or an error message. + + +Compilation +----------- + +.. highlight:: bash + +The procedure to compile this plugin is similar of that for the +:ref:`core of Orthanc <binaries>`. The following commands should work +for most UNIX-like distribution (including GNU/Linux):: + + $ mkdir Build + $ cd Build + $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release + $ make + +The compilation will produce a shared library ``OrthancAuthorization`` +that contains the authorization plugin.