/sanic-security

An effective, simple, and async security library for the Sanic framework.

Primary LanguagePythonGNU Affero General Public License v3.0AGPL-3.0

Code style: black Downloads Conda Downloads


Sanic Security

An effective, simple, and async security library for the Sanic framework.

Table of Contents

About The Project

Sanic Security is an authentication, authorization, and verification library designed for use with Sanic. This library contains a variety of features including:

  • Login, registration, and authentication
  • Two-step verification
  • Captcha
  • Role based authorization with wildcard permissions

Please visit security.sunsetdeveloper.com for documentation.

Getting Started

In order to get started, please install pip.

Prerequisites

  • Pip

https://pypi.org/

Installation

  • Install the Sanic Security pip package.
pip3 install sanic-security
  • Install the Sanic Security pip package with the cryptography dependency included.

If you are planning on encoding or decoding JWTs using certain digital signature algorithms (like RSA or ECDSA which use the public secret and private secret), you will need to install the cryptography library. This can be installed explicitly, or as a required extra in the sanic-security requirement.

pip3 install sanic-security[crypto]
  • For developers, fork Sanic Security and install development dependencies.
pip3 install -e ".[dev]"

Configuration

Sanic Security configuration is merely an object that can be modified either using dot-notation or like a dictionary.

For example:

from sanic_security.configuration import config

config.SECRET = "This is a big secret. Shhhhh"
config["CAPTCHA_FONT"] = "./resources/captcha.ttf"

You can also use the update() method like on regular dictionaries.

Any environment variables defined with the SANIC_SECURITY_ prefix will be applied to the config. For example, setting SANIC_SECURITY_SECRET will be loaded by the application automatically and fed into the SECRET config variable.

You can load environment variables with a different prefix via calling the config.load_environment_variables("NEW_PREFIX_") method.

  • Default configuration values:
Key Value Description
SECRET This is a big secret. Shhhhh The secret used for generating and signing JWTs. This should be a string unique to your application. Keep it safe.
PUBLIC_SECRET None The secret used for verifying and decoding JWTs and can be publicly shared. This should be a string unique to your application.
SESSION_SAMESITE strict The SameSite attribute of session cookies.
SESSION_SECURE True The Secure attribute of session cookies.
SESSION_HTTPONLY True The HttpOnly attribute of session cookies. HIGHLY recommended that you do not turn this off, unless you know what you are doing.
SESSION_DOMAIN None The Domain attribute of session cookies.
SESSION_ENCODING_ALGORITHM HS256 The algorithm used to encode and decode session JWT's.
SESSION_PREFIX token Prefix attached to the beginning of session cookies.
MAX_CHALLENGE_ATTEMPTS 5 The maximum amount of session challenge attempts allowed.
CAPTCHA_SESSION_EXPIRATION 60 The amount of seconds till captcha session expiration on creation. Setting to 0 will disable expiration.
CAPTCHA_FONT captcha.ttf The file path to the font being used for captcha generation.
TWO_STEP_SESSION_EXPIRATION 200 The amount of seconds till two step session expiration on creation. Setting to 0 will disable expiration.
AUTHENTICATION_SESSION_EXPIRATION 2692000 The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.
ALLOW_LOGIN_WITH_USERNAME False Allows login via username and email.
INITIAL_ADMIN_EMAIL admin@example.com Email used when creating the initial admin account.
INITIAL_ADMIN_PASSWORD admin123 Password used when creating the initial admin account.

Usage

Sanic Security's authentication and verification functionality is session based. A new session will be created for the user after the user logs in or requests some form of verification (two-step, captcha). The session data is then encoded into a JWT and stored on a cookie on the user’s browser. The session cookie would be sent along with every subsequent request. The server can then compare the session stored on the cookie against the session information stored in the database to verify user’s identity and send a response with the corresponding state.

  • You can create the initial administrator account via the example below:

    create_initial_admin_account(app)
if __name__ == "__main__":
    app.run(host="127.0.0.1", port=8000)

    This account can be logged into and has complete authoritative access. Login credentials can be modified in config.

  • The tables in the below examples represent example request form-data (https://sanicframework.org/en/guide/basics/request.html#form).

Authentication

  • Registration

Phone can be null or empty.

Key Value
username example
email example@example.com
phone 19811354186
password examplepass 
account = await register(request)
two_step_session = await request_two_step_verification(request, account)
await email_code(two_step_session.code)  # Custom method for emailing verification code.
response = json("Registration successful!", two_step_session.bearer.json())
two_step_session.encode(response)
return response
  • Verify Account
Key Value
code AJ8HGD 
two_step_session = await verify_account(request)
return json(
    "You have verified your account and may login!", two_step_session.bearer.json()
)
  • Login

Login credentials are retrieved via the Authorization header. Credentials are constructed by first combining the username and the password with a colon (aladdin:opensesame), and then by encoding the resulting string in base64 (YWxhZGRpbjpvcGVuc2VzYW1l). Here is an example authorization header: Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l.

You can use a username as well as an email for login if ALLOW_LOGIN_WITH_USERNAME is true in the config.

authentication_session = await login(request)
response = json("Login successful!", authentication_session.bearer.json())
authentication_session.encode(response)
return response
  • Logout
authentication_session = await logout(request)
response = json("Logout successful!", authentication_session.bearer.json())
return response
  • Authenticate
authentication_session = await authenticate(request)
return json(
    "You have been authenticated.",
    authentication_session.bearer.json(),
)
  • Requires Authentication
@app.post("api/auth")
@requires_authentication()
async def on_authenticate(request, authentication_session):
    return json(
        "You have been authenticated.",
        authentication_session.bearer.json(),
    )

Captcha

A pre-existing font for captcha challenges is included in the Sanic Security repository. You may set your own font by downloading a .ttf font and defining the file's path in the configuration.

1001 Free Fonts

Recommended Font

Captcha challenge example:

Captcha image.

  • Request Captcha
captcha_session = await request_captcha(request)
response = captcha_session.get_image()
captcha_session.encode(response)
return response
  • Captcha
Key Value
captcha 2bH14b 
captcha_session = await captcha(request)
return json("Captcha attempt successful!", captcha_session.json())
  • Requires Captcha
Key Value
captcha 2bH14b 
@app.post("api/captcha")
@requires_captcha()
async def on_captcha(request, captcha_session):
    return json("Captcha attempt successful!", captcha_session.json())

Two-step Verification

  • Request Two-step Verification
Key Value
email example@example.com 
two_step_session = await request_two_step_verification(request)
await email_code(two_step_session.code)  # Custom method for emailing verification code.
response = json("Verification request successful!", two_step_session.bearer.json())
two_step_session.encode(response)
return response
  • Resend Two-step Verification Code
two_step_session = await TwoStepSession.decode(request)
await email_code(two_step_session.code)  # Custom method for emailing verification code.
return json("Verification code resend successful!", two_step_session.bearer.json())
  • Two-step Verification
Key Value
code AJ8HGD 
two_step_session = await two_step_verification(request)
response = json(
    "Two-step verification attempt successful!", two_step_session.bearer.json()
)
return response
  • Requires Two-step Verification
Key Value
code AJ8HGD 
@app.post("api/verify")
@requires_two_step_verification()
async def on_verify(request, two_step_session):
    response = json(
        "Two-step verification attempt successful!", two_step_session.bearer.json()
    )
    return response

Authorization

Sanic Security uses role based authorization with wildcard permissions.

Roles are created for various job functions. The permissions to perform certain operations are assigned to specific roles. Users are assigned particular roles, and through those role assignments acquire the permissions needed to perform particular system functions. Since users are not assigned permissions directly, but only acquire them through their role (or roles), management of individual user rights becomes a matter of simply assigning appropriate roles to the user's account; this simplifies common operations, such as adding a user, or changing a user's department.

Wildcard permissions support the concept of multiple levels or parts. For example, you could grant a user the permission printer:query, printer:query,delete, or printer:*.

  • Assign Role
await assign_role(
    "Chat Room Moderator",
    account,
    "channels:view,delete, account:suspend,mute, voice:*",
    "Can read and delete messages in all chat rooms, suspend and mute accounts, and control voice chat.",
)
  • Check Permissions
authentication_session = await check_permissions(request, "channels:view", "voice:*")
return text("Account is authorized.")
  • Require Permissions
@app.post("api/channel/voice/control")
@require_permissions("channels:view", "voice:*")
async def on_voice_chat_control(request, authentication_session):
    return text("Voice chat is now being controlled.")
  • Check Roles
authentication_session = await check_roles(request, "Chat Room Moderator")
return text("Account is authorized.")
  • Require Roles
@app.post("api/account/suspend")
@require_roles("Chat Room Moderator")
async def on_suspend_account(request, authentication_session):
    return text("Account successfully suspended.")

Testing

  • Set the TEST_DATABASE_URL configuration value.

  • Make sure the test Sanic instance (test/server.py) is running on your machine.

  • Run the unit test client (test/tests.py) for results.

Tortoise

Sanic Security uses Tortoise ORM for database operations.

Tortoise ORM is an easy-to-use asyncio ORM (Object Relational Mapper).

  • Initialise your models and database like so:
async def init():
    await Tortoise.init(
        db_url="sqlite://db.sqlite3",
        modules={"models": ["sanic_security.models", "app.models"]},
    )
    await Tortoise.generate_schemas()

or

register_tortoise(
    app,
    db_url="sqlite://db.sqlite3",
    modules={"models": ["sanic_security.models", "app.models"]},
    generate_schemas=True,
)
  • Define your models like so:
from tortoise.models import Model
from tortoise import fields


class Tournament(Model):
    id = fields.IntField(pk=True)
    name = fields.TextField()
  • Use it like so:
# Create instance by save
tournament = Tournament(name="New Tournament")
await tournament.save()

# Or by .create()
await Tournament.create(name="Another Tournament")

# Now search for a record
tour = await Tournament.filter(name__contains="Another").first()
print(tour.name)

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the GNU Affero General Public License v3.0. See LICENSE for more information.

Versioning

0.0.0

  • MAJOR version when you make incompatible API changes.

  • MINOR version when you add functionality in a backwards compatible manner.

  • PATCH version when you make backwards compatible bug fixes.

https://semver.org/