squirrel-group-manager

A tool to help manage groups in Authentik and their related mailinglists hosted by all-inkl. It'll take Authentik as source of truth and can

• notify admins about group memberships
• create, configure and re-sync mailinglist configuration & subscribers based on authentik groups

Getting started

This assumes you have an Authentik instance set up and an account by all-inkl.

Installation

First clone the repository

git clone https://code.hyteck.de/moanos/squirrel-group-manager.git

Then install the tool

pip install .

Then create a file called squirrel.cfg in your working directory and configure like this

[authentik]
base_url = https://login.neustart-solewo.de
token = MySecretToken

[email]
sender_email = technik@neustart-solewo.de
smtp_password = VerySecretPassword
smtp_server = w0XXXXXXX.kasserver.com

[kas]
login=w01XXXXXX
password=OtherVerySecretPassword

You can now try to run the tool.

Commands

The tool can be used with squirrel. squirrel -h will show the following help. Appending -h to any command will show details on the command and available arguments.

usage: squirrel [-h] [-v] {status,notify,diff,apply} ...

A tool to help manage groups in Authentik and their related mailinglists hosted by all-inkl

positional arguments:
  {status,notify,diff,apply}
    status              Shows information on current configuration of the tool, authentik and mailinglists.
    notify              Sends an e-mail with all group admins in authentik, notifying them of the current group members. Admins are defined by custom attributes in Authentik
    diff                Show the difference between the authentik configuration and all-inkl mailinglists
    apply               Apply the authentik configuration to all-inkl mailinglists

options:
  -h, --help            show this help message and exit
  -v, --verbose

Notify

The command squirrel notify will produce e-mails that look like this:

Pressing the button "Änderung mitteilen" will open the e-mail client with a pre-configured e-mail:

Hallo Technik-AG, ich würde gerne die Mitglieder der Gruppe AG_IT aktualisieren.

Hinzufügen: (hier Name und E-Mail Adresse einfügen)

Entfernen: (hier Name und E-Mail Adresse einfügen)

Diff

Shows the diff between the mailinglist members defined in authentik and all-inkl

I'll then ask if you want to apply the changes. It'll show you the removed and added members and replace them if you confirm.

Apply

Apply allows to specify a list via --listname. It'll then immediately write the mailinglist configuration ( subscribers, configuration file) to all-inkl.

• ⚠️ The list must already exist in all-inkl
• The list must be configured in Authentik
• listname must be the full name of the list in all-inkl for example mailinglist-name-example-org

Authentik setup

You can use the groups additional properties in authentik to add information to the group.

Mandatory are: name, title, domain and subject_prefix

group-admin:
  - id: 42
    name: moanos
mailinglist:
  - name: name-without-domain
    title: My Mailinglist Title
    domain: neustart-solewo.de
    subject_prefix: MyMail
    additional-members:
      - test@example.org

Limitations

This tool is a custom build for Neustart. Here are some limitations you need to work around

• 2FA enabled for all-inkl: The first step in the all-inkl api where you get a session token might fail if you send 2FA information (not tested)
• Mailinglist Configuration: The template in src/squirrel/templates/group-management/kas/majordomo-config.j2 hardcodes values (e.g. footer text) to be Neustart-specific. To change that you'd need to adjust this file.

Migration

You likely have a setup where you manually add members to groups in authentik and then also manually add them to the respective mailinglist in all-inkl. You mailinglist configuration is likely copy-pasted each time you set up a mailinglist. You can now migrate step by step. First, create a test group in authentik. Now, try the diff action. You should be able to create the mailinglist in all-inkl with their respective members. When that works, check the configuration the tool created for the mailinglist. Compare with your existing configuration and make necessary adjustments.

If all that looks good and the test mailinglist works as expected, you can start to add "migrate" existing mailinglists by adding the necessary additional properties in the authentik group. After that, you can again use the diff tool to compare all-inkl and authentik. If you press a for apply, the authentik information will overwrite the all-inkl configuration.

Do this one-by-one to finish the migration.