With it false, a middleware rejects password login, sign-up and password reset/change in the API, allauth's pages and the Django admin, and the web app shows only the provider button. /login and /signup go straight to the provider, and the post-login redirect never points back at them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.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_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.