Python tools and helpers for microservices written in Python on top of Microkubes.
It contains tools:
- To register your serice with Microkubes API Gateway
- Security library that works with Microkubes own security and user management:
- Support for JWT based auth
- Support for OAuth based auth
- Integration with Flask, so you can secure your Flask API endpoints
To install micrkubes-python run:
pip install "git+https://github.com/Microkubes/microkubes-python#egg=microkubes-python"
If you want to hack around, you can install it with pip:
pip install -e "git+https://github.com/Microkubes/microkubes-python#egg=microkubes-python"
or clone this repository directly:
git clone https://github.com/Microkubes/microkubes-python
cd microkubes-python
pip setup.py develop
pip install -r dev-requirements.txt
If you're developing with Flask, then you need to install it additionaly:
pip install FlaskOptionally, if you wat to add /healthcheck endpoint in your Flask microservice, you need to install
the healthcheck library:
pip install healthcheckAs an example we can write small hello-world-like service in Flask (service.py):
import os
from flask import Flask
from microkubes.gateway import KongGatewayRegistrator
app = Flask(__name__)
registrator = KongGatewayRegistrator(os.environ.get("API_GATEWAY_URL", "http://localhost:8001")) # Use the Kong registrator for Microkubes
# Self-registration on the API Gateway must be the first thing we do when running this service.
# If the registration fails, then the whole service must terminate.
registrator.register(name="hello-service", # the service name.
paths=["/"], # URL pattern that Kong will use to redirect requests to out service
host="hello-service.service.consul", # The hostname of the service.
port=5000) # Flask default port. When redirecting, Kong will call us on this port.
@app.route("/hello")
def hello():
return "Hello from Flask service on Microkubes"The library provides the basic function of registering your own service with the API Gateway.
The tools are provided in package microkubes.gateway.
To register your service on a gateway, you need to use a Registrator. microkubes-python comes
with support for Kong Gateway.
Example:
from microkubes.gateway import KongGatewayRegistrator
registrator = KongGatewayRegistrator(os.environ.get("API_GATEWAY_URL", "http://localhost:8001")) # Use the Kong registrator for Microkubes
# Self-registration on the API Gateway must be the first thing we do when running this service.
# If the registration fails, then the whole service must terminate.
registrator.register(name="hello-service", # the service name.
paths=["/"], # URL pattern that Kong will use to redirect requests to out service
host="hello-service.service.consul", # The hostname of the service.
port=5000) # Flask default port. When redirecting, Kong will call us on this port.Note that the registration of our service to the gateway should be one of the first things that the service does. On Microkubes microservices do this check first and terminate if anything goes wrong.
microkubes-python provides tools for implementing security in your services that works with the
security infrastructure provided by Microkubes.
The security library offers python API for setting up security based on yor needs. It comes with couple of security providers out-of-the-box:
- JWT provider - can decode and validate JWTs generated by Microkubes
jwt-issuerservice - OAuth2 provider -can decode and validate OAuth2 tokens generated by the OAuth2 Authorization Server in Microkubes.
- SAML service provider - can decode session created from Identity Provider and populate auth object
The security is configured as a chain of providers, so you can have more than one type except SAML SP on any endpoint in your service.
The main entrypoint for this is the SecurityChain. When a new request is made by the client, the SecurityChain
passes it to every provider in the chain. Every provider attempts to authenticate and authorize the request.
If some of the providers is successful, then Auth object is generated and set i the SecurityContext.
An example of setting up security chain:
from microkubes.security import (SecurityChain,
ThreadLocalSecurityContext,
JWTSProvider,
is_authenticated_provider,
KeyStore)
store = KeyStore(dir_path='./keys') # we need key store with the RSA keys so we can validate the JWT signature
context = ThreadLocalSecurityContext() # Keeps the Auth in thread-local, which is fine for tests, but should be avoided for production
chain = (SecurityChain(context).
provider(JWTSecurityProvider(key_store=store)). # Security chain with JWT auth
provider(is_authenticated_provider)) # check if the request has been authenticated
# assuming we receive an HTTP request, the processing of the request can be done like this:
# try:
# chain.execute(context, request, response)
# except SecurityException serr:
# response.status_code = serr.status_code
# response.write_json({"code": serr.status_code, "message": str(serr)})
# then we can access the context to get the Auth object:
auth = context.get_auth()You can secure your Flask services by using the convinience security builder for Flask.
You need to create new Security and then use Security.secured decorator on your endpoints.
By using the example in Flask above, we can secure the action by setting up a full security chain:
import os
from flask import Flask
from microkubes.gateway import KongGatewayRegistrator
from microkubes.security import FlaskSecurity
app = Flask(__name__)
registrator = KongGatewayRegistrator(os.environ.get("API_GATEWAY_URL", "http://localhost:8001")) # Use the Kong registrator for Microkubes
# set up a security chain
sec = (FlaskSecurity().
keys_dir("./keys"). # set up a key-store that has at least the public keys from the platform
jwt(). # Add JWT support
oauth2(). # Add OAuth2 support
build()) # Build the security for Flask
# Self-registration on the API Gateway must be the first thing we do when running this service.
# If the registration fails, then the whole service must terminate.
registrator.register(name="hello-service", # the service name.
paths=["/"], # URL pattern that Kong will use to redirect requests to out service
host="hello-service.service.consul", # The hostname of the service.
port=5000) # Flask default port. When redirecting, Kong will call us on this port.
@app.route("/hello")
@sec.secured # this action is now secure
def hello():
auth = sec.context.get_auth() # get the Auth from the security context
return "Hello %s from Flask service on Microkubes" % auth.username
SAML service provider can not be combined with others providers because if user is not authenticate then request is redirected to the Identity Provider. Setting up SAML SP is similar to the other providers, you need to create new Security and then use Security.secured decorator on your endpoints. The microkubes SAML SP is built on top of python3-saml library.
Below is the example that shows how to secure action in Flask:
import os
import logging
from flask import (Flask, request, session, redirect, make_response)
from microkubes.gateway import KongGatewayRegistrator
from microkubes.security import FlaskSecurity, SAMLSPUtils
logging.basicConfig(level=logging.DEBUG)
app = Flask(__name__)
app.config['SECRET_KEY'] = os.getenv('SECRET_KEY') or 'example-service'
configSAML ={
"strict": True,
"debug": False,
"sp": {
"entityId": "http://localhost:5000/metadata",
"assertionConsumerService": {
"url": "http://localhost:5000/acs",
"binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
},
"x509cert": "",
"privateKey": ""
},
"idp": {
"entityId": "http://localhost:8080/saml/idp/metadata",
"singleSignOnService": {
"url": "http://localhost:8080/saml/idp/sso",
"binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
},
"x509cert": ""
},
"security": {
"nameIdEncrypted": False,
"authnRequestsSigned": False,
"signMetadata": True,
"wantMessagesSigned": True,
"wantAssertionsSigned": True,
"wantNameId": False,
"wantNameIdEncrypted": False,
"wantAssertionsEncrypted": False,
},
"registration_url":"http://localhost:8080/saml/idp/services",
"privateKeyName":"service.key",
"certName": "service.cert"
}
# set up a security chain
sec = (FlaskSecurity().
keys_dir("./keys"). # set up a key-store that has at least the public keys from the platform
saml(config=configSAML). # Set SAML SP
build()) # Build the security for Flask
@app.route("/")
@sec.secured # this action is now secure
def hello():
auth = sec.context.get_auth() # get the Auth from the security context
return "Hello %s from Flask service on Microkubes" % auth.username
# This method is executed before any request in Flask. In order to serve SP metadata and
# assertion consumer service endpoints define this method, do not forget decorator
@app.before_request
def serve_saml_ednpoints():
if '/metadata' in request.path:
metadata, errors = SAMLSPUtils.get_sp_metadata(configSAML)
if len(errors) == 0:
resp = make_response(metadata, 200)
resp.headers['Content-Type'] = 'text/xml'
return resp
else:
return make_response(', '.join(errors), 500)
if '/acs' in request.path:
return SAMLSPUtils.serve_acs(request, session, configSAML, redirect)ACL provider allows for integrating policies in a microservice as part of the security chain.
Policies are created as part of the ACL configuration, where you can specify fine-grained control over how each authenticated user has access to each resource. Each policy object has the following structure:
{
'id': 'user-ana-allow-access',
'description': 'Allow the user ana to read todos',
'resources': ['/todos'],
'actions': [
'api:read'
],
'subjects': ['ana'],
'roles': ['user'],
'organizations': ['test-organization'],
'namespaces': ['test-namespace']
}
Where:
- id is an id of the policy.
- description is a description of what the policy does.
- resources is a list of resource paths.
- actions is a list of API actions. Currently supports "api:read" (
GET) and "api:write" (POST,PUT,PATCH,DELETE). - subjects is a list of users that are allowed to access the resource in the policy.
- roles is a list of roles.
- organizations is a list of organizations that a user belongs to.
- namespaces is a list of namespaces that a user belongs to.
Based on the currently authenticated user, all policy properties are checked against of those set in the JWT token.
The ACL provider is built on top of miracle-acl library.
Below is the example that shows how to configure the ACL provider and secure an action in Flask:
import logging
from flask import Flask
from microkubes.security import FlaskSecurity
logging.basicConfig(level=logging.DEBUG)
app = Flask(__name__)
config_acl = {
'policies': [{
'id': 'user-ana-allow-access',
'description': 'Allow the user ana to read todos',
'resources': ['/todos'],
'actions': [
'api:read'
],
'subjects': ['ana'],
'roles': ['user'],
'organizations': ['test-organization'],
'namespaces': ['test-namespace']
},
{
'id': 'admin-allow-full-access',
'descrition': 'Allow the admin to have full access.',
'resources': ['/todos'],
'actions': [
'api:read',
'api:write'
],
'subjects': [],
'roles': ['admin'],
'organizations': ['test-organization', 'test-organization-1'],
'namespaces': ['test-namespace', 'test-namespace-1']
}]
}
sec = (FlaskSecurity().
keys_dir('./keys').
jwt().
oauth2().
acl(config=config).
build())
@app.route('/todos', methods=['GET'])
@sec.secured
def todos():
auth = sec.context.get_auth() # get the Auth from the security context
return 'Hello %s from Flask service on Microkubes' % auth.usernameFirst make sure you have healthcheck installed:
pip install healthcheckThen add healthcheck to your microservice by adding the following code:
from flask import Flask
from microkubes.tools import add_healthcheck
app = Flask(__name__)
add_healthcheck(app)To add version endpoint to your microservice, first you need to create a configuration JSON file in the root of the microservice project, that looks like this:
{
"version": "1.0.0"
}After that, add the following code after you create the Flask instance:
import os
from flask import Flask
from microkubes.tools import add_version_endpoint, read_config
app = Flask(__name__)
current_dir_path = os.path.dirname(os.path.realpath(__file__))
config = read_config(current_dir_path + '/config.json')
add_version_endpoint(app, config)To test it out, start the Flask server and do curl http://localhost:5000/version and it will return:
{
"version": "1.0.0"
}For contributing to this repository or its documentation, see the Contributing guidelines.