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>
5.7 KiB
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
/loginstraight to the provider;/login?local=1still 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
/loginand/signupto 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.
- Mount
oidc-login.jsandoidc-login.cssat/usr/share/nginx/html/oidc/. - Mount
inject.shas/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.
- adds the script to
- Set these on the front container:
FUNKWHALE_OIDC_PROVIDER_IDandFUNKWHALE_OIDC_NAME, with the same values as on the API.FUNKWHALE_OIDC_AUTO_REDIRECT: optional,trueto 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_actorandcreate_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.