2.6. The Config File

privacyIDEA reads its configuration from different locations:

  1. default configuration from the module privacyidea/config.py

  2. then from the config file /etc/privacyidea/pi.cfg if it exists and then

  3. from the file specified in the environment variable PRIVACYIDEA_CONFIGFILE.

    export PRIVACYIDEA_CONFIGFILE=/your/config/file

The configuration is overwritten and extended in each step. I.e. values define in privacyidea/config.py that are not redefined in one of the other config files, stay the same.

You can create a new config file (either /etc/privacyidea/pi.cfg) or any other file at any location and set the environment variable. The file should contain the following contents:

# The realm, where users are allowed to login as administrators
SUPERUSER_REALM = ['super', 'administrators']
# Your database
SQLALCHEMY_DATABASE_URI = 'sqlite:////etc/privacyidea/data.sqlite'
# This is used to encrypt the auth_token
SECRET_KEY = 't0p s3cr3t'
# This is used to encrypt the admin passwords
PI_PEPPER = "Never know..."
# This is used to encrypt the token data and token passwords
PI_ENCFILE = '/etc/privacyidea/enckey'
# This is used to sign the audit log
PI_AUDIT_KEY_PRIVATE = '/home/cornelius/src/privacyidea/private.pem'
PI_AUDIT_KEY_PUBLIC = '/home/cornelius/src/privacyidea/public.pem'
# PI_AUDIT_MODULE = <python audit module>
# PI_AUDIT_SQL_URI = <special audit log DB uri>
# PI_LOGFILE = '....'
# PI_LOGLEVEL = 20
# PI_INIT_CHECK_HOOK = 'your.module.function'
# PI_CSS = '/location/of/theme.css'
# PI_UI_DEACTIVATED = True

Note

The config file is parsed as python code, so you can use variables to set the path and you need to take care for indentations.

SQLALCHEMY_DATABASE_URI defines the location of your database. You may want to use the MySQL database or Maria DB. There are two possible drivers, to connect to this database. Please read MySQL database connect string.

The SUPERUSER_REALM is a list of realms, in which the users get the role of an administrator.

PI_INIT_CHECK_HOOK is a function in an external module, that will be called as decorator to token/init and token/assign. This function takes the request and action (either “init” or “assing”) as an arguments and can modify the request or raise an exception to avoid the request being handled.

There are three config entries, that can be used to define the logging. These are PI_LOGLEVEL, PI_LOGFILE, PI_LOGCONFIG. These are described in Debugging and Logging.

You can use PI_CSS to define the location of another cascading style sheet to customize the look and fell. Read more at Themes.

Note

If you ever need passwords being logged in the log file, you may set PI_LOGLEVEL = 9, which is a lower log level than logging.DEBUG. Use this setting with caution and always delete the logfiles!

privacyIDEA digitally signs the responses. You can disable this using the parameter PI_NO_RESPONSE_SIGN. Set this to True to suppress the response signature.

You can set PI_UI_DEACTIVATED = True to deactivate the privacyIDEA UI. This can be interesting if you are only using the command line client or your own UI and you do not want to present the UI to the user or the outside world.

Note

The API calls are all still accessible, i.e. privacyIDEA is technically fully functional.

2.6.1. Engine Registry Class

The PI_ENGINE_REGISTRY_CLASS option controls the pooling of database connections opened by SQL resolvers and the SQL audit module. If it is set to "null", SQL connections are not pooled at all and new connections are opened for every request. If it is set to "shared", connections are pooled on a per-process basis, i.e. every wsgi process manages one connection pool for each SQL resolver and the SQL audit module. Every request then checks out connections from this shared pool, which reduces the overall number of open SQL connections. If the option is left unspecified, its value defaults to "null".

2.6.2. Audit parameters

PI_AUDIT_MODULE lets you specify an alternative auditing module. The default which is shipped with privacyIDEA is privacyidea.lib.auditmodules.sqlaudit. There is no need to change this, unless you know exactly what you are doing.

You can change the servername of the privacyIDEA node, which will be logged to the audit log using the variable PI_AUDIT_SERVERNAME.

You can run the database for the audit module on another database or even server. For this you can specify the database URI via PI_AUDIT_SQL_URI.

PI_AUDIT_TRUNCATE = True lets you truncate audit entries, that to the length of the database fields.

In certain cases when you experiencing problems you may use the parameters PI_AUDIT_POOL_SIZE and PI_AUDIT_POOL_RECYCLE. However, they are only effective if you also set PI_ENGINE_REGISTRY_CLASS to "shared".

If you by any reason want to avoid signing audit entries you can set PI_AUDIT_NO_SIGN = True. If PI_AUDIT_NO_SIGN is set to True audit entries will not be signed and also the signature of audit entries will not be verified. Audit entries will appears with signature fail.

2.6.3. Monitoring parameters

PI_MONITORING_MODULE lets you specify an alternative statistics monitoring module. The monitoring module takes care of writing values with timestamps to a store. This is used e.g. by the EventCounter and SimpleStats.

The first available monitoring module is privacyidea.lib.monitoringmodules.sqlstats. It accepts the following additional parameters:

PI_MONITORING_SQL_URI can hold an alternative SQL connect string. If not specified the normal SQLALCHEMY_DATABASE_URI is used.

PI_MONITORING_POOL_SIZE (default 20) and PI_MONITORING_POOL_RECYCLE (default 600) let you configure pooling. It uses the settings from the above mentioned PI_ENGINE_REGISTRY_CLASS.

Note

A SQL database is probably not the best database to store time series. Other monitoring modules will follow.

2.6.4. privacyIDEA Nodes

privacyIDEA can run in a redundant setup. For statistics and monitoring purposes you can give these different nodes, dedicated names.

PI_NODE is a string with the name of this very node. PI_NODES is a list of all available nodes in the cluster.

If PI_NODE is not set, then PI_AUDIT_SERVERNAME is used as node name. If this is also not set, the node name is returned as “localnode”.

2.6.5. Trusted JWTs

Other applications can use the API without the need to call the /auth endpoint. This can be achieved by trusting private RSA keys to sign JWTs. You can define a list of corresponding public keys that are trusted for certain users and roles using the parameter PI_TRUSTED_JWT:

PI_TRUSTED_JWT = [{"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEF...",
                    "algorithm": "RS256",
                    "role": "user",
                    "realm": "realm1",
                    "user": "userA",
                    "resolver": "resolverX"}]

This entry means, that the private key, that corresponds to the given public key can sign a JWT, that can impersonate as the userA in resolver resolverX in realmA.

A JWT can be created like this:

auth_token = jwt.encode(payload={"role": "user",
                                 "user": "userA",
                                 "realm": "realm1",
                                 "resolver": "resolverX"},
                                 key=private_key,
                                 algorithm="RS256")