pyjwt-wrapper 0.6.0

An easy to use wrapper around PyJWT for authentication and authorization.

An easy to use wrapper around PyJWT for authentication and authorization.

• Why this may be useful
• Quick Start
  • Installation
  • Implement your own BackEndAuthenticator
  • Authenticating a user that supplies a username and password
  • Authorize an API request using the access_token from Authentication
  • Important Parameters
    • Using the password salt
    • Using the JWT secret
  • Using the Refresh Token
• Implementation
  • Authentication
  • The JSON Web Token (generated from pyjwt_wrapper.authentication)
    • Access Token
    • User Token
  • Authorization (as implemented by from pyjwt_wrapper.authorization)
  • Logging
• Testing from Source
• To Do

Note: The development is still in an early stage, and therefore documentation should improve over time. Right now, only some basic concepts are covered.

Why this may be useful

PyJWT is a really solid library and a very useful tool for creating and using JSON Web tokens (JWT) in applications. Check out https://jwt.io/ for more info around JSON Web Tokens.

This library is a wrapper around PyJWT that creates a standard access token and user token.

Note: Refresh tokens to come soon...

Quick Start

Installation

pip install pyjwt-wrapper

PyPi page: https://pypi.org/project/pyjwt-wrapper/

Implement your own BackEndAuthenticator

Below is a quick example of how you would implement your own password based authentication. In stead of users being in a dictionary, you would typically connect to a database.

Note: The example below assumes the password is encoded using SHA256. However, when a user enters a password, we will receive it in normal text format which means it also needs to be SHA256 converted in order to compare to the password on record.

You would typically implement in this code in the application/API that handles authentication.

from pyjwt_wrapper import Logger, BackEndAuthenticator, AuthenticationResult, generate_jwt, PASSWORD_SALT
import traceback
import hashlib


class MyBackEndAuthenticator(BackEndAuthenticator):
    def __init__(self, logger: Logger=Logger()):
        super().__init__(logger=logger)
    def authenticate(self, input: dict, request_id: str=None)->AuthenticationResult:
        my_hard_coded_users = {
            'user1': {
                'password': hashlib.sha256('!paSsWord123!{}'.format(PASSWORD_SALT).encode('utf-8')).hexdigest(),
                'permissions': ['p1', 'p2'],
                'active': True
            }
        }
        result = AuthenticationResult(
            success=False,
            userid=None,
            permissions=list()
        )
        try:
            input_password_hashed = hashlib.sha256('{}{}'.format(input['password'], PASSWORD_SALT).encode('utf-8')).hexdigest()
            if input['username'] in my_hard_coded_users:
                if my_hard_coded_users[input['username']]['active']:
                    if input_password_hashed == my_hard_coded_users[input['username']]['password']:
                        result.success = True
                        result.userid = input['username']
                        result.permissions = my_hard_coded_users[input['username']]['permissions']
                        self.logger.info(message='LOGIN SUCCESS for user "{}"'.format(input['username']), request_id=request_id)
                    else:
                        self.logger.error(message='LOGIN FAIL for user "{}" - incorrect password'.format(input['username']), request_id=request_id)
                else:
                    self.logger.error(message='LOGIN FAIL for user "{}" - user not active'.format(input['username']), request_id=request_id)
            else:
                self.logger.error(message='LOGIN FAIL for user "{}" - user not found'.format(input['username']), request_id=request_id)
        except:
            self.logger.error(message='EXCEPTION: {}'.format(traceback.format_exc()), request_id=request_id)
        return result

Authenticating a user that supplies a username and password

You would also implement in this code in the application/API that handles authentication.

from pyjwt_wrapper.authentication import  authenticate_using_user_credentials

# This part would tyically be implemented in a function that receives the username and password
result = authenticate_using_user_credentials(
    application_name='my_awesome_app',
    username='user1',
    password='!paSsWord123!',
    request_id='test123',
    backend=MyBackEndAuthenticator()
)

# Return the result to the client...

The result may look something like this:

{
    'user_token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJteV9hd2Vzb21lX2FwcCIsInN1YiI6InVzZXIxIiwiY29udGV4dCI6Im15X2F3ZXNvbWVfYXBwIn0.qylm2cpukiUzCAjeDhO99iTMAWwdjuJKt4Jb2q0np2A', 
    'access_token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJteV9hd2Vzb21lX2FwcCIsInN1YiI6InVzZXIxIiwiYXVkIjoibXlfYXdlc29tZV9hcHAiLCJleHAiOjE2MTYzMTg1MTYsIm5iZiI6MTYxNjIzMjExNiwiaWF0IjoxNjE2MjMyMTE2LCJqdGkiOiJ0ZXN0MTIzIiwicHJtIjpbInAxIiwicDIiXX0.3UXG_fasgaj88ujbltHKqNUgJA1DJX9O6C6-i0Y1cIU', 
    'request_id': 'test123'
}

You should then use the access_token in every API call you make.

Authorize an API request using the access_token from Authentication

The authorization code is implemented in applications/API that receives requests from the user, which is why each request must include the access_token.

from pyjwt_wrapper.authorization import authorize_token

authorized = authorize_token(
    token=result['access_token'], 
    application_name='my_awesome_app',
    request_id='api123'
)

The resulting value from authorized should be True

Important Parameters

There are two parameters that are important to take note of:

• PASSWORD_SALT - The salt used for added protection when storing passwords.
• JWT_SECRET - The secret required to encrypt and validate a JWT

Using the password salt

Depending on your BackEndAuthenticator implementation, the PASSWORD_SALT may be considered optional. It's provided as a convenient way to include the parameter.

When your user register, your application should add some salt to ensure the password is even better protected when storing it in a database.

First, in the environment your application run, ensure the PASSWORD_SALT is set as an environment variable. This can be done using the following shell command on Linux like operating systems:

export PASSWORD_SALT="some really random text and special characters."

Typically, you will salt the password with something like:

user_password = '....' # Store the user's password in a variable 
hashed_password = hashlib.sha256('{}{}'.format(user_password, PASSWORD_SALT).encode('utf-8')).hexdigest()

# You can now save the hashed_password in a database

If you want to generate a strong salt once-off, you can run the following shell command:

python3 -c "from pyjwt_wrapper import generate_random_string; print('{}'.format(generate_random_string(length=60)))"

Important: You need to safely and securely store your salt value as any password validation will be rendered useless if you don't have the original salt it was hashed with

Using the JWT secret

The JWT secret is required and as with the password salt, you need to store it safely and securely. If you ever need to change the secret, any existing tokens created with the previous secret will not pass validation and all users would have to re-authenticate to get new tokens issued with the new secret.

Again, you can use the following one-liner utility to generate the secret:

python3 -c "from pyjwt_wrapper import generate_random_string; print('{}'.format(generate_random_string(length=60)))"

Set the following environment variable in your application environment:

export JWT_SECRET="some really random text and special characters."

Using the Refresh Token

If your front-end application gets an authorization error and you have a refresh token, you need to use the refresh token to get another set of access and refresh tokens.

Only once the refresh token have also reached expiry, must the application re-authenticate the user to get a fresh set of tokens. Form the front-end, this action can be triggered when both an API request and a refresh tokens request returned an error.

The refresh token by default only does the following basic checks in order to decide if the access token can be refreshed:

• Validate the supplied access token checksum is equal to the original calculated checksum
• Validate that the refresh token has not expired

If you need to do some additional validation, for example checking a back-end to see that the user account is still active, you can implement a function to do tat and pass it to the refresh_tokens function as a parameter. Here is an example:

from pyjwt_wrapper.authentication import refresh_tokens
import traceback

def my_validation_function(*args)->bool:
    final_result = False # fail safely
    application_name = args[9]
    decoded_access_token = args[1]
    decoded_refresh_token = args[2]
    logger = args[3]
    request_id = args[4]
    secret_str = args[5]
    try:
        # Do your own checks here....
        pass
    except:
        logger.error(message='EXCEPTION: {}'.format(traceback.format_exc()), request_id=request_id)
    return final_result


# Later, call the refresh tokens function.
#
# In this example, if the validation function throws an exception, the default 
# behavior is changed to still force a success
#
# The access_token and _refresh_token is supplied by the calling client to your refresh API
refresh_tokens(
    application_name='your-great-app',
    access_token=access_token,
    refresh_token=refresh_token,
    request_id=request_id,
    user_validation_function=my_validation_function,
    default_user_validation_function_result_on_exception=True
)

Implementation

This library can be used in two different contexts:

1. During user authentication which will result in a access_token and user_token being issues
2. During API requests, where a previously issued access_token is validated and some tests are done before the request is authorized.

For the authentication portion, you will probably implement this library at the authentication API end-point.

For authorization, you would typically implement this library in your API Gateway or proxy server in the authorization leg.

Authentication

You will still need to implement the actual method of authentication. This process is facilitated by the BackEndAuthenticator class which you need to extend with your own implementation of the authenticate method.

The authenticate method returns a AuthenticationResult which contains enough information to finally construct the dictionary that will hold the access token and user token.

The JSON Web Token (generated from pyjwt_wrapper.authentication)

Thus far, this library only support username and password authentication in a function called authenticate_using_user_credentials (name may change in future).

Access Token

The access token is typically used by one application that is requesting resources from another application to authorize the first application. The authorization is usually done by some kind of a proxy in front of the second application. A web page rendered in a user's web browser that requests some data from an application hosted on the Internet is a typical example of this setup. In this case the web page will include the access_token with each request to the application API. Each request has to pass the authorization check before the application will respond with the requested data.

There are a number of resources on the Internet that will explain in a lot more detail the mechanics of authorization, but Auth0 has a very good lightweight explanation of how the process would work.

The access_token contains the following elements:

• iss - The issuer claim which is the value of the application_name parameter. In web applications you could derive this from the Host header.
• sub - The subject claim is currently mapped to the username in username/passwords authentication
• aud - The audience claim which is also mapped to the application_name parameter at the moment.
• exp - The expiration time claim which is the Unix timestamp (UTC) after which this token is no longer considered valid.
• nbf - The not before claim which is set to the Unix timestamp (UTC) of token creation
• iat - The issued at claim which is set to the Unix timestamp (UTC) of token creation
• jti - The JWT ID claim which is mapped to the request_id parameter
• prm - A list of permission names (strings) that was valid for the user at the time of authentication. This may be useful in some front-end application to decide which components to render. For example, only provide administrator controls/components to the users that have admin rights.
• extra - An optional parameter that will only be present if the BackEndAuthenticator included extra data to include in the token. This is a standard dictionary and should only contain primitives.

User Token

The user token (also known as the ID token) contains basic user profile information.

The access_token contains the following elements:

• iss - The issuer claim which is the value of the application_name parameter. In web applications you could derive this from the Host header.
• sub - The subject claim is currently mapped to the username in username/passwords authentication
• context - This value is from the application_name parameter.
• extra - An optional parameter that will only be present if the BackEndAuthenticator included extra data to include in the token. This is a standard dictionary and should only contain primitives.

Authorization (as implemented by from pyjwt_wrapper.authorization)

During the authorization phase, PyJWT is used for the general token validation.

In addition, the authorize_token takes a number of other parameters used in the authorization process:

• application_name, which will be used to validate the aud claim
• required_permission which is a parameter you pass in based on the type of request. The function will test if this value is present in the prm claim values.

Logging

The library utilizes the standard Python logging framework and by default will use a STDOUT log handler.

Most functions takes a logger parameter which implements the Logger class. If you create your own handler, just create it yourself and initialize Logger with your handler.

Example:

from pyjwt_wrapper import Logger
import logging

fh = logging.FileHandler('spam.log')
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
fh.setFormatter(formatter)

my_logger = Logger(logging_handler=fh)

# later usage...
from pyjwt_wrapper.authentication import authenticate_using_user_credentials

auth_result = authenticate_using_user_credentials(
    application_name='my_aoo',
    username='[e-mail]',
    password='the world strongest password',
    logger=my_logger,
)

# Use the logger in your own app:
my_logger.info(message='This is a test', request_id='some-request-reference...')

Testing from Source

Basic steps:

1. Clone the repository
2. Create a Python Virtual Environment
3. Install dependencies
4. Run the unit tests
5. Get teh coverage reports

The steps above can all be summarized in the following list of Unix commands (bash or zsh):

# Clone the repository
git clone https://github.com/nicc777/pyjwt-wrapper.git

cd pyjwt-wrapper

# Create a Python Virtual Environment
python -m venv venv

. venv/bin/activate

# Install dependencies
pip install pyjwt coverage

# Run the unit tests
coverage run --source ./src -m unittest discover

# Get teh coverage reports
coverage report -m

To Do

• Create a customizable authorization class
• Create authorization caching feature