A Python library to create and validate authentication tokens

Overview

handshake

A Python library to create and validate authentication tokens.

handshake is used to generate and validate arbitrary authentication tokens that contain arbitrary metadata and support expiration. It uses basic cryptographic primitives (hashing, HMACs) and is based around the concept of a shared private secret for security.

Example usage would be to create namespaced authentication tokens for clients of an API which another service can check is valid and hasn't expired. The tokens are safe to be made public, put in headers etc. and can be used like session tokens.

The tokens are strings in the format of:

arbitrary:data:here:timestamp:random:signature

All fields other than timestamp, random and signature are optional. Signatures are in the format of:

HMAC(arbitrary:data:here:timestamp:random){shared_secret}

The library is designed to allow whatever metadata is required into the token, such as the first parameter could be a namespace and the second parameter an object id. This allows tokens to be easily split between internal systems and uses while containing metadata or IDs for other objects.

For example, you could use handshake to allow an API to generate tokens which a client stores for a variable amount of time and can verify their state with other services. The arbitrary data prefix can be used to store an application namespace and the UUID of the object being referenced (such as user:uuid or service:recordtype:uuid). This library is of most use if you have multiple diverse systems, microservices or other distributed endpoints that require ad-hoc authentication and something like JWT or OAuth is overkill.

Installation

handshake is pure Python and has no dependancies. You can install handshake via pip:

$ pip install handshake

Any modern version of Python3 will be compatible.

Usage

handshake has one class providing two basic public functions. Examples:

import os
from handshake import AuthToken

# The shared secret, keep this private, can be str or bytes but needs to be
# from a cryptographically secure source
secret = os.urandom(128)

# Create the instance
token = AuthToken(secret)

# Basic token with no additional parameters
plain_token = token.create()
token.verify(plain_token)

# The token must be no more than 300 seconds old
plain_token = token.create()
token.verify(plain_token, time_range=300)

# Namespaced but no specific item, namespace is arbitrary
namespaced_token = token.create('namespace')
token.verify(namespaced_token)

# Namespaced and with an arbitrary item ID
from uuid import uuid4
client_token = token.create('user', uuid4())
token.verify(client_token)

# Lots of metadata
client_token = token.create('network', 'node', '12345', '67890')
token.verify(client_token)

# Use blake2s for hashes and signatures
from hashlib import blake2s
token = AuthToken(secret, hashfunc=blake2s)
blake2s_token = token.create()
token.verify(blake2s_token)

If a token fails to validate it raise the relevent exception:

# Create a token with one secret
token = AuthToken('a fixed secret string')
plain_token = token.create()

# Attempt to verify it with a different token, this is invalid
token_with_different_secret = AuthToken('not the same secret string')
token_with_different_secret.verify(plain_token)
# ... a child of handshake.errors.InvalidTokenError exception is raised

Limitations

The secret must be at least 16 bytes or characters and no more than 1024 bytes or characters. The total generated token length cannot be longer than 2048 characters.

Full API synopsis

handshake.AuthToken(secret=str_or_bool, hashfunc=function)

Initiates an AuthToken object using the specified secret. The secret is required. It must be either a string or a bytes and must be between 32 and 1024 characters or bytes in length. The secret should be sourced from a cryptographically safe random source, such as os.urandom.

hashfunc defaults to hashlib.sha256 but you can replace it with another hash function if you need to.

handshake.AuthToken.create(*arbitrary str)

Creates an authentication token.

handshake.AuthToken.verify(token=str, time_range=int)

Verifies an authentication token created with handshake.AuthToken.create().

time_range is an optional integer which if set specifies the valid time range the token must have been generated within. This is used to verify expiring tokens. It defaults to 0 which disables time range validation.

If the token is valid a tuple containing any arbitrary data in the token. For example a token of

arbitrary:data:here:timestamp:random:signature

If valid would return a tuple of:

('arbitrary', 'data', 'here')

If the token is invalid for any reason a handshake.errors.InvalidTokenError exception is raised (or a child exception of handshake.errors.InvalidTokenError). You can handle different errors by catching them specifically and the exception names describe the event:

import os
from handshake import AuthToken, errors

secret = os.urandom(128)
token = AuthToken(secret)
test_token = token.create()

try:
    token.verify(test_token)
except errors.TokenExpiredError as e:
    print(e)
except errors.TokenSignatureError as e:
    print(e)
except errors.InvalidTokenError as e:
    print(e)

Tests

There is a test suite that you can run by cloning this repository and executing:

$ make test

Contributing

All properly formatted and sensible pull requests, issues and comments are welcome.

You might also like...
Simple yet powerful authorization / authentication client library for Python web applications.

Authomatic Authomatic is a framework agnostic library for Python web applications with a minimalistic but powerful interface which simplifies authenti

Crie seus tokens de autenticação com o AScrypt.

AScrypt tokens O AScrypt é uma forma de gerar tokens de autenticação para sua aplicação de forma rápida e segura. Todos os tokens que foram, mesmo que

Local server that gives you your OAuth 2.0 tokens needed to interact with the Conta Azul's API

What's this? This is a django project meant to be run locally that gives you your OAuth 2.0 tokens needed to interact with Conta Azul's API Prerequisi

Creation & manipulation of PyPI tokens

PyPIToken: Manipulate PyPI API tokens PyPIToken is an open-source Python 3.6+ library for generating and manipulating PyPI tokens. PyPI tokens are ver

Two factor authentication system using azure services and python language and its api's
Two factor authentication system using azure services and python language and its api's

FUTURE READY TALENT VIRTUAL INTERSHIP PROJECT PROJECT NAME - TWO FACTOR AUTHENTICATION SYSTEM Resources used: * Azure functions(python)

Toolkit for Pyramid, a Pylons Project, to add Authentication and Authorization using Velruse (OAuth) and/or a local database, CSRF, ReCaptcha, Sessions, Flash messages and I18N

Apex Authentication, Form Library, I18N/L10N, Flash Message Template (not associated with Pyramid, a Pylons project) Uses alchemy Authentication Authe

This app makes it extremely easy to build Django powered SPA's (Single Page App) or Mobile apps exposing all registration and authentication related functionality as CBV's (Class Base View) and REST (JSON)

Welcome to django-rest-auth Repository is unmaintained at the moment (on pause). More info can be found on this issue page: https://github.com/Tivix/d

Simple extension that provides Basic, Digest and Token HTTP authentication for Flask routes

Flask-HTTPAuth Simple extension that provides Basic and Digest HTTP authentication for Flask routes. Installation The easiest way to install this is t

Implements authentication and authorization as FastAPI dependencies

FastAPI Security Implements authentication and authorization as dependencies in FastAPI. Features Authentication via JWT-based OAuth 2 access tokens a

Releases(v0.2.1)
An open source Flask extension that provides JWT support (with batteries included)!

Flask-JWT-Extended Features Flask-JWT-Extended not only adds support for using JSON Web Tokens (JWT) to Flask for protecting views, but also many help

Landon Gilbert-Bland 1.4k Jan 04, 2023
Basic auth for Django.

easy-basicauth WARNING! THIS LIBRARY IS IN PROGRESS! ANYTHING CAN CHANGE AT ANY MOMENT WITHOUT ANY NOTICE! Installation pip install easy-basicauth Usa

bichanna 2 Mar 25, 2022
Web authentication testing framework

What is this This is a framework designed to test authentication for web applications. While web proxies like ZAProxy and Burpsuite allow authenticate

OWASP 88 Jan 01, 2023
Implementation of Supervised Contrastive Learning with AMP, EMA, SWA, and many other tricks

SupCon-Framework The repo is an implementation of Supervised Contrastive Learning. It's based on another implementation, but with several differencies

Ivan Panshin 132 Dec 14, 2022
Todo app with authentication system.

todo list web app with authentication system. User can register, login, logout. User can login and create, delete, update task Home Page here you will

Anurag verma 3 Aug 18, 2022
Script that provides your TESLA access_token and refresh_token

TESLA tokens This script helps you get your TESLA access_token and refresh_token in order to connect to third party applications (Teslamate, TeslaFi,

Bun-Ny TAN 3 Apr 28, 2022
Toolkit for Pyramid, a Pylons Project, to add Authentication and Authorization using Velruse (OAuth) and/or a local database, CSRF, ReCaptcha, Sessions, Flash messages and I18N

Apex Authentication, Form Library, I18N/L10N, Flash Message Template (not associated with Pyramid, a Pylons project) Uses alchemy Authentication Authe

95 Nov 28, 2022
API with high performance to create a simple blog and Auth using OAuth2 ⛏

DogeAPI API with high performance built with FastAPI & SQLAlchemy, help to improve connection with your Backend Side to create a simple blog and Cruds

Yasser Tahiri 111 Jan 05, 2023
Extending the Django authentication system with a phone verification step.

Extending the Django authentication system with a phone verification step.

Miguel Grinberg 50 Dec 04, 2022
Easy and secure implementation of Azure AD for your FastAPI APIs 🔒 Single- and multi-tenant support.

Easy and secure implementation of Azure AD for your FastAPI APIs 🔒 Single- and multi-tenant support.

Intility 220 Jan 05, 2023
A host-guest based app in which host can CREATE the room. and guest can join room with room code and vote for song to skip. User is authenticated using Spotify API

A host-guest based app in which host can CREATE the room. and guest can join room with room code and vote for song to skip. User is authenticated using Spotify API

Aman Raj 5 May 10, 2022
Ready to use and customizable Authentications and Authorisation management for FastAPI ⚡

AuthenticationX 💫 Ready-to-use and customizable Authentications and Oauth2 management for FastAPI ⚡ Source Code: https://github.com/yezz123/AuthX Doc

Yasser Tahiri 404 Dec 27, 2022
Login-python - Login system made in Python, using native libraries

login-python Sistema de login feito 100% em Python, utilizando bibliotecas nativ

Nicholas Gabriel De Matos Leal 2 Jan 28, 2022
Authentication with fastapi and jwt cd realistic

Authentication with fastapi and jwt cd realistic Dependencies bcrypt==3.1.7 data

Fredh Macau 1 Jan 04, 2022
Local server that gives you your OAuth 2.0 tokens needed to interact with the Conta Azul's API

What's this? This is a django project meant to be run locally that gives you your OAuth 2.0 tokens needed to interact with Conta Azul's API Prerequisi

Fábio David Freitas 3 Apr 13, 2022
A full Rest-API With Oauth2 and JWT for request & response a JSON file Using FastAPI and SQLAlchemy 🔑

Pexon-Rest-API A full Rest-API for request & response a JSON file, Building a Simple WorkFlow that help you to Request a JSON File Format and Handling

Yasser Tahiri 15 Jul 22, 2022
Foundation Auth Proxy is an abstraction on Foundations' authentication layer and is used to authenticate requests to Atlas's REST API.

foundations-auth-proxy Setup By default the server runs on http://0.0.0.0:5558. This can be changed via the arguments. Arguments: '-H' or '--host': ho

Dessa - Open Source 2 Jul 03, 2020
Python One-Time Password Library

PyOTP - The Python One-Time Password Library PyOTP is a Python library for generating and verifying one-time passwords. It can be used to implement tw

PyAuth 2.2k Dec 26, 2022
Flask Implementation of a login page and some basic functionality.

login_page Flask Implementation of a login page and some basic functionality. How to Run $ chmod +x run.sh setup.sh $ # run setup.sh only if the datab

3 Jun 03, 2021
Use this to create (admin) personal access token in gitlab database. Mainly used for automation.

gitlab-personal-access-token Ensure PAT is present in gitlab database. This tool is mainly used when you need to automate gitlab installation and conf

CINAQ Internet Technologies 1 Jan 30, 2022