Implement authentication.

[campb303]

webqueue2 does not have any form of authentication at this time. The original webqueue had HTTP protocol level authentication at the browser level that looks like this:

This type of authentication cannot be accessed by screen readers or password managers. To address this, one of two options should be chosen and moved forward with:

• Application level authentication like most web apps have with a login form or
• Purdue CAS aka BoilerKey for a unified interface and two factor authentication

[campb303]

After the first webqueue2 demo, Dave expressed interest in moving forward with CAS due to a need for two factor authentication. This should be followed up on.

[benf]

https://www.purdue.edu/securepurdue/identity-access/authentication-options.php

SAML and CAS both support BoilerKey.

[campb303]

Initial research suggests that using ITaP's SAML interface to BoilerKey may be the easiest method of two factor authentication. More experimentation is needed. Direct ActiveDirectory authentication is also an option. I need to ask @seth what he uses to interact with ActiveDirectory to see how that works under the hood.

[campb303]

@seth Authenticates against BoilerAD directly at boilerad.purdue.edu

[campb303]

For our beta release we need authentication. For the short term this can be acheived by authenticating with a shared username and password and authorizing with JWTs. Later implementations of authentication will be 2FA via SAML or BoilerKey.

The authentication/authorization workflow should work as follows:

1. The user visits the site for the first time and enters the shared username and password.
2. The login form hashes the password using SHA 256, never storing the plain text password.
3. The login form sends the username and hashed password to the API.

{
  "username": form.username,
  "password": sha256(form.password)
}

4. The API receives the username and hashed password. The hashed password is combined with a salt then rehashed using SHA 256.

username = request.json.username
password = sha256(request.json.password + salt)

5. If the hash received matches the hash stored, the API issues a new JWT for the user and sends it back to the client.
6. The client stores the JWT in a cookie. When subsequent requests are made, the JWT is also sent.
7. The API attempts to decrypt the JWT. If the token is decoded and has not expired, the user is presumed valid and the request is served.
8. When the client wishes to logout, the JWT is removed from cookies.

---

To achieve these the following things need to happen in this order:

Implment .env File Support In The API

JWTs require a secret key for encryption. This should not be stored in version control. Instead, the JWT secret key and other sensitive values can be stored in .env files that are ignored by version control.

dotenv is a Python package that will load entries from .env files into the os.environ namespace. These variables can then be got and set with os.environ.get(key) and os.environ[key] = value respectively.

Implement JWT support in the API

We are currently using Flask and FlaskRESTful to create our API.

Within this environment we can add JWT support via a low level library like pyjwt and use an authentication decorator as shown in this YouTube video.

Important: This videos suggests storing the JWT private key directly in source code. This is insecure as it would expose the key via version control. The key should be stored in an environment variable file outside of version control with separate keys for development and production.

The generated JWT is sent back to the client as dictionary with a key of token and a value of the JWT:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }

Flask specific JWT libraries could be considered such as Flask JWT Extended or Flask-Praetorian.

Note: This article suggests that there are to be two types of tokens:

• Access Token: used for short term resource authorization and stored in memory for the running application.
• Refresh Token: use for long term ability to get more access tokens and stored in a cookie with flags httpOnly, secure, and SameSite=strict set.

At this time, it appears that a short term access token alone will be sufficent but refresh tokens should be implemented at a later date.

Build A Login Page

We are currently using react-router to control which items get displayed in the frontend. There are plans to implement cookie based queue storage using react-cookie.

With JWT support in the API, we can retrieve a JWT by sending a valid username and SHA 256 password. This can be acheived by a controlled login form sending the authentication data then storing the JWT in a cookie. Its important that the cookie path be set to root / so that the JWT is sent back to server on every request.

Make react-router Authentication Aware

We are currently using react-router to control which items get displayed in the frontend.

react-router needs to be made aware of authentication so that the following things happen:

• If a user does not have an unexpired JWT, redirect to the login page.
• If a user logs outs, they'll be redirected to the login page.
• If a use has left their page open past their JWT expiration date, redirect to the login page on next page load.

This can be acheived by:

• Creating a custom PrivateRoute component extending react-router's Route to manage authentication status.
• Create a custom context manager and hooks to make authentication data available without prop drilling.

Bother of these are dicussed in this article.

[campb303]

Support for .env files has been added to the API through the dotenv package. This is how it works:

Getting and (temporarily) setting environment variables during runtime is already available within Python scrips via the os library's environ submodule like this:

import os

# Get the USER environment variable
print( os.environ.get("USER") ) # campb303

# Set the LOL_BUTTS environment variable to nyan-cat
# Setting this variable does not persist outside of this script
os.environ["LOL_BUTTS"] = "nyan-cat"
print( os.environ.get("LOL_BUTTS") ) # nyan-cat

To set and load out own environment variables, we can create a file (typically named .env) in the same directory with key value pairs then, in out script, import the dotenv module and run its load_dotenv() function.

# ./.env
LOL_BUTTS=nyan-cat
test=123

# ./script.py
import os, dotenv

# Load environment variables from .env
dotenv.load_dotenv()

# Get the LOL_BUTTS environment variable
print( os.environ.get("LOL_BUTTS") ) # nyan-cat

# Get the test environment variable
print( os.environ.get("test") ) # 123

dotenv's load_dotenv() function can be customized as detailed on the project's GitHub page. For our purposes, the default behavior should suffice.

Any part of out Python codebase can utilize .env files by importing the dotenv module and running its load_dotenv() function.

[campb303]

FUll JWT support has been added to the API. There are two types of tokens:

• Access Tokens: valid for 15 minutes and used to send and received data to and from the API.
• Refresh Tokens: valid for 30 days and used to get new access tokens.

JWT usage depends on the API endpoint. There are four types of API endpoints:

• Public: These endpoints are not authenticated and can be accessed by anyone.
  Example: /login
• Access Token Restricted: These endpoints require a non-expired access token to be present. Refresh tokens will not be accepted.
  Example: /api/get_queues
• Refresh Token Restricted: These endpoints require a non-expired refresh token to be present. Access tokens will not be accepted.
  Example: /tokens/refresh

Interacting with the API using a JWT based workflow would work like this:

First Time Login (Authentication):

Send a POST request to the /login endpoint with a JSON body containing a username and password:

fetch(
    "/login", 
    {
        method: "POST", 
        headers: { 'Content-Type': 'application/json'},
        body: '{
            "username": username, 
            "password": password
        }'
    }
);

The API will validate the username and password then return an access token in the body of the response.

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MDQ3Nzk2MDUsIm5iZiI6MTYwNDc3OTYwNSwianRpIjoiY2EzMWMxMzAtNDU5OC00MTBkLThhNzEtM2JmMzhkODc5OTljIiwiZXhwIjoxNjA0NzgwNTA1LCJzdWIiOiJ3cTJCZXRhIiwiZnJlc2giOmZhbHNlLCJ0eXBlIjoiYWNjZXNzIiwiY3NyZiI6IjYzZTBjOWI3LTY5NzgtNDIwMy1iMjVmLTNhMTIzNWU3YzAzMSJ9.RsuZe0C8CMZvNlcLHRptWXwmj0RGNhW6YYylNbRMjco"
}

The API will also attach two cookies to the response:

• refresh_token_cookie: containing the refresh token used to get new access tokens. This is a HttpOnly cookie meaning the client cannot read it but the API will receive it on subsequent requests.
• csrf_refresh_token: containing a validation string used to confirm the refresh token. This must be manually sent back to the API as a header named 'X-CSRF-TOKEN` when getting new refresh tokens.

Refreshing Access Tokens

After the first login, new access tokens should be retrieved before the old access token expires to avoid errors.

Send a POST request to the /tokens/refresh endpoint with a header named X-CSRF-TOKEN containing the value of the csrf_refresh_token cookie:

fetch(
    "/tokens/refresh", 
    {
        method: "POST", 
        headers: {"X-CSRF-TOKEN": "8a32d817-8f77-42d1-94f2-e6876cb436a4"}
    }
);

The API will validate the refresh token with the CSRF string and return a new access token:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MDQ3Nzk2MDUsIm5iZiI6MTYwNDc3OTYwNSwianRpIjoiY2EzMWMxMzAtNDU5OC00MTBkLThhNzEtM2JmMzhkODc5OTljIiwiZXhwIjoxNjA0NzgwNTA1LCJzdWIiOiJ3cTJCZXRhIiwiZnJlc2giOmZhbHNlLCJ0eXBlIjoiYWNjZXNzIiwiY3NyZiI6IjYzZTBjOWI3LTY5NzgtNDIwMy1iMjVmLTNhMTIzNWU3YzAzMSJ9.RsuZe0C8CMZvNlcLHRptWXwmj0RGNhW6YYylNbRMjco"
}

Access Token Usage (Authorization)

When interacting with access token restricted endpoints, a unexpired access token must be sent in an authorization header:

fetch(
    "/ce/100", 
    {
        method: "POST", 
        headers: {"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MDQ3Nzk2MDUsIm5iZiI6MTYwNDc3OTYwNSwianRpIjoiY2EzMWMxMzAtNDU5OC00MTBkLThhNzEtM2JmMzhkODc5OTljIiwiZXhwIjoxNjA0NzgwNTA1LCJzdWIiOiJ3cTJCZXRhIiwiZnJlc2giOmZhbHNlLCJ0eXBlIjoiYWNjZXNzIiwiY3NyZiI6IjYzZTBjOWI3LTY5NzgtNDIwMy1iMjVmLTNhMTIzNWU3YzAzMSJ9.RsuZe0C8CMZvNlcLHRptWXwmj0RGNhW6YYylNbRMjco"}
    }
);

The API will validate the access token and respond with the requested data:

{
    "queue": "ce",
    "number": 100,
    "lastUpdated": "2020-09-28T13:26:00-0400",
    "headers": [ ],
    "content": [ ],
    "isLocked": "ce 100 is locked by knewell using qvi",
    "userEmail": "campb303@purdue.edu",
    "userName": "Justin Campbell",
    "userAlias": "campb303",
    "assignedTo": "campb303",
    "subject": "Beepboop",
    "status": "Dont Delete",
    "priority": "",
    "department": "",
    "building": "",
    "dateReceived": "2020-06-23T13:25:51-0400"
}

Renewing Refresh Tokens

When a refresh token expires, another login must happen.

[campb303]

Using authentication within the frontend use state variables require extraneous prop drilling (passing state variables through intermediate components for access down the tree) and would become brittle for refactoring with every prop reference needing to be changed. A better way to manage this would be with a React Context.

React Context allows data to be arbitrarily passed through a component tree without prop drilling. Contexts are made of three pieces:

• A Provider component that wraps a subtree, making the values passed to it available.
• A Consumer component that can exist anywhere in a wrapped subtree to access the provider values.
• The useContext() hook that accesses the values provided by a Provider insider of a Consumer.

Making use of a context requires three steps:

1. Create and place a Provider
2. Create and place a Consumer
3. Reference the provided data in a consumer with useContext

(Codevolution on YouTube has a three part video series that visualizes the use of a context well. See Part 1, Part 2 and Part 3)

Example:

import React, { createContext, useContext } from "react";

export default function App(){
    // Create a context
    const AuthContext = createContext();

    // Create components for component tree
    const CompA = _ => "CompA";
    const CompB = _ => "CompB";
    const CompC = _ => "CompC";

    return (
        // Use the AuthContext provider with a `true` value to represent a user being logged in
        <AuthContext.Provider value={true}>
            <CompA>
                <CompB>
                    <CompC>
                        // Use the AuthContext consumer to reference the value
                        <AuthContext.Consumer>
                            {
                                // To use the value inside a provider we must use render prop style rendering
                               // See: https://reactjs.org/docs/render-props.html
                                (value) => {
                                    const isLoggedIn = value;
                                    isLoggedIn
                                        ? <AdminArea />
                                        : <Login />
                                }
                            }
                        </AuthContext.Consumer>
                    </CompC>
                </CompB>
            </CompA>
        </AuthContext.Provider>
    );
}

In the example above we created an AuthContext and used its Provider to pass a value down a component tree to be used inside its consumer. As this article points out there are ways to make this more convenient allow for complicated logic to be controlled by the context. Using suggestions from this article, we can create helper components from the context Provider and Consumer as well as utilize custom hooks that wrap useContext() to create a more performant solution with easier granular access all without prop drilling.

This is the method we'll use for managing authentication in the frontend.

[campb303]

A timed event to refresh the access token needs to be implemented.