.. _tutorial: ******** Tutorial ******** .. contents:: :local: :depth: 2 Using the OWSProxy with a WPS application ========================================= The ``OWSProxy`` is a proxy service for OWS services. First you need an external WPS. You can use `Emu WPS service `_ from Birdhouse. Get it from GitHub and run the installation: .. code-block:: console $ git clone https://github.com/bird-house/emu.git $ cd emu $ make install $ make start The Emu WPS service is available by default at the URL: http://localhost:5000/wps?service=WPS&version=1.0.0&request=GetCapabilities Make sure Twitcher is installed and running: .. code-block:: console $ cd ../twitcher # cd into the twitcher installation folder $ pserve development.ini Prepare your Client Application ------------------------------- Register your client application at twitcher to get a *client_id* and *client_secret*: .. code-block:: console $ twitcherctl -k --username demo --password demo add --name demo_app {'name': 'demo_app', 'client_id': 'id', 'client_secret': 'secret'} Get an access token to use the registration service using your OAuth *client_id* and *client_secret* with scope *register*: .. code-block:: console $ twitcherctl -k gentoken -i client_id -s client_secret --scope register {'access_token': 'TOKEN', 'expires_in': 3600, 'scope': ['register'], 'token_type': 'Bearer'} Register a WPS service ---------------------- Register the Emu WPS service at the Twitcher ``OWSProxy``: .. code-block:: console $ twitcherctl -k --username demo --password demo register --name emu http://localhost:5000/wps If you don't provide a name with ``--name`` option then a nice name will be generated, for example ``sleepy_flamingo``. Use the ``list`` command to see which WPS services are registered with OWSProxy: .. code-block:: console $ twitcherctl -k --username demo --password demo list [{'url': 'http://localhost:5000/wps', 'type': 'wps', 'name': 'emu', 'auth': 'token'}] Access a registered service --------------------------- By default the registered service is available at the URL ``https://localhost:8000/ows/proxy/{service_name}``. Replace the ``service_name`` with the registered name. Run a ``GetCapabilities`` request for the registered Emu WPS service: .. code-block:: console $ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&request=GetCapabilities" Run a ``DescribeProcess`` request: .. code-block:: console $ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&version=1.0.0&request=DescribeProcess&identifier=hello" Use a token to run an execute request ------------------------------------- By default the WPS service is protected by the ``OWSSecurity`` wsgi middleware. You need to provide an OAuth access token to run an execute request. Run an ``Exceute`` request: .. code-block:: console $ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&version=1.0.0&request=Execute&identifier=hello&DataInputs=name=tux" Now you should get an XML error response with a message that you need to provide an access token. We need to generate an access token with ``twitcherctl`` using OAuth *client_id* and *client_secret* with scope *compute*: .. code-block:: console $ twitcherctl -k gentoken -i client_id -s client_secret --scope compute {'access_token': 'TOKEN', 'expires_in': 3600, 'scope': ['compute'], 'token_type': 'Bearer'} By default the token has a limited life time of one hour. For testing you can provide the OAuth token as HTTP parameter: .. code-block:: console $ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&version=1.0.0&request=Execute&identifier=hello&DataInputs=name=tux&access_token=TOKEN" But you should use an HTTP header: .. code-block:: console $ curl -k -H 'Authorization: Bearer TOKEN' "http://localhost:8000/ows/proxy/emu?service=WPS&version=1.0.0&request=Execute&identifier=hello&DataInputs=name=tux" Use x509 certificates to control client access ============================================== .. warning:: You need an Nginx web-server in front of the Twitcher WSGI service to use x509 certificates. .. hint:: You can install Twitcher with Nginx using an Ansible playbook_. Since version 0.3.6 Twitcher is prepared to use x509 certificates to control client access. By default it is configured to accept x509 proxy certificates from ESGF_. Register the Emu WPS service at the Twitcher ``OWSProxy`` with ``auth`` option ``cert``: .. code-block:: console $ twitcherctl -k --username demo --password demo register --name emu --auth cert http://localhost:5000/wps The ``GetCapabilities`` and ``DescribeProcess`` requests are not blocked: .. code-block:: console $ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&request=GetCapabilities" $ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&version=1.0.0&request=DescribeProcess&identifier=hello" When you run an ``Exceute`` request without a certificate you should get an exception report: .. code-block:: console $ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&version=1.0.0&request=Execute&identifier=hello&DataInputs=name=tux" Now you should get an XML error response with a message that you need to provide a valid X509 certificate. Get a valid proxy certificate from ESGF, you may use the `esgf-pyclient`_ to run a myproxy logon. Let's say your proxy certificate is ``cert.pem``, then run the exceute request again using this certificate: .. code-block:: console $ curl --cert cert.pem --key cert.pem -k "http://localhost:8000/ows/proxy/emu?service=WPS&version=1.0.0request=Execute&identifier=hello&DataInputs=name=tux" Keycloak example ================ Set-up a demo Keycloak service using an Ansible `playbook `_. The keycloak service is available at (``username=admin``, ``password=admin``): http://localhost:8080/auth/ You need to copy the public key of your Keycloak realm to the twitcher configuration (see screenshot): .. image:: _images/keycloak-realm-public-key.png Update your twitcher configuration in ``development.ini``: .. code-block:: ini twitcher.token.type = keycloak_token keycloak.token.secret = public_key_copied_from_keycloak Start the twitcher service and register the Emu_ WPS: .. code-block:: console $ twitcherctl -k --username demo --password demo register --name emu http://localhost:5000/wps Try the demo notebook to access a token from the keycloak and execute a WPS process. Use ``client_id=demo`` and copy the client secret from Keycloak in `Clients/demo/Credentials/Secret` (see screenshot). .. image:: _images/keycloak-client-secret.png .. toctree:: :maxdepth: 1 notebooks/twitcher-keycloak-demo .. _ESGF: https://esgf.llnl.gov/ .. _esgf-pyclient: https://github.com/ESGF/esgf-pyclient .. _playbook: https://github.com/bird-house/ansible-wps-playbook .. _Emu: https://github.com/bird-house/emu