# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1607600713 -3600
# Node ID 6a3d48510b0b61fc36e179dcc1c57d77152c94b9
# Parent  6fb469a3c382390db1824f2dcd3dc164f679bf26
Python sample: "Forbid or allow access to REST resources (authorization)", deprecating advanced authorization plugin

diff -r 6fb469a3c382 -r 6a3d48510b0b Sphinx/source/plugins.rst
--- a/Sphinx/source/plugins.rst	Tue Dec 08 16:46:50 2020 +0100
+++ b/Sphinx/source/plugins.rst	Thu Dec 10 12:45:13 2020 +0100
@@ -61,13 +61,13 @@
 .. toctree::
    :maxdepth: 1
 
-   plugins/osimis-webviewer.rst
    plugins/mysql.rst
-   plugins/authorization.rst
    plugins/transfers.rst
    plugins/google-cloud-platform.rst    
    plugins/python.rst 
    plugins/object-storage.rst   
+   plugins/osimis-webviewer.rst
+   plugins/authorization.rst
 
 .. _plugins-contributed:
 
diff -r 6fb469a3c382 -r 6a3d48510b0b Sphinx/source/plugins/authorization.rst
--- a/Sphinx/source/plugins/authorization.rst	Tue Dec 08 16:46:50 2020 +0100
+++ b/Sphinx/source/plugins/authorization.rst	Thu Dec 10 12:45:13 2020 +0100
@@ -1,11 +1,15 @@
 .. _authorization:
 
 
-Advanced authorization plugin
-=============================
+Advanced authorization plugin (deprecated)
+==========================================
 
 .. contents::
 
+.. note:: This plugin is now deprecated and is not maintained anymore.
+          The :ref:`Python plugin <python_authorization>` provides a
+          more intuitive and flexible solution.
+   
 This **official plugin by Osimis** extends Orthanc with an advanced
 authorization mechanism. For each incoming REST request to some URI,
 the plugin will query a Web service to know whether the access is
diff -r 6fb469a3c382 -r 6a3d48510b0b Sphinx/source/plugins/python.rst
--- a/Sphinx/source/plugins/python.rst	Tue Dec 08 16:46:50 2020 +0100
+++ b/Sphinx/source/plugins/python.rst	Thu Dec 10 12:45:13 2020 +0100
@@ -710,6 +710,82 @@
 description.
 
 
+.. _python_authorization:
+
+Forbid or allow access to REST resources (authorization)
+........................................................
+
+.. highlight:: python
+
+The following Python script installs a callback that is triggered
+whenever the HTTP server of Orthanc is accessed::
+
+  import orthanc
+  import pprint
+
+  def Filter(uri, **request):
+      print('User trying to access URI: %s' % uri)
+      pprint.pprint(request)
+      return True  # False to forbid access
+
+  orthanc.RegisterIncomingHttpRequestFilter(Filter)
+
+If access is not granted, the ``Filter`` callback must return
+``False``. As a consequence, the HTTP status code would be set to
+``403 Forbidden``. If access is granted, the ``Filter`` must return
+``true``. The ``request`` argument contains more information about the
+request (such as the HTTP headers, the IP address of the caller and
+the GET arguments).
+
+Note that this is similar to the ``IncomingHttpRequestFilter()``
+callback that is available in :ref:`Lua scripts <lua-filter-rest>`.
+
+Thanks to Python, it is extremely easy to call remote Web services for
+authorization. Here is an example using the ``requests`` library::
+
+  import json
+  import orthanc
+  import requests
+
+  def Filter(uri, **request):
+      body = {
+          'uri' : uri,
+          'headers' : request['headers']
+      }
+      r = requests.post('http://localhost:8000/authorize',
+                        data = json.dumps(body))
+      return r.json() ['granted']  # Must be a Boolean
+
+  orthanc.RegisterIncomingHttpRequestFilter(Filter)
+
+.. highlight:: javascript
+
+This filter could be used together with the following Web service
+implemented using `Node.js
+<https://en.wikipedia.org/wiki/Node.js>`__::
+
+  const http = require('http');
+
+  const requestListener = function(req, res) {
+    let body = '';
+      req.on('data', function(chunk) {
+      body += chunk;
+    });
+    req.on('end', function() {
+      console.log(JSON.parse(body));
+      var answer = {
+        'granted' : false  // Forbid access
+      };
+      res.writeHead(200);
+      res.end(JSON.stringify(answer));
+    });
+  }
+
+  http.createServer(requestListener).listen(8000);
+
+  
+
+
 Performance and concurrency
 ---------------------------