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>
102 lines
5.7 KiB
Markdown
102 lines
5.7 KiB
Markdown
# funkwhale-oidc
|
|
|
|
OpenID Connect login for [Funkwhale](https://funkwhale.audio) 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.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```nginx
|
|
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
|
|
|
|
```sh
|
|
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.
|