Compare revisions

.pytest_cache/

# Translations

*.mo

*.pot

# Django stuff:

tags

# Persistent undo

[._]*.un~

# Auto-generated development key/certificate

devcert.crt

devcert.key

image: debian:latest

image: registry.git.cccv.de/uffd/docker-images/bookworm

variables:

  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

  DEBIAN_FRONTEND: noninteractive 

  GIT_SUBMODULE_STRATEGY: normal

  APT_API_URL: https://packages.cccv.de

  APT_REPO: uffd

  PYLINT_PIN: pylint~=2.16.2

before_script:

  - apt update

  - apt -y -qq -o Dpkg::Use-Pty=0 install python3 sqlite3 locales-all git python3-flask python3-coverage python3-flask-sqlalchemy python3-pip python-ldap3

  - python3 -V

  - lsb_release -a

  - uname -a

  - python3 -m pylint --version

  - python3 -m coverage --version

  - export PACKAGE_VERSION="$(git describe | sed -E -n -e 's/^v([0-9.]*)$/\1/p' -e 's/^v([0-9.]*)-([0-9]*)-g([0-9a-z]*)$/\1.dev+git.\3/p' | grep .)"

linter:

.build:

  stage: build

build:pip:

  extends: .build

  script:

  - python3 -m build

  artifacts:

    paths:

      - dist/*

build:apt:

  extends: .build

  script:

  - ./debian/create_changelog.py uffd > debian/changelog

  - export PYBUILD_INSTALL_ARGS="--install-lib=/usr/share/uffd/ --install-scripts=/usr/share/uffd/"

  - export DEB_BUILD_OPTIONS=nocheck

  - dpkg-buildpackage -us -uc

  - mv ../*.deb ./

  - dpkg-deb -I *.deb

  - dpkg-deb -c *.deb

  artifacts:

    paths:

    - ./*.deb

db_migrations_updated:

  stage: test

  needs: []

  script:

  - FLASK_APP=uffd FLASK_ENV=testing flask db upgrade

  - FLASK_APP=uffd FLASK_ENV=testing flask db migrate 2>&1 | grep -q 'No changes in schema detected'

linter:buster:

  image: registry.git.cccv.de/uffd/docker-images/buster

  stage: test

  needs: []

  script:

  - pip3 install $PYLINT_PIN pylint-gitlab pylint-flask-sqlalchemy # this force-updates jinja2 and some other packages!

  - python3 -m pylint --output-format=pylint_gitlab.GitlabCodeClimateReporter:codeclimate.json,pylint_gitlab.GitlabPagesHtmlReporter:pylint.html,colorized uffd

  artifacts:

    when: always

    paths:

    - pylint.html

    reports:

      codequality: codeclimate.json

linter:bullseye:

  image: registry.git.cccv.de/uffd/docker-images/bullseye

  stage: test

  needs: []

  script:

  - pip3 install $PYLINT_PIN pylint-gitlab pylint-flask-sqlalchemy # this force-updates jinja2 and some other packages!

  - python3 -m pylint --output-format=pylint_gitlab.GitlabCodeClimateReporter:codeclimate.json,pylint_gitlab.GitlabPagesHtmlReporter:pylint.html,colorized uffd

  artifacts:

    when: always

    paths:

    - pylint.html

    reports:

      codequality: codeclimate.json

linter:bookworm:

  image: registry.git.cccv.de/uffd/docker-images/bookworm

  stage: test

  needs: []

  script:

  - pip3 install pylint

  - python3 -m pylint --rcfile .pylintrc --output-format=text uffd | tee pylint.txt

  - pip3 install $PYLINT_PIN pylint-gitlab pylint-flask-sqlalchemy # this force-updates jinja2 and some other packages!

  - python3 -m pylint --output-format=pylint_gitlab.GitlabCodeClimateReporter:codeclimate.json,pylint_gitlab.GitlabPagesHtmlReporter:pylint.html,colorized uffd

  artifacts:

    when: always

    paths:

      - pylint.txt

#unittest:

#  stage: test

#  script:

#  - python3 -m coverage run runTests.py

#  - python3 -m coverage report --include "./*"

#  - python3 -m coverage report -m  --include "./*" > report.txt

#  - python3 -m coverage html --include "./*"

#  artifacts:

#      paths:

#      - htmlcov/*

#      - .coverage

#      - report.txt

    - pylint.html

    reports:

      codequality: codeclimate.json

tests:buster:sqlite:

  image: registry.git.cccv.de/uffd/docker-images/buster

  stage: test

  needs: []

  script:

  - python3 -m pytest --junitxml=report.xml

  artifacts:

    when: always

    reports:

      junit: report.xml

tests:buster:mysql:

  image: registry.git.cccv.de/uffd/docker-images/buster

  stage: test

  needs: []

  script:

  - service mysql start

  - TEST_WITH_MYSQL=1 python3 -m pytest --junitxml=report.xml

  artifacts:

    when: always

    reports:

      junit: report.xml

tests:bullseye:sqlite:

  image: registry.git.cccv.de/uffd/docker-images/bullseye

  stage: test

  needs: []

  script:

  - python3 -m pytest --junitxml=report.xml

  artifacts:

    when: always

    reports:

      junit: report.xml

tests:bullseye:mysql:

  image: registry.git.cccv.de/uffd/docker-images/bullseye

  stage: test

  needs: []

  script:

  - service mariadb start

  - TEST_WITH_MYSQL=1 python3 -m pytest --junitxml=report.xml

  artifacts:

    when: always

    reports:

      junit: report.xml

tests:bookworm:sqlite:

  image: registry.git.cccv.de/uffd/docker-images/bookworm

  stage: test

  needs: []

  script:

  - rm -rf pages

  - mkdir -p pages

  - cp -r uffd/static pages/static

  - DUMP_PAGES=pages python3-coverage run --include 'uffd/*.py' -m pytest --junitxml=report.xml || touch failed

  - sed -i -e 's/href="\/static\//href=".\/static\//g' -e 's/src="\/static\//src=".\/static\//g' pages/*.html || true

  - python3-coverage report -m

  - python3-coverage html

  - python3-coverage xml

  - test ! -e failed

  artifacts:

    when: always

    paths:

    - htmlcov/index.html

    - htmlcov

    - pages

    expose_as: 'Coverage Report'

    reports:

      coverage_report:

        coverage_format: cobertura

        path: coverage.xml

      junit: report.xml

  coverage: '/^TOTAL.*\s+(\d+\%)$/'

tests:bookworm:mysql:

  image: registry.git.cccv.de/uffd/docker-images/bookworm

  stage: test

  needs: []

  script:

  - service mariadb start

  - TEST_WITH_MYSQL=1 python3 -m pytest --junitxml=report.xml

  artifacts:

    when: always

    reports:

      junit: report.xml

html5validator:

  stage: test

  needs:

  - job: tests:bookworm:sqlite

  script:

  - html5validator --root pages 2>&1 | tee html5validator.log

  artifacts:

    when: on_failure

    paths:

    - pages

    - html5validator.log

.trans:

  stage: test

  needs: []

  script:

  - ./update_translations.sh $TRANSLATION_LANGUAGE

  coverage: '/^TOTAL.*\s+(\d+\%)$/'

trans_de:

  extends: .trans

  variables:

    TRANSLATION_LANGUAGE: de

test:package:pip:buster:

  image: registry.git.cccv.de/uffd/docker-images/buster

  stage: test

  needs:

  - job: build:pip

  script:

  - pip3 install dist/*.tar.gz

test:package:pip:bullseye:

  image: registry.git.cccv.de/uffd/docker-images/bullseye

  stage: test

  needs:

  - job: build:pip

  script:

  - pip3 install dist/*.tar.gz

test:package:pip:bookworm:

  image: registry.git.cccv.de/uffd/docker-images/bookworm

  stage: test

  needs:

  - job: build:pip

  script:

  - pip3 install dist/*.tar.gz

# Since we want to test if the package installs correctly on a fresh Debian

# install (has correct dependencies, etc.), we don't use uffd/docker-images

# here

test:package:apt:buster:

  image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/debian:buster

  stage: test

  needs:

  - job: build:apt

  before_script: []

  script:

  - apt -y update

  - apt -y install curl ./*.deb

  - service uwsgi start uffd || ( service uwsgi status uffd ; sleep 15; cat /var/log/uwsgi/app/uffd.log; )

  - echo "server { listen 127.0.0.1:5000 default_server;  include /etc/uffd/nginx.include.conf; }" > /etc/nginx/sites-enabled/uffd.ini

  - service nginx start || ( service nginx status; nginx -t; exit 1; )

  - uffd-admin routes

  - curl -Lv 127.0.0.1:5000

test:package:apt:bullseye:

  image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/debian:bullseye

  stage: test

  needs:

  - job: build:apt

  before_script: []

  script:

  - apt -y update

  - apt -y install curl ./*.deb

  - service uwsgi start uffd || ( service uwsgi status uffd ; sleep 15; cat /var/log/uwsgi/app/uffd.log; )

  - echo "server { listen 127.0.0.1:5000 default_server;  include /etc/uffd/nginx.include.conf; }" > /etc/nginx/sites-enabled/uffd.ini

  - service nginx start || ( service nginx status; nginx -t; exit 1; )

  - uffd-admin routes

  - curl -Lv 127.0.0.1:5000

test:package:apt:bookworm:

  image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/debian:bookworm

  stage: test

  needs:

  - job: build:apt

  before_script: []

  script:

  - apt -y update

  - apt -y install curl ./*.deb

  - service uwsgi start uffd || ( service uwsgi status uffd ; sleep 15; cat /var/log/uwsgi/app/uffd.log; )

  - echo "server { listen 127.0.0.1:5000 default_server;  include /etc/uffd/nginx.include.conf; }" > /etc/nginx/sites-enabled/uffd.ini

  - service nginx start || ( service nginx status; nginx -t; exit 1; )

  - uffd-admin routes

  - curl -Lv 127.0.0.1:5000

.publish:

  stage: deploy

  rules:

    - if: '$CI_COMMIT_TAG =~ /v[0-9]+[.][0-9]+[.][0-9]+.*/'

publish:pip:

  extends: .publish

  script:

  - TWINE_USERNAME="${GITLABPKGS_USERNAME}" TWINE_PASSWORD="${GITLABPKGS_PASSWORD}" python3 -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*

  - TWINE_USERNAME="${PYPI_USERNAME}" TWINE_PASSWORD="${PYPI_PASSWORD}" python3 -m twine upload dist/*

  dependencies:

  - build:pip

publish:apt:

  extends: .publish

  script:

  - export DEBPATH="$(echo *.deb)"

  - echo Upload deb file, add it to repo and clean up upload

  - curl --user "${APTLY_API_USER}:${APTLY_API_PW}" -X POST -F file=@"$DEBPATH" "${APT_API_URL}/api/files/${APT_REPO}-ci-upload-${CI_JOB_ID}"

  - curl --user "${APTLY_API_USER}:${APTLY_API_PW}" -X POST "${APT_API_URL}/api/repos/${APT_REPO}/file/${APT_REPO}-ci-upload-${CI_JOB_ID}"

  - curl --user "${APTLY_API_USER}:${APTLY_API_PW}" -X DELETE "${APT_API_URL}/api/files/${APT_REPO}-ci-upload-${CI_JOB_ID}"

  - echo Update published repo for all distros

  - 'curl --user "${APTLY_API_USER}:${APTLY_API_PW}" -X PUT -H "Content-Type: application/json" --data "{ }" "${APT_API_URL}/api/publish/uffd/buster"'

  - 'curl --user "${APTLY_API_USER}:${APTLY_API_PW}" -X PUT -H "Content-Type: application/json" --data "{ }" "${APT_API_URL}/api/publish/uffd/bullseye"'

  - 'curl --user "${APTLY_API_USER}:${APTLY_API_PW}" -X PUT -H "Content-Type: application/json" --data "{ }" "${APT_API_URL}/api/publish/uffd/bookworm"'

  dependencies:

  - build:apt

# Use multiple processes to speed up Pylint. Specifying 0 will auto-detect the

# number of processors available to use.

jobs=1

jobs=0

# Control the amount of potential inferred values when inferring a single

# object. This can help the performance when dealing with large functions or

# List of plugins (as comma separated values of python module names) to load,

# usually to register additional checkers.

load-plugins=

load-plugins=pylint_flask_sqlalchemy

# Pickle collected data for later comparisons.

persistent=yes

disable=missing-module-docstring,

        missing-class-docstring,

        missing-function-docstring,

        print-statement,

        parameter-unpacking,

        unpacking-in-except,

        old-raise-syntax,

        backtick,

        long-suffix,

        old-ne-operator,

        old-octal-literal,

        import-star-module-level,

        non-ascii-bytes-literal,

        raw-checker-failed,

        bad-inline-option,

        locally-disabled,

        file-ignored,

        suppressed-message,

        useless-suppression,

        deprecated-pragma,

        use-symbolic-message-instead,

        unused-wildcard-import,

        apply-builtin,

        basestring-builtin,

        buffer-builtin,

        cmp-builtin,

        coerce-builtin,

        execfile-builtin,

        file-builtin,

        long-builtin,

        raw_input-builtin,

        reduce-builtin,

        standarderror-builtin,

        unicode-builtin,

        xrange-builtin,

        coerce-method,

        delslice-method,

        getslice-method,

        setslice-method,

        no-absolute-import,

        old-division,

        dict-iter-method,

        dict-view-method,

        next-method-called,

        metaclass-assignment,

        indexing-exception,

        raising-string,

        reload-builtin,

        oct-method,

        hex-method,

        nonzero-method,

        cmp-method,

        input-builtin,

        round-builtin,

        intern-builtin,

        unichr-builtin,

        map-builtin-not-iterating,

        zip-builtin-not-iterating,

        range-builtin-not-iterating,

        filter-builtin-not-iterating,

        using-cmp-argument,

        eq-without-hash,

        div-method,

        idiv-method,

        rdiv-method,

        exception-message-attribute,

        invalid-str-codec,

        sys-max-int,

        bad-python3-import,

        deprecated-string-function,

        deprecated-str-translate-call,

        deprecated-itertools-function,

        deprecated-types-field,

        next-method-defined,

        dict-items-not-iterating,

        dict-keys-not-iterating,

        dict-values-not-iterating,

        deprecated-operator-function,

        deprecated-urllib-function,

        xreadlines-attribute,

        deprecated-sys-function,

        exception-escape,

        comprehension-escape,

        too-few-public-methods,

        method-hidden,

        bad-continuation,

        too-many-ancestors,

        duplicate-code,

        redefined-builtin,

        superfluous-parens,

        consider-using-f-string, # Temporary

# Enable the message, report, category or checker with the given id(s). You can

# either give multiple identifier separated by comma (,) or put this option

ignore-imports=no

# Minimum lines number of a similarity.

min-similarity-lines=4

min-similarity-lines=6

[TYPECHECK]

# List of members which are set dynamically and missed by pylint inference

# system, and so shouldn't trigger E1101 when accessed. Python regular

# expressions are accepted.

generated-members=

generated-members=query,UniqueConstraint

# Tells whether missing members accessed in mixin class should be ignored. A

# mixin class is detected if its name ends with "mixin" (case insensitive).

# Maximum number of lines in a module.

max-module-lines=1000

# List of optional constructs for which whitespace checking is disabled. `dict-

# separator` is used to allow tabulation in dicts, etc.: {1  : 1,\n222: 2}.

# `trailing-comma` allows a space between comma and closing bracket: (a, ).

# `empty-line` allows space-only lines.

no-space-check=trailing-comma,

               dict-separator

# Allow the body of a class to be on the same line as the declaration if body

# contains single statement.

single-line-class-stmt=no

max-args=7

# Maximum number of attributes for a class (see R0902).

max-attributes=7

max-attributes=12

# Maximum number of boolean expressions in an if statement (see R0916).

max-bool-expr=5

# Maximum number of branch for function / method body.

max-branches=12

max-branches=15

# Maximum number of locals for function / method body.

max-locals=15

# Exceptions that will emit a warning when being caught. Defaults to

# "BaseException, Exception".

overgeneral-exceptions=BaseException,

                       Exception

overgeneral-exceptions=builtin.BaseException,

                       builtin.Exception

include setup.py

recursive-include uffd *.py *.html *.js *.css *.txt *.po *.cfg

graft uffd/migrations

graft uffd/templates

graft uffd/*/templates

graft uffd/static/

graft uffd/translations

# uffd

# Uffd

This is the UserFrwaltungsFrontend.

A web service to manage LDAP users, groups and permissions.

Uffd (UserFerwaltungsFrontend) is a web-based user management and single sign-on software.

Development chat: [#uffd-development](https://rocket.cccv.de/channel/uffd-development)

## Dependencies

Please note that we refer to Debian packages here and **not** pip packages.

## dependencies

- python3

- python3-ldap3

- python3-flask

- python3-flask-sqlalchemy

- python3-flask-migrate

- python3-qrcode

- python3-fido2 (version 0.5.0 or 0.9.1, optional)

- python3-prometheus-client (optional, needed for metrics)

- python3-jwt

- python3-cryptography

- python3-flask-babel

- python3-argon2

- python3-itsdangerous (also a dependency of python3-flask)

- python3-mysqldb or python3-pymysql for MariaDB support

- python3-ua-parser (optional, better user agent parsing)

Some 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 supplied `requirements.txt`.

## Development

Before running uffd, you need to create the database with `flask db upgrade`. The database is placed in

`instance/uffd.sqlit3`.

Then use `flask run` to start the application:

```

FLASK_APP=uffd flask db upgrade

FLASK_APP=uffd FLASK_ENV=development flask run

```

During 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".

## Deployment

Do not use `pip install uffd` for 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 main

```

Then download [cccv-archive-key.gpg](https://packages.cccv.de/docs/cccv-archive-key.gpg) and add it to the trusted repository keys in `/etc/apt/trusted.gpg.d/`.

Afterwards run `apt update && apt install uffd` to install the package.

The Debian package uses uwsgi to run uffd and ships an `uffd-admin` script to execute flask commands in the correct context.

If you upgrade, make sure to run `flask db upgrade` after every update! The Debian package takes care of this by itself using uwsgi pre start hooks.

For an example uwsgi config, see our [uswgi.ini](uwsgi.ini). You might find our [nginx include file](nginx.include.conf) helpful to setup a web server in front of uwsgi.

Uffd supports SQLite and MariaDB. To use MariaDB, create the database with the options `CHARACTER SET utf8mb4 COLLATE utf8mb4_nopad_bin` and make sure to add the `?charset=utf8mb4` parameter to `SQLALCHEMY_DATABASE_URI`.

## Python Coding Style Conventions

PEP 8 without double new lines, tabs instead of spaces and a max line length of 160 characters.

We ship a [pylint](https://pylint.org/) config to verify changes with.

## Configuration

Uffd reads its default config from `uffd/default_config.cfg`.

You can overwrite config variables by creating a config file in the `instance` folder.

The file must be named `config.cfg` (Python syntax), `config.json` or `config.yml`/`config.yaml`.

You can also set a custom file path with the environment variable `CONFIG_PATH`.

## OAuth2 Single-Sign-On Provider

Other 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 user

If the service supports server metadata discovery ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)), configuring the base url of your uffd installation or `/.well-known/openid-configuration` as the discovery endpoint should be sufficient.

The only OAuth2 scope supported is `profile`. 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"

  ],

}

```

`id` is the numeric (Unix) user id, `name` the display name and `nickname` the loginname of the user.

## OpenID Connect Single-Sign-On Provider

In addition to plain OAuth2, uffd also has basic OpenID Connect support.

Endpoint URLs are the same as for plain OAuth2.

OpenID Connect support is enabled by requesting the `openid` scope.

ID token signing keys are served at `/oauth2/keys`.

See [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) specification for more details.

Supported flows and response types:

* Only Authorization Code Flow with `code` response type

Supported scopes:

* `openid`: Enables OpenID Connect support and returns mandatory `sub` claim

* `profile`: Returns `name` and `preferred_username` claims

* `email`: Returns `email` and `email_verified` claims

* `groups`: Returns non-standard `groups` claim

Supported claims:

* `sub` (string): Decimal encoded numeric (Unix) user id

* `name` (string): Display name

* `preferred_username`(string): Loginname

* `email` (string): Service-specific or primary email address

* `email_verified` (boolean): Verification status of `email` value (always `true`)

* `groups` (array of strings): Names of groups the user is a member of (non-standard)

uffd supports the optional `claims` authorization request parameter for requesting claims individually.

Note that there is a IANA-registered `groups` claim with a syntax borrowed from [SCIM](https://www.rfc-editor.org/rfc/rfc7643.html).

The syntax used by uffd is different and incompatible, although arguably more common for a claim named "groups" in this context.

uffd aims for complience with OpenID provider conformance profiles Basic and Config.

It is, however, not a certified OpenID provider and it has the following limitations:

* Only the `none` value for the `prompt` authorization request parameter is recognized. Other values (`login`, `consent` and `select_account`) are ignored.

* The `max_age` authorization request parameter is not supported and ignored by uffd.

* The `auth_time` claim is not supported and neither returned if the `max_age` authorization request parameter is present nor if it is requested via the `claims` parameter.

* Requesting the `sub` claim with a specific value for the ID Token (or passing the `id_token_hint` authorization request parameter) is only supported if the `prompt` authorization request parameter is set to `none`. The authorization request is rejected otherwise.

## Metrics

Uffd can export metrics in a prometheus compatible way. It needs python3-prometheus-client for this feature to work.

Metrics can be accessed via `/metrics` and `/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 the `metrics` permission. 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

[..]

```

## Translation

The web frontend is initially written in English and translated in the following Languages:

![status](https://git.cccv.de/uffd/uffd/badges/master/coverage.svg?job=trans_de&key_text=DE)

## deployment

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 uwsgi.

Use the `update_translations.sh` to update the translation files.

## python style conventions

## License

tabs.

GNU Affero General Public License v3.0, see [LICENSE](LICENSE).

# Upgrading from v1 to v2

Prior to v2 uffd stored users, groups and mail aliases on an LDAP server.

OAuth2 and API client credentials were defined in the config. Starting with

v2 uffd stores all of this in its database and no longer supports LDAP.

A number of other features and configurations are no longer supported. See the

changelog for details on changed and removed features.

## Preparations

Create a backup of the database before attempting an upgrade. The database

migration scripts are quite complex and somewhat fragile. If anything fails,

you will end up with a broken database that is difficult or impossible to

recover from. Furthermore downgrading from v2 to v1 is not supported.

Make sure no service (besides uffd) directly accesses your LDAP server.

Migrate any remaining services to [uffd-ldapd][] or other solutions that

solely rely on uffds API and OAuth2 endpoints. Uffd will cease to update

any data stored in the LDAP directory.

Migrate all API clients defined with the `API_CLIENTS` config option to the

`API_CLIENTS_2` option. This includes changing authentication from a

token-based mechanism to HTTP Basic Authentication and consequently replacing

affected credentials.

The imported OAuth2 and API clients are grouped by service objects. These

service objects will be auto-created for each client with unique names derived

from the `client_id` parameter. Add the `service_name` parameter to clients to

set a custom name. This name is visible to users in place of the OAuth2

`client_id`. Use the same `service_name` for multiple clients to group them

together. This is recommended for OAuth2 and API credentials used by the same

services, as future features like service-specific email addresses will be

added as service-level options. The OAuth2 client parameter `required_group` is

imported as a service-level option. Make sure that grouped OAuth2 clients have

the same `required_group` value, otherwise nobody will be able to access the

service. Note that values other than a single group name are not supported.

Adjust the ACLs of your LDAP server so uffd can read the `userPassword`

attribute of user objects. Note that uffd will not perform any writes to the

LDAP server during or after the upgrade.

If you use user bind (config option `LDAP_SERVICE_USER_BIND`), i.e. if you

have uffd authenticate with the LDAP server using the credentials of the

currently logged in user, you will have to replace this configuration and

grant uffd full read access to all user, group and mail alias data with

config-defined credentials.

Install the new dependency `python3-argon2`. (Dist-)Upgrading the Debian

package will do that for you. Do not uninstall the removed dependency

`python3-ldap3` (i.e. do not run `apt autoremove`)! It is required to import

data from the LDAP server.

There is a safeguard in place to prevent accidental upgrades. Add the

following line to your config file to disable the safeguard:

```

UPGRADE_V1_TO_V2=True

```

## Running the Upgrade

Upgrade the Debian package to v2. This will restart the uffd UWSGI app. With

the default UWSGI configuration, the database migration scripts will run