API Reference

Twitcher Client

class twitcher.client.TwitcherService(url, username=None, password=None, verify=True)[source]

TwitcherService is a twitcher client to talk to the twitcher service API.

add_client_app(name=None, redirect_uri=None)[source]

Add a client application to twitcher with optional name.

clear_services()[source]

Remove all OWS services.

fetch_token(client_id, client_secret, scope=None, keycloak=False)[source]

Get an access token with given scope.

get_service(name)[source]

Get an OWS service with given name.

list_services()[source]

List all registered OWS services.

register_service(name, url, data=None)[source]

Register a service.

unregister_service(name)[source]

Remove registered service with given name.

Twitcher CLI

The twitcherctl is a command line tool to control the twitcher service. It is used to generate access tokens and to register OWS services.

twitcherctl is part of the twitcher installation:

$ twitcherctl -h

twitcherctl Commands and Options

twitcherctl has the following command line options:

-h, --help

Print usage message and exit

-s, --serverurl

URL on which twitcher server is listening (default “http://localhost:8000/”).

-u, --username

Username to access twitcher server.

-p, --password

Password to access twitcher server.

-k, --insecure

Don’t validate the server’s certificate.

List of available commands:

add

Add OAuth2 client application.

gentoken

Generates an access token.

list

Lists all registered OWS services used by OWS proxy.

clear

Removes all OWS services from the registry.

register

Adds OWS service to the registry to be used by the OWS proxy.

unregister

Removes OWS service from the registry.

Add an OAuth2 client application

Register an application using basic authentication with username and password (name and redirect-uri are optional):

$ twitcherctl -k --username demo --password demo add --name demo_app --redirect-uri http://localhost/demo_app
{'client_id': 'id', 'client_secret': 'secret'}

The result is an OAuth client_id and client_secret.

Generate an access token

Get an OAuth access token using client_id and client_secret for given scope:

$ twitcherctl -k gentoken -i client_id -s client_secret --scope compute
{'access_token': 'TOKEN', 'expires_in': 3600, 'scope': ['compute'], 'token_type': 'Bearer'}

Possible scopes are: compute, register.

You can also get a token from a Keycloak OAuth service using the client credentials workflow:

$ twitcherctl -k -s http://localhost:8080 gentoken -i client_id -s client_secret --scope compute --keycloak

Register an OWS Service for the OWS Proxy

See the available options:

twitcherctl -k register -h

Register a local WPS service using an OAuth access token:

$ twitcherctl -k --username demo --password demo register http://localhost:5000/wps
tiny_buzzard

You can use the --name option to provide a name (used by the OWS proxy). Otherwise a nice name will be generated.

List registered services

The list command shows the registered OWS services:

$ twitcherctl -k --username demo --password demo list
[{'url': 'http://localhost:5000/wps', 'type': 'wps', 'name': 'tiny_buzzard', 'auth': 'token'}]
class twitcher.scripts.twitcherctl.TwitcherCtl[source]

Command line to interact with the OAuth and OpenAPI interface of the twitcher service.

OpenAPI interface

class twitcher.api.TwitcherAPI[source]

Twitcher API defined with OpenAPI.

static clear_services(request)[source]

Clear all services.

static get_service(request)[source]

Get registered service.

static list_services(request)[source]

Returns a list of registered services.

static register_service(request)[source]

Register a service.

static unregister_service(request)[source]

Remove registered service.

OAuth2 Tokens

twitcher.oauth2

This module implements the OAuth2 model to generate access tokens. These tokens are used to access the compute services (scope=compute). The compute services are accessed via the OWS proxy.

The implementation is using the OAuth2 client credentials grant type

Currently three types of access tokens can be used:

random_token

The access token is a UUID string. The tokens are stored in a local database and can be used for local validation only.

signed_token

A JWT token signed with a X.509 certificate. The token can be validated without contacting a validation service.

custom_token

A JWT token with a secret (UUID string) which can be shared for validation. The token can be validated without contacting a validation service.

keycloak_token

A JWT token generated by a Keycloak OAuth2 service.

See also the OAuth2 token documenation

The implementation is using the pyramid-oauthlib library. The code is also inspired by the following OAuth libraries:

Further reading:

twitcher.oauth2.generate_token_view(request)[source]

Core functionality is available directly from the request.

Responses from OAuthLib are wrapped in a response object of type pyramid.response.Response so they can be returned directly from views.

twitcher.oauth2.register_client_app_view(request)[source]

Register a new client application and returns client_id and client_secret.

Uses basic authentication.

class twitcher.oauth2.RandomTokenValidator[source]
save_bearer_token(token_response, request, *args, **kwargs)[source]

Persist the Bearer token.

validate_bearer_token(token, scopes, request)[source]

Validate access token.

Parameters
  • token – A string of random characters

  • scopes – A list of scopes

  • request – The Request object passed by oauthlib

The validation validates:

  1. if the token is available

  2. if the token has expired

  3. if the scopes are available

class twitcher.oauth2.SignedTokenValidator(cert, key, issuer)[source]
validate_bearer_token(token, scopes, request)[source]

Ensure the Bearer token is valid and authorized access to scopes.

Parameters
  • token – A string of random characters.

  • scopes – A list of scopes associated with the protected resource.

  • request – The HTTP Request (oauthlib.common.Request)

A key to OAuth 2 security and restricting impact of leaked tokens is the short expiration time of tokens, always ensure the token has not expired!.

Two different approaches to scope validation:

  1. all(scopes). The token must be authorized access to all scopes

    associated with the resource. For example, the token has access to read-only and images, thus the client can view images but not upload new. Allows for fine grained access control through combining various scopes.

  2. any(scopes). The token must be authorized access to one of the

    scopes associated with the resource. For example, token has access to read-only-images. Allows for fine grained, although arguably less convenient, access control.

A powerful way to use scopes would mimic UNIX ACLs and see a scope as a group with certain privileges. For a restful API these might map to HTTP verbs instead of read, write and execute.

Note, the request.user attribute can be set to the resource owner associated with this token. Similarly the request.client and request.scopes attribute can be set to associated client object and authorized scopes. If you then use a decorator such as the one provided for django these attributes will be made available in all protected views as keyword arguments.

Parameters
  • token – Unicode Bearer token

  • scopes – List of scopes (defined by you)

  • request – The HTTP Request (oauthlib.common.Request)

Return type

True or False

Method is indirectly used by all core Bearer token issuing grant types:
  • Authorization Code Grant

  • Implicit Grant

  • Resource Owner Password Credentials Grant

  • Client Credentials Grant

class twitcher.oauth2.CustomTokenValidator(secret, issuer)[source]
validate_bearer_token(token, scopes, request)[source]

Ensure the Bearer token is valid and authorized access to scopes.

Parameters
  • token – A string of random characters.

  • scopes – A list of scopes associated with the protected resource.

  • request – The HTTP Request (oauthlib.common.Request)

A key to OAuth 2 security and restricting impact of leaked tokens is the short expiration time of tokens, always ensure the token has not expired!.

Two different approaches to scope validation:

  1. all(scopes). The token must be authorized access to all scopes

    associated with the resource. For example, the token has access to read-only and images, thus the client can view images but not upload new. Allows for fine grained access control through combining various scopes.

  2. any(scopes). The token must be authorized access to one of the

    scopes associated with the resource. For example, token has access to read-only-images. Allows for fine grained, although arguably less convenient, access control.

A powerful way to use scopes would mimic UNIX ACLs and see a scope as a group with certain privileges. For a restful API these might map to HTTP verbs instead of read, write and execute.

Note, the request.user attribute can be set to the resource owner associated with this token. Similarly the request.client and request.scopes attribute can be set to associated client object and authorized scopes. If you then use a decorator such as the one provided for django these attributes will be made available in all protected views as keyword arguments.

Parameters
  • token – Unicode Bearer token

  • scopes – List of scopes (defined by you)

  • request – The HTTP Request (oauthlib.common.Request)

Return type

True or False

Method is indirectly used by all core Bearer token issuing grant types:
  • Authorization Code Grant

  • Implicit Grant

  • Resource Owner Password Credentials Grant

  • Client Credentials Grant

OWS Security

class twitcher.owssecurity.OWSSecurity[source]
verify_request(request)[source]

Verify that the service request is allowed.

This method verifies that the provided credentials are valid. Depending on the authentication configuration this could be a client X509 certificate or an OAuth2 token.

OWS Registry

class twitcher.owsregistry.OWSRegistry(servicestore)[source]

OWS Service Registry is a service to register OWS services for the OWS proxy.

clear_services()[source]

Removes all services from the service store.

get_service_by_name(name)[source]

Gets service with given name from service store.

get_service_by_url(url)[source]

Gets service with given url from service store.

list_services()[source]

Lists all registered OWS services.

register_service(name, url, *args, **kwargs)[source]

Adds an OWS service with the given name and url to the service store.

unregister_service(name)[source]

Removes OWS service with the given name from the service store.

OWS Proxy

The owsproxy is a service which acts as a proxy for registered OWS services.

The implementation of owsproxy is based on papyrus_ogcproxy

See also: https://github.com/nive/outpost/blob/master/outpost/proxy.py