HOWTO-Install-and-Configure-a-PrivacyIDEA-server.rst

HOWTO Install and Configure a PrivacyIDEA server

Index

1. Overview
2. Requirements
3. Setup dependencies
   1. System
   2. SQL Database
   3. Web Server
4. Install PrivacyIDEA
5. Create Administrators
6. Login to the Web UI
7. Setup basic Policies
   1. Disable Welcome message
   2. Change the Logout Time
   3. Allow admin user to do everything
   4. Change the Token label
8. Create UserIdResolvers
   1. Create an LDAP resolver
9. Create Realms
   1. Create the 'default' Realm
10. Enroll Tokens
    1. Enroll a TOTP token from the WebUI
    2. Enroll an Email Token from the WebUI
11. Reference
12. Authors
13. License

Overview

• PrivacyIDEA overview

Requirements

• Python 3.9.2, Python Virtual Environment & PIP (package installer di Python)
• SQL database
• Apache web server with WSGI support for Python3
• Debian 11

[TOP]

Setup dependencies

System

Create a system user privacyidea without SSH access:

• sudo adduser --system --group --shell /bin/bash --home /opt/privacyidea privacyidea

[TOP]

SQL Database

1. Become ROOT:
   • sudo su -
2. Install the required packages:
   • apt install default-mysql-server
3. Improve MySQL Installation Security:
   • mysql_secure_installation
     • Root password: empty or a desired value for the root password of MariaDB
     • Switch to unix_socket: Y
     • Change the root password? N
     • Remove anonymous users? Y
     • Disallow root login remotely? Y
     • Remove test database and access to it? Y
     • Reload privilege tables now? Y
4. Create the PrivacyIDEA database:
   • sudo mariadb
   • CREATE DATABASE pi;
   • CREATE USER "pi"@"localhost" IDENTIFIED BY "<PASSWORD>";
   • GRANT ALL PRIVILEGES ON pi.* TO "pi"@"localhost";
   • quit

[TOP]

Web Server

1. Install the required packages:
   • sudo apt install apache2 libapache2-mod-wsgi-py3
2. Enable the required modules:
   • sudo a2enmod ssl rewrite wsgi
3. Remove the default HTTP site from Apache:
   • sudo a2dissite 000-default
4. Restart Apache:
   • sudo systemctl restart apache2.service

[TOP]

Install PrivacyIDEA

1. Become ROOT:

   • sudo su -

2. Install the packages required:

   • apt install python3-pip python3-venv

3. Create PrivacyIDEA configuration dir:

   • mkdir /etc/privacyidea
   • chown privacyidea:privacyidea /etc/privacyidea

4. Become the PrivacyIDEA user:

   • sudo su privacyidea

5. Create the PrivacyIDEA Virtual Environment:

   • python3 -m venv /opt/privacyidea

6. Install PrivacyIDEA into the new Virtual Environment:

   • cd /opt/privacyidea
   • source bin/activate
   • pip install --upgrade pip
   • pip install --upgrade setuptools wheel pymysql pymysql-sa
   • pip install -r https://raw.githubusercontent.com/privacyidea/privacyidea/v3.8.1/requirements.txt
   • pip install privacyidea==3.8.1

7. Connect the database to PrivacyIDEA:

   • SQLALCHEMY_DATABASE_URI="pymysql://pi:<PASSWORD>@localhost:3306/pi"
   • echo "SQLALCHEMY_DATABASE_URI = '$SQLALCHEMY_DATABASE_URI'" >> /etc/privacyidea/pi.cfg

8. Create PrivacyIDEA tables:

   • pi-manage create_tables

9. Stamping the database to the current database schema version for the update process later:

   • pi-manage db stamp head -d /opt/privacyidea/lib/privacyidea/migrations/

10. Improve PrivacyIDEA Installation Security:

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

11. Create an encryption key for PrivacyIDEA secrets:

    • pi-manage create_enckey
    • PI_ENCFILE="/opt/privacyidea/lib/python3.9/site-packages/enckey"
    • echo "PI_ENCFILE = '$PI_ENCFILE'" >> /etc/privacyidea/pi.cfg

12. Create a key for verification of audit log entries:

    • pi-manage create_audit_keys
    • PI_AUDIT_KEY_PRIVATE="/opt/privacyidea/lib/python3.9/site-packages/private.pem"
    • PI_AUDIT_KEY_PUBLIC="/opt/privacyidea/lib/python3.9/site-packages/public.pem"
    • echo "PI_AUDIT_KEY_PRIVATE = '$PI_AUDIT_KEY_PRIVATE'" >> /etc/privacyidea/pi.cfg
    • echo "PI_AUDIT_KEY_PUBLIC = '$PI_AUDIT_KEY_PUBLIC'" >> /etc/privacyidea/pi.cfg

13. Configure some settings of PrivacyIDEA:

    • Truncate Audit entries to fit into DB columns:
      • echo "PI_AUDIT_SQL_TRUNCATE = True" >> /etc/privacyidea/pi.cfg
    • Define the PrivacyIDEA page <title>'s value:
      • echo 'PI_PAGE_TITLE = "privacyIDEA Authentication System"' >> /etc/privacyidea/pi.cfg
    • Logging:
      • echo "PI_LOGFILE = '/opt/privacyidea/privacyidea.log'" >> /etc/privacyidea/pi.cfg
      • echo "PI_LOGLEVEL = 20" >> /etc/privacyidea/pi.cfg
    • Administrators Realms:
      • echo "SUPERUSER_REALM = ['administrators']" >> /etc/privacyidea/pi.cfg

14. Exit from the Python Virtual Environment:

    • deactivate

15. Become ROOT:

    • exit (this has to be executed if the command line starts with privacyidea@...
    • sudo su -

16. Enable the required Apache2 configuration:

    • PRIVACYIDEA_VENV_APACHECONF="https://raw.githubusercontent.com/NetKnights-GmbH/ubuntu/master/deploy/apache/sites-available/privacyidea-venv.conf"
    • PRIVACYIDEA_APACHECONF="https://raw.githubusercontent.com/NetKnights-GmbH/ubuntu/master/deploy/apache/sites-available/privacyidea.conf"
    • sudo wget "$PRIVACYIDEA_VENV_APACHECONF" -O /etc/apache2/conf-available/privacyidea-venv.conf
    • sudo wget "$PRIVACYIDEA_APACHECONF" -O /etc/apache2/sites-available/privacyidea.conf

17. Adapt the downloaded file to your needs:

    • sudo vim /etc/apache2/sites-available/privacyidea.conf

      ServerName <PRIVACYIDEA_FQDN>
      ...
      WSGIScriptAlias /      /opt/privacyidea/etc/privacyidea/privacyideaapp.wsgi
      ...
      SSLCertificateFile    /etc/ssl/certs/ssl-cert.crt
      SSLCertificateKeyFile /etc/ssl/private/ssl-cert.key
      SSLCACertificateFile  /etc/ssl/certs/ca-certificates.crt

18. Enable the Apache2 configurations:

    • sudo a2enconf privacyidea-venv
    • sudo a2ensite privacyidea

19. Restart Apache2 web server:

    • sudo systemctl restart apache2.service

[TOP]

Create Administrators

The creation of the administrators' users in the PrivacyIDEA database is done throught a command line in the PrivacyIDEA Virtual Environment:

• cd /opt/privacyidea
• source bin/activate
• pi-manage admin add admin

As long as no admin policy is defined all administrators are allowed to do everything. Take a look to Admin policies

If you lock out you can disable the wrong policies by the command line with:

• cd /opt/privacyidea
• source bin/activate
• pi-manage policy -h

[TOP]

Login to the Web UI

Open https://<PRIVACYIDEA_FQDN>/ and enter the Admin username admin and <PASSWORD>.

Administrators will be able to configure the system and to manage all tokens, while normal users will only be able to manage their own tokens.

[TOP]

Setup basic Policies

DOC: Policies

Policies are just a set of definitions. These definitions are meant to modify the way privacyIDEA reacts on requests. Different policies have different scopes where they act.

For example:

• admin policies define, what an administrator is allowed to do.
• user policies define, how the system reacts if a user is managing his own tokens.
• authentication and authorization policies influence the authentication and the authorization of users/admins.

Disable Welcome message

When the administrator logs in and no UserIdResolver and no Realm are defined, a popup appears, which asks you to create a default Realm. Say "No" to the Create default realm request.

Than disable the Welcome message with the Policy template hide_welcome:

• Go to Config -> Policies
• Open Create new Policy -> Show Policy templates
• Click on hide_welcome
• Set the value of Policy Name to hide_welcome
• Set the value of Priority to 2
• Save Policy

[TOP]

Change the Logout Time

Set the timeout, after which a user in the WebUI will be logged out. The default timeout is 120 seconds.

• Go to Config -> Policies
• Open Create new Policy
• Set the value of Policy Name to webui-timeout
• Set the value of Priority to 3
• Set the value of Scope to webui
• Move on the Action tab
• Insert logout_time in the filter action search box
• Set the value of logout_time to 10 minutes: 600
• Save Policy

[TOP]

Allow admin user to do everything

Attention: Admins in privacyIDEA have rights to all actions at the beginning. This will apply as long as no admin policy is defined. If you define a policy in the scope admin, only the rights entered for the policies apply to all admins. If there is no further admin policy yet, you should be careful not to block yourself out of the web UI.

• Go to Config -> Policies
• Open Create new Policy -> Show Policy templates
• Click on superuser
• Set the value of Policy Name to superuser
• Set the value of Priority to 1
• Leave the value of Admin-Realm (under the Condition tab) to None Selected to enable policy for all admins' realms.
• Add the username of the administrator created admin to the field Admin to enable the policy for only the selected user.
• Save Policy

[TOP]

Change the Token label

Set label for a new enrolled Google Authenticator app. Possible tags are <u> (user), <r> (realm), <s> (serial).

• Go to Config -> Policies
• Open Create new Policy -> Show Policy templates
• Click on enroll_tokenlabel
• Set the value of Policy Name to enroll_tokenlabel
• Set the value of Priority to 4
• Move on the Action tab and click on the Show selected actions only button
• Edit the tokenlabel by inserting the label you prefer (e.g.: Lab MFA 42: OTP (<u>))
• Save Policy

[TOP]

Create UserIdResolvers

DOC: UserIdResolvers

The UserIdResolver is the connector to a user source. You can create as many UserIdResolvers as you wish and edit existing resolvers.

There are resolvers for simple text file, LDAP Directory, SQL database, SCIM, HTTP. It also possible to develop your own resolver with a python module.

[TOP]

Create an LDAP resolver

DOC: PrivacyIDEA LDAP Resolver

The LDAP resolver can be used to access any kind of LDAP service like OpenLDAP, Active Directory, FreeIPA, Penrose, Novell eDirectory.

PrivacyIDEA can use the following datas: username, surname, givenname, email, phone, mobile

• Go to Config -> Users to create a UserIdResolver.
• Choose New ldapresolver and fill at least the following fields:
  • Resolver name: LABMFA<N>-ldap-resolver
  • Server URI: ldap://idem-day-idp-<N>.aai-test.garr.it
  • STARTTLS: Checked
  • TLS Version: TLS v1.3
  • Verify TLS: Checked and /etc/ssl/certs/ca-certificates.crt
  • Base DN: ou=people,dc=idem-day-org-<N>,dc=it
  • Scope: SUBTREE
  • Bind Type: Simple
  • Bind DN: cn=idm-user,ou=system,dc=idem-day-org-<N>,dc=it
  • Bind Password: <IDM-USER-PASSWORD>
  • Per-process server pool: Checked
  • Click on Preset OpenLDAP
  • Insert into Loginname Attribute the LDAP attribute name used to login the PrivacyIDEA Web UI
  • Insert into Search Filter the correct value to list all possible users
  • Remove from the Attribute mapping those datas not managed by the OpenLDAP server connected
  • Insert into Multivalue Attributes a Python list of user attributes, that should return a list of values. E.g.: ['mail']
  • Insert into UID Type the unique identifier for the LDAP object. We suggest to use an attribute with a value that not change permanently. If your OpenLDAP get corrupted, you will break all due the change of the entryUUID value for all entries.
  • Check the No anonymous referral chasing box if Active Directory is used.
  • Check the No retrieval of schema information box to disable the retrieval of schema information in order to improve performance.

The Server URI can contains a comma separated list of servers. The servers are used to create a server pool and are used with a round robin strategy.

• Test with:
  • Quick resolver test button
  • Test LDAP Resolver button
• Save resolver

[TOP]

Create Realms

DOC: PrivacyIDEA Realms

Realms are collections of resolvers that can be managed by administrators and where policies can be applied.

Users need to be in realms to have tokens assigned.

A user, who is not member of a realm can not have a token assigned and can not authenticate.

Several different UserIdResolvers can be combined into a realm.

Create the 'default' realm

The system knows one default realm > defrealm.

The defrealm is a special endpoint to define the default realm. The default realm is used if no user realm is specified.

Users within the default realm can authenticate with their username.

Users outside of the default realm have to authenticate theirselves with username@realm-name.

Into this HOWTO we'll use only the default realm because we don't need more than one realm.

• Go to Config -> Realms
• Set idem-day-org-<N>.it on Realm name
• Check the new resolver created
• Press on Create realm

If other realms are defined on PrivacyIDEA, the default one can set on the realm list from the WebUI.

[TOP]

Enroll Tokens

DOC: PrivacyIDEA Tokens

Without any specific policy an user can use any token supported by PrivacyIDEA.

Enroll a TOTP token from the WebUI

DOC: TOTP Token

A time based One Time Password tokens based on RFC6238.

• Go to Tokens -> Enroll Token
• Select TOTP: Time Base One Time Passwords.
• Enter the user name under Username
• Leave the PIN empty
• Press the Enroll Token button
• Scan the QR Code with Google Authenticator or another apps
• TOTP Token is enrolled
• Enjoy

[TOP]

Enroll an Email Token from the WebUI

DOC: Email Token

A token that sends the OTP value to the E-Mail address of the user.

1. Add your SMTP server:

   1. Go to Config -> System -> SMTP servers
   2. Adding a new SMTP server by opening New SMTP server:
      • Identifier: labmfa<N>-smtp
      • IP or FQDN: idem-day-idp-<N>.aai-test.garr.it
      • Port: 1025
      • Timeout: 10
      • Sender Email: privacyidea@idem-day-org-<N>.it
      • StartTLS: no
      • Recipient for testing: [email protected]
      • Test with Send Test Email
      • Save SMTP server

2. Link the SMTP server to the Email Token:

   • Go to Config -> Tokens -> Email
   • Select the SMTP server created into SMTP server configuration
   • Set the OTP validity time to 30 seconds.
   • Save

3. Enroll an Email Token from the WebUI:

   • Go to Tokens -> Enroll Token
   • Select Email: Send a One Time Passwords to the users email address.
   • Check the box Read email address dynamically from user source on each request.
   • Enter the user name under Username
   • Leave the "PIN" empty (if you don't use it)
   • Press the Enroll Token button

   The Email Token is a challenge response token, this means that first the user sends an authentication request to obtain the OTP value sent by email, and then sends a second authentication request by presenting the OTP value obtained by email:

   1. curl -X POST -F 'user=<USERNAME>' -F 'pass=' https://idem-day-mfa-<N>.aai-test.garr.it/validate/check
   2. The OTP value is sent to the email address of the user <USERNAME>.
   3. curl -X POST -F 'user=<USERNAME>' -F 'transaction_id=<TRANSACTION_ID>' -F 'pass=<OTP-VALUE>' https://idem-day-mfa-<N>.aai-test.garr.it/validate/check

[TOP]

Reference

• PrivacyIDEA Documentation

Authors

• Marco Malavolti

License

This HOWTO is licensed under CC BY-SA 4.0.

[TOP]