# 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:///accounts/oidc//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.