API Reference¶
Twitcher Client¶
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'}]
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:
https://oauthlib.readthedocs.io/en/latest/oauth2/tokens/bearer.html
https://requests-oauthlib.readthedocs.io/en/latest/index.html
-
class
twitcher.oauth2.
RandomTokenValidator
[source]¶ -
-
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:
if the token is available
if the token has expired
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:
- all(scopes). The token must be authorized access to all scopes
associated with the resource. For example, the token has access to
read-only
andimages
, thus the client can view images but not upload new. Allows for fine grained access control through combining various scopes.
- 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:
- all(scopes). The token must be authorized access to all scopes
associated with the resource. For example, the token has access to
read-only
andimages
, thus the client can view images but not upload new. Allows for fine grained access control through combining various scopes.
- 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¶
OWS Proxy¶
The owsproxy is based on papyrus_ogcproxy
See also: https://github.com/nive/outpost/blob/master/outpost/proxy.py