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.
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'}]
OpenAPI interface¶
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:
https://requests-oauthlib.readthedocs.io/en/latest/index.html
https://docs.apigee.com/api-platform/security/oauth/oauth-20-client-credentials-grant-type
- 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 Security¶
OWS Registry¶
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