Metadata-Version: 1.1
Name: auth
Version: 0.5.2
Summary: Authorization for humans
Home-page: http://github.com/ourway/auth/
Author: Farsheed Ashouri
Author-email: rodmena@me.com
License: Apache 2.0
Description: ====================================
        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
        
Keywords: authorizarion role auth groups membership ensure ldap
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python :: Implementation :: Jython
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
