bird-house · cehbrecht · Aug 1, 2019 · Jul 25, 2019 · Jul 25, 2019 · Jul 25, 2019
diff --git a/Makefile b/Makefile
@@ -46,6 +46,9 @@ help:
 	@echo "  bump              to update the package version."
 	@echo "  dry               to only display results (not applied) when combined with 'bump'."
 	@echo "  dist              to build source and wheel package."
+	@echo "\nSecurity targets:"
+	@echo "  gensecret         to generate a secret hash key."
+	@echo "  gencert           to generate a self-signed certificate."
 
 .PHONY: debug
 debug:
@@ -178,3 +181,16 @@ dist: clean
 	@-python setup.py sdist
 	@-python setup.py bdist_wheel
 	ls -l dist
+
+## Security
+
+.PHONY: gensecret
+gensecret:
+	@echo "Generate a secret ..."
+	@-python -c 'import uuid; print(uuid.uuid4().hex)'
+
+.PHONY: gencert
+gencert:
+	@echo "Generate a self-signed certificate ..."
+	@-bash -c "openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout key.pem -out cert.pem"
+	@-bash -c "openssl x509 -pubkey -noout -in cert.pem > pubkey.pem"
diff --git a/README.rst b/README.rst
@@ -1,6 +1,6 @@
-=====================================
-Twitcher: A simple OWS Security Proxy
-=====================================
+============================
+Twitcher: OWS Security Proxy
+============================
 
 .. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
    :target: http://twitcher.readthedocs.io/en/latest/?badge=latest
@@ -22,13 +22,12 @@ Twitcher: A simple OWS Security Proxy
 Twitcher (the bird-watcher)
   *a birdwatcher mainly interested in catching sight of rare birds.* (`Leo <https://dict.leo.org/ende/index_en.html>`_).
 
-Twitcher is a security proxy for Web Processing Services (WPS). The execution of a WPS process is blocked by the proxy.
-The proxy service uses access tokens (UUID) to run a WPS process.
-The access tokens are valid only for a short period of time.
-In addition one can also use X.509 certificates for WPS client authentication.
+Twitcher is a security proxy for OWS services like Web Processing Services (WPS).
+The proxy service uses OAuth2 access tokens to protect the OWS service access.
+In addition one can also use X.509 certificates for client authentication.
 
 The implementation is not restricted to WPS services.
-It will be extended to more OWS services like WMS (Web Map Service) and CSW (Catalogue Service for the Web)
+It will be extended to more OWS services like WMS (Web Map Service)
 and might also be used for Thredds catalog services.
 
 Twitcher extensions:
@@ -39,6 +38,18 @@ Twitcher extensions:
 
 Twitcher is implemented with the Python `Pyramid`_ web framework.
 
+You can try Twitcher online using Binder, or view the notebooks on NBViewer.
+
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/bird-house/twitcher.git/dev-oauth?filepath=notebooks
+   :alt: Binder Launcher
+   :height: 20
+
+.. image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.png
+   :target: https://nbviewer.jupyter.org/github/bird-house/twitcher/tree/dev-oauth/notebooks/
+   :alt: NBViewer
+   :height: 20
+
 Twitcher is part of the `Birdhouse`_ project. The documentation is on `ReadTheDocs`_.
 
 Twitcher `Docker`_ images are also available for most recent tagged versions.

diff --git a/binder/environment.yml b/binder/environment.yml
@@ -0,0 +1 @@
+../environment.yml
diff --git a/binder/postBuild b/binder/postBuild
@@ -0,0 +1 @@
+pip install -e .
diff --git a/development.ini b/development.ini
@@ -25,13 +25,19 @@ retry.attempts = 3
 # twitcher
 twitcher.url = http://localhost:8000
 twitcher.adapter = default
-twitcher.rpcinterface = true
-twitcher.username =
-twitcher.password =
-twitcher.ows_security = true
+twitcher.username = demo
+twitcher.password = demo
 twitcher.ows_proxy = true
-twitcher.ows_proxy_delegate = false
 twitcher.ows_proxy_protected_path = /ows
+# available types: default, random_token, signed_token, custom_token
+twitcher.token.type = default
+# run "make gencert"
+twitcher.token.keyfile = key.pem
+twitcher.token.certfile = pubkey.pem
+twitcher.token.expires_in = 3600
+twitcher.token.issuer = twitcher
+# run "make gensecret"
+twitcher.token.secret = 8dc7b9a238c54bde90f57e80b6ac8b34
 
 ###
 # wsgi server configuration
@@ -67,8 +73,8 @@ handlers = console
 
 [logger_twitcher]
 level = DEBUG
-handlers =
-qualname = twitcher
+handlers = console
+qualname = TWITCHER
 
 [logger_sqlalchemy]
 level = WARN

diff --git a/docs/diagrams/oauth-wps-data-access.png b/docs/diagrams/oauth-wps-data-access.png
diff --git a/docs/diagrams/twitcher-new.png b/docs/diagrams/twitcher-new.png
diff --git a/docs/diagrams/twitcher-new.xml b/docs/diagrams/twitcher-new.xml
diff --git a/docs/diagrams/twitcher-overview.dia b/docs/diagrams/twitcher-overview.dia
diff --git a/docs/diagrams/twitcher-overview.png b/docs/diagrams/twitcher-overview.png
diff --git a/docs/diagrams/twitcher-overview.xml b/docs/diagrams/twitcher-overview.xml
@@ -0,0 +1 @@
+<mxfile userAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Atom/1.38.2 Chrome/61.0.3163.100 Electron/2.0.18 Safari/537.36" version="9.1.0" editor="www.draw.io" type="device"><diagram id="6b31b2c4-f107-957b-7422-773966168f4d" name="Page-1">7Zpdc9o4FIZ/DTO7N4xsYdlcAiXZzjYTpnSa7qWwha2NsRghAuyvX8mW8Yec1AkY0kmTi+AjWZbOc3T8HpEenKz2txyvozsWkLhng2Dfg596tm1ZtiP/KMshs3geygwhp4HuVBjm9D+ijUBbtzQgm0pHwVgs6Lpq9FmSEF9UbJhztqt2W7K4+tQ1DolhmPs4Nq0PNBCRXoXtFva/CA2j/MkWGmYtC+w/hpxtE/28ng2X6U/WvML5WHqhmwgHbFcywWkPTjhjIvu02k9IrHybuy277+aZ1uO8OUlEqxv0ip5wvCX5lNOJiUPujHQ5RN1g9eB4F1FB5mvsq9adxC9tkVjFuvm4IKAuBGePZMJixtOhYOAOF6BoyX0rlz1e0jgu9VwuCfJ9ZWeJ0AFiefIaxzRM5IUvV0hk57G5ZO2FJ8IF2ZdM2gW3hK2I4AfZRbfaQMerDldrqPHsCvjOQPeJyuBd3RHrgAuPYxdOlx+035sZOAaC+4e5NMw42x9eoAFOpeHZC4hQGxqBQ7xgcCka+ebQNOwGGrYHTBroDDCgZXicBDI36EvGRcRCluB4WljHVSYl/wd4Ex13jrqYYSH9lKQWGyjrv0SIg3Yp3gomTcVDvjC2zlHW6Y0+qV+DHjTpgfSngd6zsDZsy329fJ0hBOYh0b2gdrTyzItEOYmxoE/VrHoKHjNdzYm/5VSop33BBxmDNorlNMcL9SlUn/744QCZnsFERiBdUh8L0rPlk8D9aCsiNdw36b/kT/POLjffwpMZpV0q9HxyuVRY33ywIRVaHW0+75lM+JWEdJNNswHv/Zoko9nnjOlXshEXJol8jyyWrdIoJt7yUiQd0CKNwo5IWpaB8mE2/9WkRdpBz7ZBWr1+c7lVJANgIrHsrpDYJpK7bpGgBXJa6QspkO3rIBkMrokEmkhuOkUyRC7ErZAQS4o+9xpIELgikvwd9LH13/mEnb51xqh8xBExBMN+reTyavAyvanvK1ewPx9qUBsqU7PGUGkoHNfULjoG54wO6XV++KHsfaVsteEf1doHAOWGGeFUzlHttXSEdx5UJAlG6ghGXicsIZnlhiqfptO/WtDVBdExr/wkToyBBsNhZSCIrFax+5aAc34H3C8bcAiBWmp6c8ghp57lugw6ZMiSbzsq/EhV1yAryUpld/M5lXzZi5oyqbDXqMqQtckQGEo6yLI9HumGFQ2CNNCbpFA1+CtqqB445xYusKYl7Qbh0nhwZZ/j4AoY0KZ7tUtxbJbD6uBDrlOdhVCWNNTUs9H3zxPF+Q6Ha5qdl9Q7Tee3N1nRbbb9TQ5+zPBj1t7v919Xk5+sc7s4XQk5Dqi8KItkLEsc1EWlWI2kpgNpCzVEkqF93hRKZqWYbfpJrNbfJbcLVfEGiAZcz7NxqnDcC5Yn0Pyy4IEsVBKWr1u10z82Gse7Ihr3nFLtnWuuRgHVitSpmgqerXJsGKq7yhGaZ9s8PdVWmqrh5aq+a1Ffej+ShtfzOxVbZ9jAqJZbLcfcwW5XCmpoICJ7KXPV10V1AlIORx+RD6wLkwY+XSncfHP+roVPrYWvkLchrNfCMD9FeW0tDG2zFm73CpCuwYdSt7XqsHlh0uaT9KSLkM3GbPlakJfF//Zk3Yt/oILT/wE=</diagram></mxfile>
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -1,36 +1,51 @@
-.. toctree::
-   :hidden:
+#############
+API Reference
+#############
 
-.. _api:
+.. automodule:: twitcher
 
-*************************
-XML-RPC API Documentation
-*************************
+Twitcher Client
+===============
 
-.. contents::
-    :local:
-    :depth: 2
+.. autoclass:: twitcher.client.TwitcherService
+  :members:
+  :undoc-members:
 
+Twitcher CLI
+============
 
-To use the XML-RPC interface, connect to twitcher’s HTTP port with any XML-RPC client library and run commands against it.
-An example of doing this using Python’s ``xmlrpclib`` client library is as follows.
+.. automodule:: twitcher.scripts.twitcherctl
+  :members:
 
-.. code-block:: python
+Twitcher OpenAPI
+----------------
 
-   import xmlrpc.client as xmlrpclib
-   server = xmlrpclib.Server('http://localhost:8000/RPC2')
+.. autoclass:: twitcher.api.TwitcherAPI
+  :members:
 
-.. warning::
+OWS Security
+============
 
-   When accessing the default HTTPS service you need to deactivate SSL verfication.
-   See ``twitcher/client.py`` how this can be done. You may also use the following code::
+.. automodule:: twitcher.oauth2
+  :members:
 
-   >> from twitcher import client
-   >> server = client._create_server('https://localhost:8000/RPC2', verify_ssl=False)
+.. autoclass:: twitcher.oauth2.RandomTokenValidator
+  :members:
 
-The `XML-RPC <http://xmlrpc.scripting.com/>`_ interface can also be accessed from Java and other languages.
+.. autoclass:: twitcher.oauth2.SignedTokenValidator
+  :members:
 
-See the ``twitcher/rpcinterface.py`` module for the available xmlrpc methods:
+.. autoclass:: twitcher.oauth2.CustomTokenValidator
+  :members:
 
-.. autoclass:: twitcher.rpcinterface.RPCInterface
-   :members:
+OWS Registry
+============
+
+.. autoclass:: twitcher.owsregistry.OWSRegistry
+  :members:
+
+OWS Proxy
+=========
+
+.. automodule:: twitcher.owsproxy
+  :members:
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -5,3 +5,82 @@ Configuration
 
 Twitcher has a configuration file `development.ini` for local development.
 Copy and edit this configuration to adapt to your settings.
+
+Service
+-------
+
+Edit the configuration to change the service parameters.
+
+The URL of the Twitcher service endpoint:
+
+.. code-block:: ini
+
+  twitcher.url = http://localhost:8000
+
+
+Basic Authentication
+--------------------
+
+Twitcher uses basic authentication for client application registration.
+Edit username in password in the configuration:
+
+.. code-block:: ini
+
+  twitcher.username = demo
+  twitcher.password = demo
+
+
+OAuth2 Token Generator
+----------------------
+
+Twitcher uses `OAuth2 tokens`_ to control access to the service registration and the OWS service access.
+You can use three types of tokens.
+
+Random Token
+++++++++++++
+
+Tokens with UUID strings stored in the local twitcher database.
+
+Edit the configuration file:
+
+.. code-block:: ini
+
+  twitcher.token.type = random_token # default
+
+
+Signed Token
+++++++++++++
+
+`JWT tokens`_ signed with a certificate. You can generate a self-signed certificate
+for testing with the Makefile:
+
+.. code-block:: console
+
+  $ make gencert
+
+Edit the configuration file:
+
+.. code-block:: ini
+
+  twitcher.token.type = signed_token
+  twitcher.token.keyfile = key.pem # private key
+  twitcher.token.certfile = pubkey.pem # public key
+
+Custom Token
+++++++++++++
+
+JWT tokens using a shared secret. You can generate a UUID secret with:
+
+.. code-block:: console
+
+  $ make gensecret
+
+Edit the configuration file:
+
+.. code-block:: ini
+
+  twitcher.token.type = custom_token
+  twitcher.token.secret = secret
+
+.. _OAuth2 tokens: https://oauthlib.readthedocs.io/en/latest/oauth2/tokens/bearer.html
+.. _JWT tokens: https://pyjwt.readthedocs.io/en/latest/usage.html
diff --git a/docs/source/dev_guide.rst b/docs/source/dev_guide.rst
@@ -53,6 +53,39 @@ Do the same as above using the ``Makefile``.
     $ make lint
     $ make coverage
 
+Upgrade Database
+----------------
+
+Initialize and upgrade the database using Alembic_.
+
+Generate your first revision:
+
+.. code-block:: console
+
+  $ conda activate twitcher
+  $ alembic -c development.ini revision --autogenerate -m "init"
+
+.. warning::
+
+    This first step is only needed in development to generate a new database schema version.
+
+Upgrade to that revision:
+
+.. code-block:: console
+
+  $ alembic -c development.ini upgrade head
+
+Load default data into the database using a script.
+
+.. code-block:: console
+
+  $ initialize_twitcher_db development.ini
+
+.. note::
+
+  You can use `make migrate` as a shortcut to upgrade or init the twitcher database (last two steps).
+
+
 Building the docs
 -----------------
 
@@ -84,3 +117,4 @@ See the bumpversion_ documentation for details.
 
 .. _bumpversion: https://pypi.org/project/bumpversion/
 .. _pytest: https://docs.pytest.org/en/latest/
+.. _Alembic: https://alembic.sqlalchemy.org/en/latest/
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,7 +7,6 @@
    installation
    configuration
    dev_guide
-   running
    tutorial
    api
    changes
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -55,34 +55,11 @@ For development you can use this command:
 Initialize Database
 ===================
 
-Initialize and upgrade the database using Alembic_.
-
-Generate your first revision:
-
-.. code-block:: console
-
-  $ conda activate twitcher
-  $ alembic -c development.ini revision --autogenerate -m "init"
-
-.. warning::
-
-    This first step is only needed in development to generate a new database schema version.
-
-Upgrade to that revision:
+Before you can start the service you need to initialize or upgrade the database:
 
 .. code-block:: console
 
-  $ alembic -c development.ini upgrade head
-
-Load default data into the database using a script.
-
-.. code-block:: console
-
-  $ initialize_twitcher_db development.ini
-
-.. note::
-
-  You can use `make migrate` as a shortcut to upgrade or init the twitcher database (last two steps).
+  $ make migrate
 
 Starting Twitcher Service
 =========================
@@ -94,6 +71,8 @@ Start the twitcher service using the `development.ini` configuration:
 .. code-block:: console
 
    $ pserve development.ini --reload
+   OR
+   $ make start
 
 .. _waitress: https://docs.pylonsproject.org/projects/waitress/en/latest/
 .. _Conda: https://conda.io/en/latest/