Package: uffd
DO NOT INSTALL FROM PIP FOR PRODUCTION DEPLOYMENTS, seeDeploymentfor more information.UffdUffd (UserFerwaltungsFrontend) is a web-based user management and single sign-on software.Development chat:#uffd-developmentDependenciesPlease note that we refer to Debian packages here andnotpip packages.python3python3-flaskpython3-flask-sqlalchemypython3-flask-migratepython3-qrcodepython3-fido2 (version 0.5.0 or 0.9.1, optional)python3-prometheus-client (optional, needed for metrics)python3-oauthlibpython3-flask-babelpython3-argon2python3-itsdangerous (also a dependency of python3-flask)python3-mysqldb or python3-pymysql for MariaDB supportSome of the dependencies (especially fido2) changed their API in recent versions, so make sure to install the versions from Debian Bookworm, Bullseye or Buster.
For development, you can also use virtualenv with the suppliedrequirements.txt.DevelopmentBefore running uffd, you need to create the database withflask db upgrade. The database is placed ininstance/uffd.sqlit3.Then useflask runto start the application:FLASK_APP=uffd flask db upgrade
FLASK_APP=uffd FLASK_ENV=development flask runDuring development, you may want to create some example data:export FLASK_APP=uffd
flask group create 'uffd_access' --description 'Access to Single-Sign-On and Selfservice'
flask group create 'uffd_admin' --description 'Admin access to uffd'
flask role create 'base' --default --add-group 'uffd_access'
flask role create 'admin' --add-group 'uffd_admin'
flask user create 'testuser' --password 'userpassword' --mail 'test@example.com' --displayname 'Test User'
flask user create 'testadmin' --password 'adminpassword' --mail 'admin@example.com' --displayname 'Test Admin' --add-role 'admin'Afterwards you can login as a normal user with "testuser" and "userpassword", or as an admin with "testadmin" and "adminpassword".DeploymentDo not usepip install uffdfor production deployments!
The dependencies of the pip package roughly represent the versions shipped by Debian stable.
We do not keep them updated and we do not test the pip package!
The pip package only exists for local testing/development and to help build the Debian package.We provide packages for Debian stable, oldstable and oldoldstable (currently Bookworm, Bullseye and Buster).
Since all dependencies are available in the official package mirrors, you will get security updates for everything but uffd itself from Debian.To install uffd on Debian Bullseye, add our package mirror to/etc/sources.list:deb https://packages.cccv.de/uffd bullseye mainThen downloadcccv-archive-key.gpgand add it to the trusted repository keys in/etc/apt/trusted.gpg.d/.
Afterwards runapt update && apt install uffdto install the package.The Debian package uses uwsgi to run uffd and ships anuffd-adminscript to execute flask commands in the correct context.
If you upgrade, make sure to runflask db upgradeafter every update! The Debian package takes care of this by itself using uwsgi pre start hooks.
For an example uwsgi config, see ouruswgi.ini. You might find ournginx include filehelpful to setup a web server in front of uwsgi.Uffd supports SQLite and MariaDB. To use MariaDB, create the database with the optionsCHARACTER SET utf8mb4 COLLATE utf8mb4_nopad_binand make sure to add the?charset=utf8mb4parameter toSQLALCHEMY_DATABASE_URI.Python Coding Style ConventionsPEP 8 without double new lines, tabs instead of spaces and a max line length of 160 characters.
We ship apylintconfig to verify changes with.ConfigurationUffd reads its default config fromuffd/default_config.cfg.
You can overwrite config variables by creating a config file in theinstancefolder.
The file must be namedconfig.cfg(Python syntax),config.jsonorconfig.yml/config.yaml.
You can also set a custom file path with the environment variableCONFIG_PATH.OAuth2 Single-Sign-On ProviderOther services can use uffd as an OAuth2.0-based authentication provider.
The required credentials (client_id, client_secret and redirect_uris) for these services are defined in the config.
The services need to be setup to use the following URLs with the Authorization Code Flow:/oauth2/authorize: authorization endpoint/oauth2/token: token request endpoint/oauth2/userinfo: endpoint that provides information about the current userThe only OAuth2 scope supported isprofile. The userinfo endpoint returns json data with the following structure:{
  "id": 10000,
  "name": "Test User",
  "nickname": "testuser"
  "email": "testuser@example.com",
  "groups": [
    "uffd_access",
    "users"
  ],
}idis the numeric (Unix) user id,namethe display name andnicknamethe loginname of the user.MetricsUffd can export metrics in a prometheus compatible way. It needs python3-prometheus-client for this feature to work.
Metrics can be accessed via/metricsand/api/v1/metrics_prometheus.
Those endpoints are protected via api credentials. Add prometheus in the uffd UI as a service and create an
api client with themetricspermission. Then you can access the metrics like that:$ curl localhost:5000/api/v1/metrics_prometheus --user api-user:api-password
# HELP python_info Python platform information
# TYPE python_info gauge
python_info{implementation="CPython",major="3",minor="9",patchlevel="2",version="3.9.2"} 1.0
# HELP uffd_version_info Various version infos
# TYPE uffd_version_info gauge
uffd_version_info{version="local"} 1.0
[..]TranslationThe web frontend is initially written in English and translated in the following Languages:The selection uses the language browser header by default but can be overwritten via a UI element.
You can specify the available languages in the config.Use theupdate_translations.shto update the translation files.LicenseGNU Affero General Public License v3.0, seeLICENSE.