Skip to main content

A small authentication-authorization server.

Project description

Build Status Documentation Status

This is a small server meant to help add authentication (authn) and authorization (authz) to other HTTP servers. It's built using Tornado, SQLAlchemy, cryptography, argon2-cffi, python-diskcache, and uvloop.

I wrote it to help with the login/logout/signup flows for the LCC-Server and extracted much of the code from there. It builds on the auth bits there and is eventually meant to replace them. It can do the following things:

  • Handle user sign-ups, logins, logouts, and locks/unlocks.
  • Handle user email verification, password changes, forgotten password processes, and editing user properties.
  • Handle API key issuance and verification.
  • Handle access and rate-limit checks for arbitrary schemes of user roles, permissions, and target items. There is a default scheme of permissions and user roles, originally from the LCC-Server where this code was extracted from. Another permissions policy can be specified as JSON.

See for features that are planned for the future. See for a version history.

Authnzerver talks to a frontend server over HTTP. Communications are secured with symmetric encryption using the cryptography package's Fernet scheme, so you'll need a pre-shared key that both Authnzerver and your frontend server know.

See for details on the HTTP API. Also see the (in-progress) Python module documentation.


Authnzerver is available at PyPI, but is very much a work in progress at the moment. Maybe hold off on installing it until we've reached v0.2 (beta).

With that said, it can be installed (preferably in a virtualenv) using pip:

(venv) $ pip install authnzerver

# use pip install authnzerver --pre for unstable releases

Running the server

There is a single executable that will be in your $PATH if you have a virtualenv activated and the package installed: authnzrv.

authnzrv --help will list all the options available:

--authdb         An SQLAlchemy database URL to indicate where
                 the local authentication DB is. This should
                 be in the form discussed at: https://docs.sq
--autosetup      If this is True, will automatically generate
                 an SQLite authentication database in the
                 basedir if there isn't one present and the
                 value of the authdb option is also None.
                 (default False)
--basedir        The base directory containing secret files
                 and the auth DB. (default os.getcwd())
--cachedir       Path to the cache directory to be used.
                 (default /tmp/authnzerver-cache)
--debugmode      If 1, will enable an /echo endpoint for
                 debugging purposes. (default False)
--emailpass      The password to use for login to the email
--emailport      The SMTP port of the email server to use.
                 (default 25)
--emailsender    The account name and email address that the
                 authnzerver will send from. (default
                 Authnzerver <authnzerver@localhost>)
--emailserver    The address of the email server to use.
                 (default localhost)
--emailuser      The username to use for login to the email
                 server. (default getpass.getuser())
--envfile        Path to a file containing environ variables
                 for testing/development.
--listen         Bind to this address and serve content.
--permissions    The JSON file containing the permissions
                 model the server will enforce. (default
--piisalt        A random value used as a salt when SHA256
                 hashing personally identifiable information
                 (PII), such as user IDs and session tokens,
                 etc. for authnzerver logs.
--port           Run the server on this TCP port. (default
--secret         The shared secret key used to secure
                 communications between authnzerver and any
                 frontend servers.
--sessionexpiry  This sets the session-expiry time in days.
                 (default 30)
--workers        The number of background workers to use when
                 processing requests. (default 4)

There's an example systemd .service file available in the deploy directory to run this server automatically on startup.

Configuring the server

Use the following environmental variables to configure the server. Defaults are noted below where appropriate.

# listen address, port settings, and workers

# cache and base directory locations
AUTHNZERVER_BASEDIR=directory where the server is started

# secret token, PII salt, and authentication DB URL

# session expiry time in days

# permissions model JSON

# email settings for sending emails to users
AUTHNZERVER_EMAILSENDER=Authnzerver <authnzerver@localhost>
AUTHNZERVER_EMAILUSER=user running the authnzrv executable

You can also provide all of these at once using an environment file. This is not recommended for production but is useful for development. If you go this route, use the --envfile option to point to an appropriate environment file.

At a minimum, you must provide:

  • a random pre-shared secret key as an environmental variable: AUTHNZERVER_SECRETKEY.
  • a random salt value for hashing personally identifiable information in the authnzerver logs as an environmental variable: AUTHNZERVER_PIISALT.
  • an SQLAlchemy database URL indicating where the server should store authentication information as an environmental variable: AUTHNZERVER_AUTHDB.

If none of these are provided, and the command-line option --autosetup=True, the server will prompt you for admin credentials during start up, generate the pre-shared secret key and random salt, and initialize an authentication database at the SQLAlchemy URL you provide. Autogenerated defaults for these values can be used by hitting Enter at all the prompts.


Authnzerver is provided under the MIT License. See the LICENSE file for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

authnzerver-0.1.3.tar.gz (168.1 kB view hashes)

Uploaded source

Built Distribution

authnzerver-0.1.3-py3-none-any.whl (187.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page