API Reference

Twitcher Client

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

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

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

Add a client application to twitcher with optional name.

clear_services(access_token)[source]

Remove all OWS services.

fetch_token(client_id, client_secret, scope=None)[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(access_token, name, url, data=None)[source]

Register a service.

unregister_service(access_token, 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/”).

-t, --token

OAuth access token for twitcher service.

-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 add --username demo --password demo --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

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 -t TOKEN 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 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.

Twitcher OpenAPI

class twitcher.api.TwitcherAPI[source]

Twitcher API defined with OpenAPI.

clear_services()[source]

Clear all services.

get_service()[source]

Get registered service.

list_services()[source]

Returns a list of registered services.

register_service()[source]

Register a service.

unregister_service()[source]

Remove registered service.

OWS Security

twitcher.oauth2

Using OAuth2 client_credentials grant type: https://docs.apigee.com/api-platform/security/oauth/oauth-20-client-credentials-grant-type

Code examples taken from:

Example usage:

Get Token:

http://localhost:8000/oauth/token?grant_type=client_credentials&client_id=alice&client_secret=secret

Use Token:

http://localhost:8000/ows/proxy/emu?access_token=TOKEN&service=wps&request=Execute&version=1.0.0&DataInputs=name=Stranger

TODO:

  • use external login service (github, esgf, …)

  • use external oauth service for compute

Resources:

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 Registry

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

OWS Service Registry.

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.