Advanced authorization for Orthanc
==================================


General Information
-------------------

This repository contains the source code of an advanced authorization
plugin for Orthanc.

For each incoming REST request to some URI, the plugin will query a
Web service to know whether the access is granted to the
user. Authorization credentials can be retrieved either from a GET
argument, or from a HTTP header.


Installation and usage
----------------------

Build instructions are similar to that of Orthanc:
https://orthanc.uclouvain.be/book/faq/compiling.html

Usage details are available as part of the Orthanc Book:
https://orthanc.uclouvain.be/book/plugins/authorization.html


Integration tests
-----------------

Integration tests are available in the https://orthanc.uclouvain.be/hg/orthanc-tests/ repo
in the folder NewTests/Authorization.

API
---

Since version 0.5.0, the plugin implements a RestA API to generate tokens
(provided that the Web service is able to do so).

Sample Orthanc Flavored API:

curl -X PUT http://localhost:8042/auth/tokens/resource-instant-link -H 'Content-Type: application/json' \
  -d '{"ID": "toto",
       "Resources" : [{
         "DicomUid": "1.2",
         "OrthancId": "",
         "Level": "study"
       }],
       "Type": "resource-instant-link", 
       "ExpirationDate": "2026-12-31T11:00:00Z"}'

Sample response:
  {
    "Token": "e148.....",
    "Url": null
  }

The API that must be implemented by the webservice is slighlty different wrt naming conventions:

curl -X PUT http://localhost:8000/tokens/resource-instant-link -H 'Content-Type: application/json' \
  -d '{"id": "toto",
       "resources" : [{
         "dicom-uid": "1.2",
         "level": "study"
       }],
       "type": "resource-instant-link", 
       "expiration-date": "2026-12-31T11:00:00Z"}'

Sample response:
  {
    "token": "e148.....",
    "url": null
  }



Contributing
------------

Instructions for contributing to the Orthanc project are included in
the Orthanc Book:
https://orthanc.uclouvain.be/book/developers/repositories.html


Licensing
---------

The authorization plugin for Orthanc is licensed under the AGPL license.

We also kindly ask scientific works and clinical studies that make
use of Orthanc to cite Orthanc in their associated publications.
Similarly, we ask open-source and closed-source products that make
use of Orthanc to warn us about this use. You can cite our work
using the following BibTeX entry:

@inproceedings{Jodogne:ISBI2013,
  author = {Jodogne, S. and Bernard, C. and Devillers, M. and Lenaerts, E. and Coucke, P.},
  title = {Orthanc -- {A} Lightweight, {REST}ful {DICOM} Server for Healthcare and Medical Research},
  booktitle={Biomedical Imaging ({ISBI}), {IEEE} 10th International Symposium on}, 
  year={2013}, 
  pages={190-193}, 
  ISSN={1945-7928},
  month=apr,
  url={http://ieeexplore.ieee.org/xpl/articleDetails.jsp?tp=&arnumber=6556444},
  address={San Francisco, {CA}, {USA}}
}