claudeandClaude Opus 5.5 fc3120ee3f OpenID Connect login for Funkwhale as a plugin
Turns on django-allauth's generic openid_connect provider, which
Funkwhale already ships, and wires it to Funkwhale accounts: actor and
libraries on first login, admin by username or group, optional link by
e-mail. The front assets add a login button to the web app and proxy
/accounts/ to the API. Tested end to end against Funkwhale 2.0.13 and
Dex v2.44.0 (tests/compose.yaml).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 15:14:33 -05:00

funkwhale-oidc

OpenID Connect login for Funkwhale 2.x, packaged as a Funkwhale plugin. You don't need to fork Funkwhale or build a custom image. It works with Dex, Keycloak, Authentik, Authelia, or any other OIDC provider that has a discovery document.

Funkwhale already ships django-allauth. This plugin turns on allauth's generic openid_connect provider and connects it to Funkwhale's accounts:

  • New users are created on first login, with a username taken from preferred_username. They get a federation actor and default libraries, the same as Funkwhale's own sign-up. This works even when the instance's sign-up form is closed, because the provider decides who can get in.
  • Admins can be granted from a list of usernames or from a groups claim.
  • Existing local accounts can optionally be linked by verified e-mail address.
  • The web app gets a "Log in with …" button on every login form. It can also send /login straight to the provider; /login?local=1 still shows the password form.

Tested with Funkwhale 2.0.13 (django-allauth 65.14.1) and Dex v2.44.0.

Install

The plugin has two parts. The Python package goes on the API side (api, celery worker and celery beat). A small script and stylesheet go on the front side (the nginx image).

API

Install the package and PyJWT into FUNKWHALE_PLUGINS_PATH (default /srv/funkwhale/plugins/). Funkwhale adds that path to sys.path. The Funkwhale image does not include PyJWT, which allauth's OIDC provider needs.

pip install --target /srv/funkwhale/plugins \
  https://gitea.eom.dev/DevOps/funkwhale-oidc/archive/v0.1.0.tar.gz

In containers, run this as an init step into a shared volume. tests/compose.yaml shows how.

Then set:

Variable Default
FUNKWHALE_PLUGINS must include funkwhale_oidc
FUNKWHALE_OIDC_SERVER_URL required: issuer URL, e.g. https://dex.example.com/
FUNKWHALE_OIDC_CLIENT_ID required
FUNKWHALE_OIDC_CLIENT_SECRET required
FUNKWHALE_OIDC_PROVIDER_ID oidc appears in the callback URL
FUNKWHALE_OIDC_NAME Single sign-on provider name shown to users
FUNKWHALE_OIDC_SCOPES openid,profile,email add groups for ADMIN_GROUPS
FUNKWHALE_OIDC_PKCE true
FUNKWHALE_OIDC_USERNAME_CLAIM preferred_username becomes the username and @user@host handle, so it must be ASCII
FUNKWHALE_OIDC_SIGNUP true create accounts for new provider users
FUNKWHALE_OIDC_LINK_BY_EMAIL false log into an existing local account with the same verified e-mail; only enable this for a provider you trust
FUNKWHALE_OIDC_ADMIN_USERS comma-separated usernames made superuser at login
FUNKWHALE_OIDC_ADMIN_GROUPS comma-separated groups (from FUNKWHALE_OIDC_GROUPS_CLAIM, default groups) that grant superuser

Admin rights are only ever granted, never revoked; remove them in Funkwhale's admin.

Register this redirect URI with the provider:

https://<funkwhale host>/accounts/oidc/<FUNKWHALE_OIDC_PROVIDER_ID>/login/callback/

Front

The front image needs three changes:

The files are in the package under funkwhale_oidc/front/, so the same pip install --target provides them.

  1. Mount oidc-login.js and oidc-login.css at /usr/share/nginx/html/oidc/.
  2. Mount inject.sh as /docker-entrypoint.d/98-funkwhale-oidc.sh. At startup it:
    • adds the script to index.html;
    • proxies /accounts/ to the API, which the stock config sends to the web app instead.
  3. Set these on the front container:
    • FUNKWHALE_OIDC_PROVIDER_ID and FUNKWHALE_OIDC_NAME, with the same values as on the API.
    • FUNKWHALE_OIDC_AUTO_REDIRECT: optional, true to skip the password form on /login.

If you use your own nginx in front of the API, add this instead:

location /accounts/ { include /etc/nginx/funkwhale_proxy.conf; proxy_pass http://funkwhale-api; }

Set FUNKWHALE_SPA_HTML_ROOT to the front's internal URL (e.g. http://funkwhale-front/). The API then serves the same index.html, with the script, on the pages it renders itself, such as /library/albums/1.

Notes

  • Logging out of Funkwhale doesn't log you out of the provider. That's why auto-redirect only applies to /login, so "log out" doesn't bounce you straight back in.
  • Username clashes: if the claimed username is already taken locally, or isn't valid ASCII, allauth shows its own basic sign-up form so the user can pick another.
  • Funkwhale upgrades: the plugin uses funkwhale_api.users.models.create_actor and create_user_libraries, and the front script looks for #username-field. Run the end-to-end test after upgrading Funkwhale.

Test

docker compose -f tests/compose.yaml up -d
# http://funkwhale.localhost/login → "Log in with Dex" → admin@example.com / password
docker compose -f tests/compose.yaml down -v

This brings up Funkwhale (api, worker, front), PostgreSQL, Redis and a throwaway Dex, with the plugin installed exactly as described above.

License

AGPL-3.0-or-later, the same as Funkwhale, whose code this plugin imports.

S
Description
Plugin for Funkwhale to add OIDC
Readme AGPL-3.0
68 KiB
Languages
Python 60.5%
JavaScript 22.2%
Shell 13.3%
CSS 4%