axioms-flask-py

Flask SDK for OAuth2 / OpenID Connect based authentication and authorization providers (Previously designed for Axioms). Secure your Flask APIs using OAuth2 / OpenID Connect based authentication and authorization checks.

Prerequisite

• Python 3.7+
• An OAuth2/OIDC client which can obtain access token after user's authentication and authorization and include obtained access token as bearer in Authorization header of all API request sent to Python/Flask application server.

Install SDK

Install axioms-flask-py in you Flask API project,

pip install axioms-flask-py

Documentation

Prerequisite

• Python 3.7+
• An Axioms client which can obtain access token after user's authentication and authorization and include obtained access token as bearer in Authorization header of all API request sent to Python/Flask application server.

Install SDK

Install axioms-flask-py in you Flask API project,

pip install axioms-flask-py

Add environment variables

Create a .env file and add following configs

Option 1: Using AXIOMS_DOMAIN (for Axioms or standard OAuth2/OIDC providers)

AXIOMS_DOMAIN=<your-axioms-slug>.axioms.io
AXIOMS_AUDIENCE=<your-axioms-resource-identifier-or-endpoint>

Option 2: Using AXIOMS_JWKS_URL (for custom JWKS endpoints)

AXIOMS_JWKS_URL=https://my-auth.domain.com/oauth2/.well-known/jwks.json
AXIOMS_AUDIENCE=<your-axioms-resource-identifier-or-endpoint>

Configuration Options:

• AXIOMS_AUDIENCE (required): Your resource identifier or API audience
• AXIOMS_JWKS_URL (optional): Full URL to your JWKS endpoint
• AXIOMS_DOMAIN (optional): Your auth domain (e.g., my-auth.domain.com)

Note: You must provide either AXIOMS_JWKS_URL or AXIOMS_DOMAIN.

Claims Handling:

• Roles are checked from roles claim, or https://{AXIOMS_DOMAIN}/claims/roles if using namespaced claims
• Permissions are checked from permissions claim, or https://{AXIOMS_DOMAIN}/claims/permissions if using namespaced claims
• Scopes are checked from the standard scope claim

Load environment variables

In your Flask app file (where flask app is declared) add following.

from flask_dotenv import DotEnv
env = DotEnv(app)

Register Error

In your Flask app file (where flask app is declared) add following.

from flask import jsonify
from axioms_flask.error import AxiomsError

@app.errorhandler(AxiomsError)
def handle_auth_error(ex):
    response = jsonify(ex.error)
    response.status_code = ex.status_code
    if ex.status_code == 401:
        response.headers[
            "WWW-Authenticate"
        ] = "Bearer realm='{}', error='{}', error_description='{}'".format(
            app.config["AXIOMS_DOMAIN"], ex.error["error"], ex.error["error_description"]
        )
    return response

Guard Your Flask API Views

Use following decorators to guard you API views.

Examples

• Check openid or profile scope present in the token

from axioms_flask.decorators import has_valid_access_token, has_required_scopes

private_api = Blueprint("private_api", __name__)

@private_api.route('/private', methods=["GET"])
@has_valid_access_token
@has_required_scopes(['openid', 'profile'])
def api_private():
    return jsonify({'message': 'All good. You are authenticated!'})

• Check sample:role role present in the token

from axioms_flask.decorators import has_valid_access_token, has_required_roles

role_api = Blueprint("role_api", __name__)

@role_api.route("/role", methods=["GET", "POST", "PATCH", "DELETE"])
@has_valid_access_token
@has_required_roles(["sample:role"])
def sample_role():
    if request.method == 'POST':
        return jsonify({"message": "Sample created."})
    if request.method == 'PATCH':
        return jsonify({"message": "Sample updated."})
    if request.method == 'GET':
        return jsonify({"message": "Sample read."})
    if request.method == 'DELETE':
        return jsonify({"message": "Sample deleted."})

• Check permission present in the token at API method level

from axioms_flask.decorators import has_valid_access_token, has_required_permissions

permission_api = Blueprint("permission_api", __name__)

@permission_api.route("/permission", methods=["POST"])
@has_valid_access_token
@has_required_permissions(["sample:create"])
def sample_create():
    return jsonify({"message": "Sample created."})


@permission_api.route("/permission", methods=["PATCH"])
@has_valid_access_token
@has_required_permissions(["sample:update"])
def sample_update():
    return jsonify({"message": "Sample updated."})


@permission_api.route("/permission", methods=["GET"])
@has_valid_access_token
@has_required_permissions(["sample:read"])
def sample_read():
    return jsonify({"message": "Sample read."})


@permission_api.route("/permission", methods=["DELETE"])
@has_valid_access_token
@has_required_permissions(["sample:delete"])
def sample_delete():
    return jsonify({"message": "Sample deleted."})

Flask Sample

To see a complete working example download Flask sample from our Github repository or simply deploy to heroku by clicking following button. You will need to provide Axioms domain and Axioms audience to complete deployment.