====================================
Auth | Authorization for Humans
====================================
RESTful, Simple Authorization system with ZERO configuration.
.. image:: https://badge.fury.io/py/auth.svg
:target: https://badge.fury.io/py/auth
.. image:: https://img.shields.io/pypi/dm/auth.svg
:target: https://pypi.python.org/pypi/auth
.. image:: https://api.travis-ci.org/ourway/auth.svg
:target: https://travis-ci.org/ourway/auth
.. image:: https://codecov.io/github/ourway/auth/coverage.svg?branch=master
:target: https://codecov.io/github/ourway/auth?branch=master
***************
What is Auth?
***************
Auth is a module that makes authorization simple and also scalable and powerful. It also has a beautiful RESTful API for use in micro-service architectures and platforms. It is originally desinged to use in Appido, a scalable media market in Iran.
It supports Python2.6+ and if you have a mongodb backbone, you need ZERO configurations steps. Just type ``auth-server`` and press enter!
I use Travis and Codecov to keep myself honest.
*******************
requirements
*******************
You need to access to **mongodb**. If you are using a remote mongodb, provide these environment variables:
``MONGO_HOST`` and ``MONGO_PORT``
*******************
Installation
*******************
.. code:: Bash
pip install auth
*******************
Show me an example
*******************
ok, lets image you have two users, **Jack** and **Sara**. Sara can cook and Jack can dance. Both can laugh.
You also need to choose a secret key for your application. Because you may want to use Auth in various tools and each must have a secret key for seperating their scope.
.. code:: Python
my_secret_key = "pleaSeDoN0tKillMyC_at"
from auth import Authorization
cas = Authorization(my_secret_key)
Now, Lets add 3 groups, Cookers, Dancers and Laughers. Remember that groups are Roles. So when we create a group, indeed we create a role:
.. code:: Python
cas.add_group('cookers')
cas.add_group('dancers')
cas.add_group('laughers')
Ok, great. You have 3 groups and you need to authorize them to do special things.
.. code:: Python
cas.add_permission('cookers', 'cook')
cas.add_permission('dancers', 'dance')
cas.add_permission('laughers', 'laugh')
Good. You let cookers to cook and dancers to dance etc...
The final part is to set memberships for Sara and Jack:
.. code:: Python
cas.add_membership('sara', 'cookers')
cas.add_membership('sara', 'laughers')
cas.add_membership('jack', 'dancers')
cas.add_membership('jack', 'laughers')
That's all we need. Now lets ensure that jack can dance:
.. code:: Python
if cas.user_has_permission('jack', 'dance'):
print('YES!!! Jack can dance.')
**********************
Authirization Methods
**********************
use pydoc to see all methods:
.. code:: Bash
pydoc auth.Authorization
*******************
RESTful API
*******************
Lets run the server on port 4000:
.. code:: Python
from auth import api, serve
serve('localhost', 4000, api)
Or, from version 0.1.2+ you can use this command:
.. code:: Bash
auth-server
Simple! Authorization server is ready to use.
.. image:: https://raw.githubusercontent.com/ourway/auth/master/docs/API_Usage_Teminal.gif
You can use it via simple curl or using mighty Requests module. So in you remote application, you can do something like this:
.. code:: Python
import requests
secret_key = "pleaSeDoN0tKillMyC_at"
auth_api = "http://127.0.0.1:4000/api"
Lets create admin group:
.. code:: Python
requests.post(auth_api+'/role/'+secret_key+'/admin')
And lets make Jack an admin:
.. code:: Python
requests.post(auth_api+'/permission/'+secret_key+'/jack/admin')
And finally let's check if Sara still can cook:
.. code:: Python
requests.get(auth_api+'/has_permission/'+secret_key+'/sara/cook')
********************
RESTful API helpers
********************
auth comes with a helper class that makes your life easy.
.. code:: Python
from auth.client import Client
service = Client('srv201', 'http://192.168.99.100:4000')
print(service)
service.get_roles()
service.add_role(role='admin')
*******************
API Methods
*******************
.. code:: Bash
pydoc auth.CAS.REST.service
- ``/ping`` [GET]
Ping API, useful for your monitoring tools
- ``/api/membership/{KEY}/{user}/{role}`` [GET/POST/DELETE]
Adding, removing and getting membership information.
- ``/api/permission/{KEY}/{role}/{name}`` [GET/POST/DELETE]
Adding, removing and getting permissions
- ``/api/has_permission/{KEY}/{user}/{name}`` [GET]
Getting user permission info
- ``/api/role/{KEY}/{role}`` [GET/POST/DELETE]
Adding, removing and getting roles
- ``/api/which_roles_can/{KEY}/{name}`` [GET]
For example: Which roles can send_mail?
- ``/api/which_users_can/{KEY}/{name}`` [GET]
For example: Which users can send_mail?
- ``/api/user_permissions/{KEY}/{user}`` [GET]
Get all permissions that a user has
- ``/api/role_permissions/{KEY}/{role}`` [GET]
Get all permissions that a role has
- ``/api/user_roles/{KEY}/{user}`` [GET]
Get roles that user assinged to
- ``/api/roles/{KEY}`` [GET]
Get all available roles
*******************
Deployment
*******************
Deploying Auth module in production environment is easy:
.. code:: Bash
gunicorn auth:api
*******************
Dockerizing
*******************
It's simple:
.. code:: Bash
docker build -t python/auth-server https://raw.githubusercontent.com/ourway/auth/master/Dockerfile
docker run --name=auth -e MONGO_HOST='192.168.99.100' -p 4000:4000 -d --restart=always --link=mongodb-server python/auth-server
*******************
Copyright
*******************
- Farsheed Ashouri `@ <mailto:rodmena@me.com>`_
*******************
Documentation
*******************
Feel free to dig into source code. If you think you can improve the documentation, please do so and send me a pull request.
************************
Unit Tests and Coverage
************************
I am trying to add tests as much as I can, but still there are areas that need improvement.
**********
To DO
**********
- Add Authentication features
- Improve Code Coverage
Raw data
{
"_id": null,
"home_page": "http://github.com/ourway/auth/",
"name": "auth",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "authorizarion role auth groups membership ensure ldap",
"author": "Farsheed Ashouri",
"author_email": "rodmena@me.com",
"download_url": "https://files.pythonhosted.org/packages/4a/fd/ecd7f79f549a734a7fa904e42251c7169d080f960961b823d76726936efb/auth-0.5.3.tar.gz",
"platform": "UNKNOWN",
"description": "====================================\nAuth | Authorization for Humans\n====================================\n\nRESTful, Simple Authorization system with ZERO configuration.\n\n.. image:: https://badge.fury.io/py/auth.svg\n :target: https://badge.fury.io/py/auth\n\n.. image:: https://img.shields.io/pypi/dm/auth.svg\n :target: https://pypi.python.org/pypi/auth\n\n\n\n\n.. image:: https://api.travis-ci.org/ourway/auth.svg\n :target: https://travis-ci.org/ourway/auth\n\n.. image:: https://codecov.io/github/ourway/auth/coverage.svg?branch=master\n :target: https://codecov.io/github/ourway/auth?branch=master\n\n\n\n\n***************\nWhat is Auth?\n***************\nAuth is a module that makes authorization simple and also scalable and powerful. It also has a beautiful RESTful API for use in micro-service architectures and platforms. It is originally desinged to use in Appido, a scalable media market in Iran.\n\nIt supports Python2.6+ and if you have a mongodb backbone, you need ZERO configurations steps. Just type ``auth-server`` and press enter!\n\nI use Travis and Codecov to keep myself honest.\n\n*******************\nrequirements\n*******************\n\nYou need to access to **mongodb**. If you are using a remote mongodb, provide these environment variables:\n\n``MONGO_HOST`` and ``MONGO_PORT``\n\n\n*******************\nInstallation\n*******************\n\n.. code:: Bash\n\n pip install auth\n\n\n*******************\nShow me an example\n*******************\nok, lets image you have two users, **Jack** and **Sara**. Sara can cook and Jack can dance. Both can laugh.\n\nYou also need to choose a secret key for your application. Because you may want to use Auth in various tools and each must have a secret key for seperating their scope.\n\n.. code:: Python\n\n my_secret_key = \"pleaSeDoN0tKillMyC_at\"\n from auth import Authorization\n cas = Authorization(my_secret_key)\n\nNow, Lets add 3 groups, Cookers, Dancers and Laughers. Remember that groups are Roles. So when we create a group, indeed we create a role:\n\n.. code:: Python\n\n cas.add_group('cookers')\n cas.add_group('dancers')\n cas.add_group('laughers')\n\n\nOk, great. You have 3 groups and you need to authorize them to do special things.\n\n.. code:: Python\n\n cas.add_permission('cookers', 'cook')\n cas.add_permission('dancers', 'dance')\n cas.add_permission('laughers', 'laugh')\n\n\nGood. You let cookers to cook and dancers to dance etc...\nThe final part is to set memberships for Sara and Jack:\n\n.. code:: Python\n\n cas.add_membership('sara', 'cookers')\n cas.add_membership('sara', 'laughers')\n cas.add_membership('jack', 'dancers')\n cas.add_membership('jack', 'laughers')\n\n\n\nThat's all we need. Now lets ensure that jack can dance:\n\n.. code:: Python\n\n if cas.user_has_permission('jack', 'dance'):\n print('YES!!! Jack can dance.')\n\n\n\n**********************\nAuthirization Methods\n**********************\n\nuse pydoc to see all methods:\n\n.. code:: Bash\n\n pydoc auth.Authorization\n\n\n*******************\nRESTful API\n*******************\nLets run the server on port 4000:\n\n.. code:: Python\n\n from auth import api, serve\n serve('localhost', 4000, api)\n\nOr, from version 0.1.2+ you can use this command:\n\n.. code:: Bash\n\n auth-server\n\n\nSimple! Authorization server is ready to use.\n\n.. image:: https://raw.githubusercontent.com/ourway/auth/master/docs/API_Usage_Teminal.gif\n\n\nYou can use it via simple curl or using mighty Requests module. So in you remote application, you can do something like this:\n\n.. code:: Python\n\n import requests\n secret_key = \"pleaSeDoN0tKillMyC_at\"\n auth_api = \"http://127.0.0.1:4000/api\"\n\n\nLets create admin group:\n\n.. code:: Python\n\n requests.post(auth_api+'/role/'+secret_key+'/admin')\n\n\nAnd lets make Jack an admin:\n\n.. code:: Python\n\n requests.post(auth_api+'/permission/'+secret_key+'/jack/admin')\n\nAnd finally let's check if Sara still can cook:\n\n.. code:: Python\n\n requests.get(auth_api+'/has_permission/'+secret_key+'/sara/cook')\n\n\n\n********************\nRESTful API helpers\n********************\nauth comes with a helper class that makes your life easy.\n\n.. code:: Python\n\n from auth.client import Client\n service = Client('srv201', 'http://192.168.99.100:4000')\n print(service)\n service.get_roles()\n service.add_role(role='admin')\n\n\n*******************\nAPI Methods\n*******************\n\n\n.. code:: Bash\n\n pydoc auth.CAS.REST.service\n\n\n\n\n- ``/ping`` [GET]\n\n\n Ping API, useful for your monitoring tools\n\n\n- ``/api/membership/{KEY}/{user}/{role}`` [GET/POST/DELETE]\n\n Adding, removing and getting membership information.\n\n\n- ``/api/permission/{KEY}/{role}/{name}`` [GET/POST/DELETE]\n\n Adding, removing and getting permissions\n\n\n- ``/api/has_permission/{KEY}/{user}/{name}`` [GET]\n\n Getting user permission info\n\n\n- ``/api/role/{KEY}/{role}`` [GET/POST/DELETE]\n\n Adding, removing and getting roles\n\n\n- ``/api/which_roles_can/{KEY}/{name}`` [GET]\n\n For example: Which roles can send_mail?\n\n\n- ``/api/which_users_can/{KEY}/{name}`` [GET]\n\n For example: Which users can send_mail?\n\n\n- ``/api/user_permissions/{KEY}/{user}`` [GET]\n\n Get all permissions that a user has\n\n- ``/api/role_permissions/{KEY}/{role}`` [GET]\n\n Get all permissions that a role has\n\n\n- ``/api/user_roles/{KEY}/{user}`` [GET]\n\n Get roles that user assinged to\n\n- ``/api/roles/{KEY}`` [GET]\n\n Get all available roles\n\n\n*******************\nDeployment\n*******************\n\nDeploying Auth module in production environment is easy:\n\n\n.. code:: Bash\n\n gunicorn auth:api\n\n\n\n\n*******************\nDockerizing\n*******************\n\nIt's simple:\n\n.. code:: Bash\n\n docker build -t python/auth-server https://raw.githubusercontent.com/ourway/auth/master/Dockerfile\n docker run --name=auth -e MONGO_HOST='192.168.99.100' -p 4000:4000 -d --restart=always --link=mongodb-server python/auth-server\n\n\n\n*******************\nCopyright\n*******************\n\n- Farsheed Ashouri `@ <mailto:rodmena@me.com>`_\n\n\n*******************\nDocumentation\n*******************\nFeel free to dig into source code. If you think you can improve the documentation, please do so and send me a pull request.\n\n************************\nUnit Tests and Coverage\n************************\nI am trying to add tests as much as I can, but still there are areas that need improvement.\n\n\n**********\nTo DO\n**********\n- Add Authentication features\n- Improve Code Coverage",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Authorization for humans",
"version": "0.5.3",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "http://github.com/ourway/auth/"
},
"split_keywords": [
"authorizarion",
"role",
"auth",
"groups",
"membership",
"ensure",
"ldap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c6ec4c30e831f53a81930be7996a4384db3cab5bb2155906c8429d68aea29bb0",
"md5": "3d190312d0602015fd059b23b9f7aac3",
"sha256": "da6af75ceb503964c5003c2f22a49ac8334e2f1b01941b6cfe6871024654c905"
},
"downloads": -1,
"filename": "auth-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d190312d0602015fd059b23b9f7aac3",
"packagetype": "bdist_wheel",
"python_version": "3.5",
"requires_python": null,
"size": 14009,
"upload_time": "2016-05-24T21:54:43",
"upload_time_iso_8601": "2016-05-24T21:54:43.260890Z",
"url": "https://files.pythonhosted.org/packages/c6/ec/4c30e831f53a81930be7996a4384db3cab5bb2155906c8429d68aea29bb0/auth-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4afdecd7f79f549a734a7fa904e42251c7169d080f960961b823d76726936efb",
"md5": "32e74611933f6a264c72b7e1bed2e99e",
"sha256": "fbb863640f3070356b833914d9bf12a3d74012e5bb132bc84aa51e41052ace3f"
},
"downloads": -1,
"filename": "auth-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "32e74611933f6a264c72b7e1bed2e99e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9266,
"upload_time": "2016-05-24T21:54:27",
"upload_time_iso_8601": "2016-05-24T21:54:27.566834Z",
"url": "https://files.pythonhosted.org/packages/4a/fd/ecd7f79f549a734a7fa904e42251c7169d080f960961b823d76726936efb/auth-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2016-05-24 21:54:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ourway",
"github_project": "auth",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "auth"
}
JSON
