2.1. Python Package Index

You can install privacyidea usually on any Linux distribution in a python virtual environment. This way you keep all privacyIDEA code in one defined subdirectory.

Note

privacyIDEA currently runs with Python 3.9 to 3.12. Other versions either do not work or are not tested.

2.1.1. Setting up a virtual environment

You first need to install a package for creating a python virtual environment.

Now you can setup the virtual environment for privacyIDEA like this:

$ virtualenv /opt/privacyidea

$ cd /opt/privacyidea
$ source bin/activate
(privacyidea)$

Note

Some distributions still ship Python 2.7 as the system python. If you want to use Python 3 you can create the virtual environment like this: virtualenv -p /usr/bin/python3 /opt/privacyidea

Now you are within the python virtual environment and you can proceed with the deterministic installation.

2.1.2. Deterministic Installation

The privacyIDEA package contains dependencies with a minimal required version. However, newest versions of dependencies are not always tested and might cause problems. To achieve a deterministic installation, you must install the pinned and tested versions of the dependencies before installing privacyIDEA:

(privacyidea)$ pip install -r https://raw.githubusercontent.com/privacyidea/privacyidea/v3.11.3/requirements.txt

Now you can install the required privacyIDEA version from PyPI:

(privacyidea)$ pip install privacyidea==3.11.3

The requirements are also available after the installation at /opt/privacyidea/lib/privacyidea/requirements.txt.

2.1.3. Optional features (extras)

Some features need optional dependencies that are not installed by default. They are declared as pip extras and installed on demand:

(privacyidea)$ pip install "privacyidea[postgres]"    # PostgreSQL driver (psycopg2)
(privacyidea)$ pip install "privacyidea[kerberos]"    # SASL-Kerberos bind for LDAP resolvers (gssapi)
(privacyidea)$ pip install "privacyidea[hsm]"          # PKCS#11 hardware security module support (PyKCS11)

Extras can be combined, e.g. pip install "privacyidea[postgres,kerberos]".

All three extras build native extensions that link against system libraries, so the matching OS packages must be present:

  • postgres (psycopg2): needs the PostgreSQL client library and its headers (libpq-dev / postgresql-devel), the pg_config executable they ship and a C compiler. Without them pip aborts with Error: pg_config executable not found. The prebuilt psycopg2-binary wheel needs no build tools and is a practical choice for development and testing, but upstream advises against it in production, as it bundles its own libssl and libcrypto.

  • kerberos (gssapi): pip usually installs a prebuilt wheel, but the host still needs the MIT Kerberos runtime libraries (libkrb5 / krb5-libs) and a valid /etc/krb5.conf for the realm. If pip has to build from source, additionally install the Kerberos development headers (libkrb5-dev / krb5-devel), krb5-config and a C compiler.

  • hsm (PyKCS11): additionally needs your HSM vendor’s PKCS#11 module.

Note

The official Docker image already includes the kerberos extra and the Kerberos runtime libraries, so a containerized deployment only needs a mounted krb5.conf. It also ships psycopg2-binary, so the postgres extra is not needed there either.

2.1.4. Configuration

2.1.4.1. Database

privacyIDEA makes use of SQLAlchemy to be able to talk to different SQL-based databases. Our best experience is with MySQL but SQLAlchemy supports many different databases [1].

The database server should be installed on the host or be otherwise reachable.

In order for privacyIDEA to use the database, a database user with the appropriate privileges is needed. The following SQL commands will create the database as well as a user in MySQL:

CREATE DATABASE pi;
CREATE USER "pi"@"localhost" IDENTIFIED BY "<dbsecret>";
GRANT ALL PRIVILEGES ON pi.* TO "pi"@"localhost";

You must then add the database name, user and password to your pi.cfg. See The Config File for more information on the configuration.

2.1.4.2. Setting up privacyIDEA

Additionally to the database connection a new PI_PEPPER and SECRET_KEY must be generated in order to secure the installation:

PEPPER="$(tr -dc A-Za-z0-9_ </dev/urandom | head -c24)"
echo "PI_PEPPER = '$PEPPER'" >> /path/to/pi.cfg
SECRET="$(tr -dc A-Za-z0-9_ </dev/urandom | head -c24)"
echo "SECRET_KEY = '$SECRET'" >> /path/to/pi.cfg

An encryption key for encrypting the secrets in the database and a key for signing the Audit log is also needed (the following commands should be executed inside the virtual environment):

(privacyidea)$ pi-manage setup create_enckey  # encryption key for the database
(privacyidea)$ pi-manage setup create_audit_keys  # key for verification of audit log entries

To create the database tables execute:

(privacyidea)$ pi-manage setup create_tables

After creating a local administrative user with:

(privacyidea)$ pi-manage admin add <login>

the development server can be started with:

(privacyidea)$ pi-manage run

Changed in version 3.10: To start the development server with an earlier version use runserver. The command is still available but deprecated.

Warning

The development server should not be used for a productive environment.

2.1.4.3. Webserver

To serve authentication requests and provide the management UI a WSGI capable webserver like Apache2 or nginx is needed.

Setup and configuration of a webserver can be a complex procedure depending on several parameter (host OS, SSL, internal network structure, …). Some example configuration can be found in the NetKnights GitHub repositories [2]. More on the WSGI setup for privacyIDEA can be found in The WSGI Script.

2.1.4.4. Cleanup jobs

An installation from PyPI does not schedule any jobs. Set up the cron jobs described in Cleanup Jobs, otherwise several database tables grow without limit.

Footnotes