claudeandClaude Opus 5.5 a29293bd7e Bump the service worker's index.html revision after injecting
Funkwhale's service worker precaches index.html by a build-time revision,
so returning visitors kept the unmodified page. inject.sh now writes the
modified page's hash into serviceWorker.js, which makes browsers install
the updated worker and fetch the new page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 15:48:32 -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.
  • Local login can be turned off entirely (FUNKWHALE_OIDC_LOCAL_LOGIN=false).
    • The server rejects password login, sign-up and password reset/change, in the API, in allauth's pages and in the Django admin.
    • The web app shows only the provider button and sends /login and /signup to the provider.
    • Subsonic app tokens and OAuth apps keep working.

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.2.1.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_LOCAL_LOGIN true false: the provider is the only way in. Recover with funkwhale-manage in the API container
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.
    • FUNKWHALE_OIDC_LOCAL_LOGIN: the same value as on the API.

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      # LOCAL_LOGIN=false to test that mode
# 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%