Overview

A Multi-Scrobbler instance deployed with minimal configuration (like from Quickstart) is generally a low security risk when used in a private, secured network like your local LAN, a VPN/tailscale, etc…where it has no additional exposure to the internet.

However, if you plan to expose Multi-Scrobbler publicly or on a network you do not fully trust you need to take additional steps to secure your instance.

Tip

Even in a secure network you should still secure your instance!

Why Secure It?

Abusive Actions

Currently, there are no destructive actions that can be taken in multi-scrobbler but that will likely change in the near future.

Even without destructive actions, an actor can trigger bulk scrobble/retries that exhaust rate limits for things like tealfm or cause you to be blocked for excessive activity for services like listenbrainz/musicbrainz.

Personally Identifiable Information (PII)

Exposing an insecure MS instance can potentially leak personally identifiable information. Consider:

• some Services, like Spotify, have descriptive device names that can be seen in MS like bobs-android-auto or marys-apartment-roku
  • these can potentially tell a bad actor where you are or what you are currently not doing (at home? in the car?)
  • if the device name is named after a location it’s even worse, like an airbnb: 123-fun-street-samsung-tv

This is information is generally accessible when your instance is insecure. It is not accessible from the Public Dashboard or when the instance is secured.

Habit Tracking

Exposing an insecure MS instance can potentially leak your personal habits Consider:

• general listening activity can be a sign of your daily routine
  • EX listening usually stops at 11:45pm -> you go to sleep before midnight
  • EX high listening activity between 7:30 - 8:30am -> you are commuting

This is information is generally accessible when your instance is insecure.

On secure instances this is also a risk if you enable the Public Dashboard and choose to use Now Playing: enabling this with a low refresh interval (near realtime, EX 5-10 minutes) allows someone to track when your activity changes and infer your habits. You should only enable these settings if this an acceptable risk to you.

You can generally avoid this by not using the Public Dashboard’s Now Playing feature and keeping the refresh interval reasonably high (an hour or longer).

Embedding the Public Dashboard

Allow Embedding (in the Public Dashboard settings) lets other sites show parts of the (enabled) Public Dashboard in an iframe of /embed.

Things to consider before enabling it:

• Every visitor of the site embedding it connects to your MS instance. MS (and anything in front of it like a reverse proxy) sees their IP addresses and which page they are on. If you run that site you may need to mention this to your visitors.
• The site makes the address of your MS instance public, so expect more automated traffic like scanners and login attempts. Keep your instance secured.
• With Now Playing enabled every visitor’s iframe refreshes as often as the Refresh interval allows, which adds load to your instance. See Habit Tracking above for the risks of short intervals.
• By default any site can embed it. Use Allowed Sites to limit it to your own sites (EX https://blog.example.com or https://*.example.com).

Securing Multi-Scrobbler

There are two primary ways to secure your instance, set through the ENV AUTH_MODE or AIO auth.mode config.json.

Mode	Behavior
default	Built-In Authentication is dormant until an admin password is set, from the dashboard or ENV ADMIN_SETUP_PW.
disabled	No authentication (Bring Your Own Auth). Use when behind an authenticated reverse proxy or authelia/keycloak/tinyauth/etc…

Built-in Authentication

Built-in Authentication (AUTH_MODE=default) uses hardened Better-Auth to lock down all the API endpoints for Multi-Scrobbler. All authentication and account management is done through MS settings/configuration that lives in your database, config, or ENVs.

Tip

When no other Auth related config is set, built-in authentication is automatically used.

Multi-Scrobbler starts in a “default open” state where the dashboard/API are accessible until an admin password is set. You can set this by visiting the dashboard at any time (but you should do it as soon as possible!)

In some configurations an automatically generated setup token is required to set the password and secure your instance. After setting the password your instance is secured and dashboard/API access is auth gated, only accessible by the logged in user or through an API Key.

Read more about how this works in the Built-in Authentication docs.

Bring Your Own Auth (BYOA)

With BYOA mode (AUTH_MODE=disabled) Multi-Scrobbler functions closely to the way it did before authentication was introduced. In other words, access to the dashboard and all API endpoints is always open. There is no Account, password, API Keys, etc… to manage or configure.

Important

In this mode you are expected to provide some form of security in front of MS.

Failing to do so can lead to scenarios outlined in Why Secure It?

Tip

Use this if you already have an authenticated reverse proxy with something like Authelia/Authentik/Keycloak/Tinyauth etc…

Note

Be aware that BYOA mode effectively locks you in to a single-user operating mode. MS will likely support multiple users in the future at which point users using BYOA mode will not be able to take advantage of this.

Guide: Reverse Proxy With BYOA Mode

Use a reverse proxy with some kind of authentication gate. Optionally, restrict the gate to protect all routes that are not related to ingress.

The simplest (and least secure) version of this would be using basic auth.

• Traefik basic auth
• NPM auth gateway or nginx basic auth
• Caddy basic auth

Note

Optimally, you should be using a more robust authentication implementation IE tinyauth, authentik, keycloak, etc… that integrates into your reverse proxy.

Tip

Reference the Open Endpoints section in the Authentication docs to see which routes need to be unprotected for Sources to work.

Below are examples of protecting all non-ingress routes with basic auth for the above reverse proxies.

Traefik

Using a file provider:

http:
  routers:
    ms-route:
      entryPoints:
        - "websecure"

      rule: >
        Host(`ms.mydomain.com`) && (

        !PathPrefix(`/1/`)
        && !PathPrefix(`/api/listenbrainz`)

        && !PathPrefix(`/api/webscrobbler`)

        && !PathPrefix(`/2.0/`)
        && !PathPrefix(`/api/lastfm`)

        )

      middlewares:
        - ms-auth
      service: ms-service
  services:
    ms-service:
      loadBalancer:
        servers:
        - url: "http://multi-scrobbler:9078"
  middlewares:
    ms-auth:
      basicAuth:
        users:
        - "testUsername:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"

Show all 32 lines

1. 1.can remove any set in the parenthesis group that is unused. Order: LZ endpoint, webscrobbler, LFM endpoint. If not using any then leave only Host(...)
2. 2.can use container/docker service name if traefik and MS are on the same docker network, otherwise replace domain with the host IP
3. 3.use htpasswd cli to generate password, or the htpasswd generator tool in self-hosted it-tools

The above could also be done using docker provider labels.

Caddy

multi-scrobbler.domain.tld {
  @if-not-scrobble {
    not path /1/* /api/listenbrainz* /api/webscrobbler* /2.0/* /api/lastfm*
  }
  basic_auth @if-not-scrobble {
    msUser $2a$14$.UWNn4Zn.cQHY6Z1mkXXrOhO7mg4BC2wiC.4Tb8dNBMidjSRHAw3e
  }
  reverse_proxy multi-scrobbler:9078
}

1. 1.remove any paths you are NOT using. Order: LZ, LZ, WebScrobbler, LFM, LFM
2. 2.if request is to any route not listed above, force client to basic auth. You must hash your password using caddy hash-password
3. 3.requests will be proxied if they are to a scrobble endpoint or basic auth has been passed. Can use container/service name if Caddy & MS are on the same docker network, otherwise replace multi-scrobbler with host IP

Additional Measures

These other options are available in addition to what is outlined in Securing Multi-Scrobbler.

Run Headless

If you do not need any Ingress-based Sources like Webscrobbler, Listenbrainz Endpoint, or Last.fm Endpoint and are running MS in a Docker container, you can run MS headless by removing the exposed port from the compose file.

Note: this will also remove your ability to access the dashboard or use ingress Sources.

services:
  multi-scrobbler:
  # ...
  # comment out ports section
  #
  # ports:
  #  - 9078:9078

Restrict Docker Port Binding

Lock the exposed port to a specific IP address so that it can’t be accessed from other interfaces:

services:
  multi-scrobbler:
  # ...
   ports:
    # only accessible from private ip or tailscale ip
    - 192.168.0.101:9078:9078

Disable Web Server

Use the Disable Web option to completely disable the web server. This is useful if you are not using the docker image or cannot control port exposure in your environment.

Note: this will also remove your ability to access the dashboard or use ingress Sources.

Alternative for Listenbrainz Endpoint

For Subsonic-based music services (like Navidrome) you can use a Subsonic Source instead of a Listenbrainz Endpoint to avoid needing ingress.