Skip to content
This repository has been archived by the owner on Jun 19, 2020. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time


A Security Framework for Python Applications

Project web site:

What is Yosai

Yosai is a "security framework" that features authentication, authorization, and session management from a common, intuitive API.


Yosai is based on Apache Shiro, written in Java and widely used today.

Yosai is a Framework


It is a framework that is is designed in such a way that it can be used to secure a variety of python applications, not just web applications. This is accomplished by completely decoupling security-related services from the rest of an application and writing adapters for each specific type of client.

Key Features

  • Enables Role-Based Access Control policies through permission-level and role-level access control
  • Two-Factor Authentication, featuring Time-based One-Time Passwords
  • Native Support for Caching and Serialization
  • A Complete Audit Trail of Events
  • Batteries Included: Extensions Ready for Use
  • "RunAs" Administration Tool
  • Event-driven Processing
  • Ready for Web Integration

Python 3 Supported

Yosai requires Python 3.4 or newer. There are no plans to support python2 due to anticipated optimizations that require newer versions of python.


First, install Yosai from PyPI using pip: pip install yosai

Installing from PyPI, using pip, will install the project package that includes yosai.core and yosai.web, a default configuration, and project dependencies.

Basic Authentication: UsernamePassword

yosai = Yosai(env_var='YOSAI_SETTINGS')

with Yosai.context(yosai):
    current_user = Yosai.get_current_subject()

    authc_token = UsernamePasswordToken(username='thedude',

    except AuthenticationException:
        # insert here

Two-Factor Authentication: UsernamePassword and TOTP

2FA Step 1: UsernamePassword

yosai = Yosai(env_var='YOSAI_SETTINGS')

with Yosai.context(yosai):
    current_user = Yosai.get_current_subject()

    userpass_token = UsernamePasswordToken(username='thedude',

    except AdditionalAuthenticationRequired: 
        # communicate a two-factor token request to user         
    except IncorrectCredentialsException: 
        # user failed to authenticate 

2FA Step 2: TOTP

yosai = Yosai(env_var='YOSAI_SETTINGS')

with Yosai.context(yosai):
    current_user = Yosai.get_current_subject()

    totp_token = TOTPToken(user_provided_token) 

    except IncorrectCredentialsException: 
        # user failed to authenticate 

Authorization Example

The following example was created to illustrate the myriad ways that you can declare an authorization policy in an application, ranging from general role-level specification to very specific "scoped" permissions. The authorization policy for this example is as follows:

  • Either a user with role membership "patient" or "nurse" may request a refill of a medical prescription
  • A user who is granted permission to write prescriptions may obtain the list of pending prescription refill requests
  • A user who is granted permission to write prescriptions for a specific patient may issue a prescription for that patient
@Yosai.requires_role(roleid_s=['patient', 'nurse'], logical_operator=any)
def request_prescription_refill(patient, prescription):

def get_prescription_refill_requests(patient):

def issue_prescription(patient, prescription):

Note how the authorization policy is declared using yosai's authorization decorators. These global decorators are associated with the yosai instance when the yosai instance is used as a context manager.

with Yosai.context(yosai):

    for prescription in get_prescription_refill_requests(patient):
        issue_prescription(patient, prescription)

If you were using Yosai with a web application, the syntax would be similar to that above but requires that a WebRegistry instance be passed as as argument to the context manager. The web integration library is further elaborated upon in the Web Integration section of this documentation.

with WebYosai.context(yosai, web_registry):

This is just a README file. Please visit the project web site to get a full overview.


In Japanese, the word Shiro translates to "Castle". Yosai translates to "Fortress". Like the words, the frameworks are similar yet different.

Development Status

Yosai v0.3 was released Nov 24, 2016.

This release includes:

  1. General support for second factor authentication (2FA)
  2. A complete time-based one time password authentication solution (TOTP)
  3. Configurable rate limiting / account locking
  4. Significant refactoring / optimizatio

Please see the release notes for details about that release.

v0.3 test coverage stats (ao 11/24/2016):

Name Stmt Miss Cover
yosai/core/account/ 5 1 80%
yosai/core/authc/ 196 33 83%
yosai/core/authc/ 19 2 89%
yosai/core/authc/ 51 5 90%
yosai/core/authc/ 40 0 100%
yosai/core/authz/ 199 28 86%
yosai/core/concurrency/ 16 4 75%
yosai/core/conf/ 59 7 88%
yosai/core/event/ 28 0 100%
yosai/core/ 40 0 100%
yosai/core/logging/ 35 0 100%
yosai/core/logging/ 5 0 100%
yosai/core/mgt/ 285 5 98%
yosai/core/mgt/ 37 2 95%
yosai/core/realm/ 186 11 94%
yosai/core/serialize/ 14 8 43%
yosai/core/serialize/ 24 0 100%
yosai/core/serialize/serializers/ 53 3 94%
yosai/core/serialize/serializers/ 56 41 27%
yosai/core/serialize/serializers/ 49 29 41%
yosai/core/session/ 547 63 88%
yosai/core/session/ 13 1 92%
yosai/core/subject/ 60 3 95%
yosai/core/subject/ 451 22 95%
yosai/core/utils/ 137 87 36%
yosai/web/ 7 0 100%
yosai/web/mgt/ 74 1 99%
yosai/web/registry/ 5 0 100%
yosai/web/session/ 143 2 99%
yosai/web/subject/ 162 4 98%
--------------------------------------------- ----- ---- ------


Google Groups Mailing List:


Darin Gordon is the author of Yosai


Licensed under the Apache License, Version 2.0 (the "License"); you may not use any portion of Yosai except in compliance with the License. Contributors agree to license their work under the same License. You may obtain a copy of the License at


A Security Framework for Python applications featuring Authorization (rbac permissions and roles), Authentication (2fa totp), Session Management and an extensive Audit Trail




Code of conduct





No packages published