{"id":13648307,"url":"https://github.com/YosaiProject/yosai","last_synced_at":"2025-04-22T07:31:08.502Z","repository":{"id":25481624,"uuid":"28912438","full_name":"YosaiProject/yosai","owner":"YosaiProject","description":"A Security Framework for Python applications featuring Authorization (rbac permissions and roles), Authentication (2fa totp), Session Management and an extensive Audit Trail","archived":true,"fork":false,"pushed_at":"2018-07-23T13:41:48.000Z","size":28200,"stargazers_count":590,"open_issues_count":8,"forks_count":52,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-07T14:47:20.942Z","etag":null,"topics":["authentication","authorization","python","rbac","security","sessionmanagement","totp","two-factor","twofactorauth"],"latest_commit_sha":null,"homepage":"http://yosaiproject.github.io/yosai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YosaiProject.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-07T11:52:49.000Z","updated_at":"2025-01-03T09:21:07.000Z","dependencies_parsed_at":"2022-09-13T02:32:31.968Z","dependency_job_id":null,"html_url":"https://github.com/YosaiProject/yosai","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosaiProject%2Fyosai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosaiProject%2Fyosai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosaiProject%2Fyosai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosaiProject%2Fyosai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YosaiProject","download_url":"https://codeload.github.com/YosaiProject/yosai/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250195033,"owners_count":21390230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","python","rbac","security","sessionmanagement","totp","two-factor","twofactorauth"],"created_at":"2024-08-02T01:04:07.936Z","updated_at":"2025-04-22T07:31:07.543Z","avatar_url":"https://github.com/YosaiProject.png","language":"Python","readme":"![yosai_logo](/doc/docs/img/yosai_logo_with_title.png)\n\n\n# A Security Framework for Python Applications\n\n## Project web site:  http://yosaiproject.github.io/yosai\n\n\n# What is Yosai\n\nYosai is a \"security framework\" that features authentication, authorization, and session\nmanagement from a common, intuitive API.\n\n![authc_authz_sess](/doc/docs/img/authc_authz_sess.png)\n\nYosai is based on Apache Shiro, written in Java and widely used today.\n\n\n# Yosai is a Framework\n\n![framework](/doc/docs/img/yosai_framework.png)\n\nIt is a framework that is is designed in such a way that it can be used to secure\na variety of python applications, not just web applications.  This is accomplished\nby completely decoupling security-related services from the rest of an application\nand writing adapters for each specific type of client.\n\n\n# Key Features\n\n- Enables Role-Based Access Control policies through permission-level and role-level\n  access control\n- Two-Factor Authentication, featuring Time-based One-Time Passwords\n- Native Support for Caching and Serialization\n- A Complete Audit Trail of Events\n- Batteries Included:  Extensions Ready for Use\n- \"RunAs\" Administration Tool\n- Event-driven Processing\n- Ready for Web Integration\n\n\n## Python 3 Supported\n\nYosai requires Python 3.4 or newer. There are no plans to support python2\ndue to anticipated optimizations that require newer versions of python.\n\n\n## Installation\n\nFirst, install Yosai from PyPI using pip:\n    ``pip install yosai``\n\nInstalling from PyPI, using pip, will install the project package that includes\n``yosai.core`` and ``yosai.web``, a default configuration, and project dependencies.\n\n\n## Basic Authentication:  UsernamePassword\n```Python\nyosai = Yosai(env_var='YOSAI_SETTINGS')\n\nwith Yosai.context(yosai):\n    current_user = Yosai.get_current_subject()\n\n    authc_token = UsernamePasswordToken(username='thedude',\n                                        credentials='letsgobowling')\n\n    try:\n        current_user.login(authc_token)\n    except AuthenticationException:\n        # insert here\n```\n\n\n## Two-Factor Authentication:  UsernamePassword and TOTP\n\n### 2FA Step 1:  UsernamePassword\n```Python\nyosai = Yosai(env_var='YOSAI_SETTINGS')\n\n\nwith Yosai.context(yosai):\n    current_user = Yosai.get_current_subject()\n\n    userpass_token = UsernamePasswordToken(username='thedude',\n                                        credentials='letsgobowling')\n\n    try:\n        current_user.login(userpass_token)\n    except AdditionalAuthenticationRequired: \n        # communicate a two-factor token request to user         \n    except IncorrectCredentialsException: \n        # user failed to authenticate \n```\n\n\n### 2FA Step 2:  TOTP\n\n```Python\nyosai = Yosai(env_var='YOSAI_SETTINGS')\n\n\nwith Yosai.context(yosai):\n    current_user = Yosai.get_current_subject()\n\n    totp_token = TOTPToken(user_provided_token) \n\n    try:\n        current_user.login(totp_token)\n    except IncorrectCredentialsException: \n        # user failed to authenticate \n\n```\n\n\n## Authorization Example\n\nThe following example was created to illustrate the myriad ways that you\ncan declare an authorization policy in an application, ranging from general\nrole-level specification to very specific \"scoped\" permissions.  The\nauthorization policy for this example is as follows:\n\n- Either a user with role membership \"patient\" or \"nurse\" may request a\n  refill of a medical prescription\n- A user who is granted permission to write prescriptions may obtain the\n  list of pending prescription refill requests\n- A user who is granted permission to write prescriptions for a specific\n  patient may issue a prescription for that patient\n\n```Python\n@Yosai.requires_role(roleid_s=['patient', 'nurse'], logical_operator=any)\ndef request_prescription_refill(patient, prescription):\n    ...\n\n@Yosai.requires_permission(['prescription:write'])\ndef get_prescription_refill_requests(patient):\n    ...\n\n@Yosai.requires_dynamic_permission(['prescription:write:{patient.patient_id}'])\ndef issue_prescription(patient, prescription):\n    ...\n\n```\n\nNote how the authorization policy is declared using yosai's authorization\ndecorators.  These global decorators are associated with the yosai instance\nwhen the yosai instance is used as a context manager.\n\n```Python\n\nwith Yosai.context(yosai):\n    issue_prescription(patient)\n\n    for prescription in get_prescription_refill_requests(patient):\n        issue_prescription(patient, prescription)\n```\n\nIf you were using Yosai with a web application, the syntax would be similar\nto that above but requires that a ``WebRegistry`` instance be passed as\nas argument to the context manager.  The web integration library is further\nelaborated upon in the Web Integration section of this documentation.\n\n```Python\n\nwith WebYosai.context(yosai, web_registry):\n\t...\n```\n\nThis is just a README file.  Please visit [the project web site](http://yosaiproject.github.io/yosai) to get a full overview.\n\n\n# WORD ORIGIN:  Yosai\n\nIn Japanese, the word Shiro translates to \"Castle\".  Yosai translates to \"Fortress\".\nLike the words, the frameworks are similar yet different.\n\n\n# Development Status\n\nYosai v0.3 was released Nov 24, 2016. \n\nThis release includes:\n1) General support for second factor authentication (2FA)\n2) A complete time-based one time password authentication solution (TOTP)\n3) Configurable rate limiting / account locking\n4) Significant refactoring / optimizatio\n\nPlease see the [release notes](https://yosaiproject.github.io/yosai/devstatus/)\nfor details about that release.\n\nv0.3 test coverage stats (ao 11/24/2016):\n\n|Name                                         |Stmt |Miss|Cover |\n|:---------------------------------------------|:-----:|:----:|:------:|\n| yosai/core/account/account.py               | 5   | 1  | 80%  |\n| yosai/core/authc/authc.py                   | 196 | 33 | 83%  |\n| yosai/core/authc/authc_settings.py          | 19  | 2  | 89%  |\n| yosai/core/authc/credential.py              | 51  | 5  | 90%  |\n| yosai/core/authc/strategy.py                | 40  | 0  | 100% |\n| yosai/core/authz/authz.py                   | 199 | 28 | 86%  |\n| yosai/core/concurrency/concurrency.py       | 16  | 4  | 75%  |\n| yosai/core/conf/yosaisettings.py            | 59  | 7  | 88%  |\n| yosai/core/event/event.py                   | 28  | 0  | 100% |\n| yosai/core/exceptions.py                    | 40  | 0  | 100% |\n| yosai/core/logging/formatters.py            | 35  | 0  | 100% |\n| yosai/core/logging/slogging.py              | 5   | 0  | 100% |\n| yosai/core/mgt/mgt.py                       | 285 | 5  | 98%  |\n| yosai/core/mgt/mgt_settings.py              | 37  | 2  | 95%  |\n| yosai/core/realm/realm.py                   | 186 | 11 | 94%  |\n| yosai/core/serialize/marshalling.py         | 14  | 8  | 43%  |\n| yosai/core/serialize/serialize.py           | 24  | 0  | 100% |\n| yosai/core/serialize/serializers/cbor.py    | 53  | 3  | 94%  |\n| yosai/core/serialize/serializers/json.py    | 56  | 41 | 27%  |\n| yosai/core/serialize/serializers/msgpack.py | 49  | 29 | 41%  |\n| yosai/core/session/session.py               | 547 | 63 | 88%  |\n| yosai/core/session/session_settings.py      | 13  | 1  | 92%  |\n| yosai/core/subject/identifier.py            | 60  | 3  | 95%  |\n| yosai/core/subject/subject.py               | 451 | 22 | 95%  |\n| yosai/core/utils/utils.py                   | 137 | 87 | 36%  |\n| yosai/web/exceptions.py                     | 7   | 0  | 100% |\n| yosai/web/mgt/mgt.py                        | 74  | 1  | 99%  |\n| yosai/web/registry/registry_settings.py     | 5   | 0  | 100% |\n| yosai/web/session/session.py                | 143 | 2  | 99%  |\n| yosai/web/subject/subject.py                | 162 | 4  | 98%  |\n|---------------------------------------------|-----|----|------|\n\n# GROUP COMMUNICATION\nGoogle Groups Mailing List:  https://groups.google.com/d/forum/yosai\n\n\n# CONTACT INFORMATION\nDarin Gordon is the author of Yosai  http://www.daringordon.com\n\n\n# LICENSE\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not\nuse any portion of Yosai except in compliance with the License.\nContributors agree to license their work under the same License.\nYou may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYosaiProject%2Fyosai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYosaiProject%2Fyosai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYosaiProject%2Fyosai/lists"}