



  

auth stable documentation

 [auth](index.html#document-index) 

 stable

 

[auth](index.html#document-index)

* [Docs](index.html#document-index) »

* auth stable documentation

* [Edit on GitHub](https://github.com/ourway/auth/blob/f676ac54dd11dbd5468c41d7d9f7d925a784acdf/docs/index.rst)

---

Auth | Authorization for Humans[¶](#auth-authorization-for-humans "Permalink to this headline")

===============================================================================================

RESTful, Simple Authorization system with ZERO configuration.

[![https://badge.fury.io/py/auth.svg](https://badge.fury.io/py/auth.svg)](https://badge.fury.io/py/auth)

[![https://img.shields.io/pypi/dm/auth.svg](https://img.shields.io/pypi/dm/auth.svg)](https://pypi.python.org/pypi/auth)

[![https://api.travis-ci.org/ourway/auth.svg](https://api.travis-ci.org/ourway/auth.svg)](https://travis-ci.org/ourway/auth)

[![https://codecov.io/github/ourway/auth/coverage.svg?branch=master](https://codecov.io/github/ourway/auth/coverage.svg?branch=master)](https://codecov.io/github/ourway/auth?branch=master)

What is Auth?[¶](#what-is-auth "Permalink to this headline")

------------------------------------------------------------

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[¶](#requirements "Permalink to this headline")

-----------------------------------------------------------

You need to access to **mongodb**. If you are using a remote mongodb, provide these environment variables:

`MONGO\_HOST` and `MONGO\_PORT`

Installation[¶](#installation "Permalink to this headline")

-----------------------------------------------------------

```

pip install auth

```

Show me an example[¶](#show-me-an-example "Permalink to this headline")

-----------------------------------------------------------------------

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.

```

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:

```

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.

```

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:

```

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:

```

if cas.user\_has\_permission('jack', 'dance'):

    print('YES!!! Jack can dance.')

```

Authirization Methods[¶](#authirization-methods "Permalink to this headline")

-----------------------------------------------------------------------------

use pydoc to see all methods:

```

pydoc auth.Authorization

```

RESTful API[¶](#restful-api "Permalink to this headline")

---------------------------------------------------------

Lets run the server on port 4000:

```

from auth import api, serve

serve('localhost', 4000, api)

```

Or, from version 0.1.2+ you can use this command:

```

auth-server

```

Simple! Authorization server is ready to use.

![https://raw.githubusercontent.com/ourway/auth/master/docs/API_Usage_Teminal.gif](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:

```

import requests

secret\_key = "pleaSeDoN0tKillMyC\_at"

auth\_api = "http://127.0.0.1:4000/api"

```

Lets create admin group:

```

requests.post(auth\_api+'/role/'+secret\_key+'/admin')

```

And lets make Jack an admin:

```

requests.post(auth\_api+'/permission/'+secret\_key+'/jack/admin')

```

And finally let’s check if Sara still can cook:

```

requests.get(auth\_api+'/has\_permission/'+secret\_key+'/sara/cook')

```

RESTful API helpers[¶](#restful-api-helpers "Permalink to this headline")

-------------------------------------------------------------------------

auth comes with a helper class that makes your life easy.

```

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[¶](#api-methods "Permalink to this headline")

---------------------------------------------------------

```

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[¶](#deployment "Permalink to this headline")

-------------------------------------------------------

Deploying Auth module in production environment is easy:

```

gunicorn auth:api

```

Dockerizing[¶](#dockerizing "Permalink to this headline")

---------------------------------------------------------

It’s simple:

```

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[¶](#copyright "Permalink to this headline")

-----------------------------------------------------

* Farsheed Ashouri [@](mailto:rodmena%40me.com)

Documentation[¶](#documentation "Permalink to this headline")

-------------------------------------------------------------

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[¶](#unit-tests-and-coverage "Permalink to this headline")

---------------------------------------------------------------------------------

I am trying to add tests as much as I can, but still there are areas that need improvement.

To DO[¶](#to-do "Permalink to this headline")

---------------------------------------------

* Add Authentication features

* Improve Code Coverage

