theMagicalKarp/uptown-prototype — pull request #2 by theMagicalKarp (2014-02-26 04:05:58+00:00)
Title: Authentication Integration

Authentication
=========
Overview
-----------
Wrote some new changes to allow for authentication on our prototype. This meant creating a new user model, writing some authentication methods, and adding more url routing to new views as well as writing some new html pages. These changes utilize an added flask plugin known as [flask-login](https://flask-login.readthedocs.org/en/latest/). This plugin makes it very easy to handle user authentication and stores session data in encrypted cookies for us.

A running example of this code can be found [here](http://2.uptown-prototype.appspot.com). However I have no way of providing you guys with your registration urls unless requested directly.

One thing remaining is to set up a way to email new users their registration urls so they can set up their accounts created by admins.

This branch also must be merged into [lib-update](https://github.com/theMagicalKarp/uptown-prototype/pull/1), containing all the updates to the libraries, before it's merged into master.

User model
-----------
| Property | Type | Definition |
| ------------- | ------------- | ----- |
| email | String | Email of user. |
| password | String | A hashed string thats constructed from the ```SECRET_KEY``` with the users hash code and plain text password. For example... ```hashlib.sha512(password+hash_code+SECRTE_KEY).hexdigest()``` This helps keeps user's passwords secure and unreadable to others. |
| role | String | The role that user holds on the web app. Roles including but not limited to are "admin" and "base-user-role". These roles help decided what web pages are accessible to that user. |
| hash_code | String | One of the keys used to construct the hashed form of users password. |
| registration_id | String | The id that references a user when they are registering. That way we can have registration urls. |
| is_registered | Boolean | Tells whether or not the user has completed registering their account. This helps block users from account actions until they have taken the proper steps for setting up their account. |

Authentication Methods
-----------
```python
def hash_password(password, hash_code=None):
```
Handles the hashing of user passwords. If no hash_code is provided one is randomly generated using
```uuid.uuid4().hex``` and returned so the hash_code can be stored and used again.

```python
def create_user(email, role):
```
Creates a user model and stores them in the database. This creates the user with their email and role while setting up their registration id in the background. If a user with the same email already exists this functions terminates and returns the preexisting user model. This model is completely useless until the user has registered a password through the registration page. They can access their registration page with their registration url that contains their registration id.

```python
def register(registration_id, password):
```
This hashes the user's password and stores it in the user model as well as sets ```is_registered``` to true.

```python
def login(email, password):
```
Get's the user's model by their email address and checks if the entered password, when hashed with the ```SECRET_KEY``` and the users ```hash_code```, equals the stored hash password. If it does we login the user with the flask-login library. The flask-login library handles the rest for us so no worries.

```python
def logout():
```
Logs the current user out.

Authentication Views
-----------
| Name | Methods | URL | Definition |
| ------------- | ------------- | -------- |-----------------|
| admin | ```GET``` | ```/admin``` | The admin page allows for administrators to add and monitor users in the application. |
| register | ```POST, GET``` | ```/auth/register/``` | This page prompts the user to enter a password to assign to their new account. Their form submission is then posted back to this url and processed. |
| login | ```POST, GET``` | ```/auth/login``` | This page prompts the user to enter their email and password. Their form submission is then posted back to this url and processed so the user may log in. |
| logout | ```GET``` | ```/auth/logout``` | This logs out the current user and redirects them to the home page. |