Tutorial¶
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:
$ 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:
$ 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:
$ 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:
$ 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
:
$ 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:
$ 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:
$ curl -k "http://localhost:8000/ows/proxy/emu?service=WPS&request=GetCapabilities"
Run a DescribeProcess
request:
$ 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:
$ 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:
$ 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:
$ 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:
$ 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
:
$ twitcherctl -k --username demo --password demo register --name emu --auth cert http://localhost:5000/wps
The GetCapabilities
and DescribeProcess
requests are not blocked:
$ 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:
$ 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:
$ 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):
Update your twitcher configuration in development.ini
:
twitcher.token.type = keycloak_token
keycloak.token.secret = public_key_copied_from_keycloak
Start the twitcher service and register the Emu WPS:
$ 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).