Getting Started

• 1: Externalized Authentication Quick Start
• 2: Anonymous Data Collection

1 - Externalized Authentication Quick Start

What is externalized authentication

Externalized authentication allows you to use an external system to handle authentication for Navidrome. Instead of managing user credentials in Navidrome itself, the responsibility is delegated to an external authentication service.

The external system comprises a reverse proxy (nginx, Caddy, Traefik, etc.) and an authentication service (Authelia, Authentik, or any other authentication service that works with your reverse proxy).

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    User     │ --> │   Reverse   │ --> │  Navidrome  │
│   Browser   │     │    Proxy    │     │    Server   │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                          V
                    Authentication
                        Service

Navidrome supports a header-based mechanism to retrieve data about the authenticated user from the reverse proxy.

This approach is usually called “reverse proxy authentication”, and offers several benefits:

• Increased flexibility: Leverage authentication methods not supported by Navidrome (LDAP, OAuth, 2FA, etc.)
• Single Sign-On (SSO): Users can login once and access multiple services
• Centralized user management: Manage all your users in one place

How It Works

1. Your reverse proxy authenticates the user
2. The proxy adds a header with the username (e.g., Remote-User: john) to the request, then forwards it to Navidrome
3. Navidrome checks that the request comes from a trusted IP (using ExtAuth.TrustedSources, more on that below)
4. If trusted, Navidrome uses the username from the header to identify the user
5. If the user doesn’t exist in Navidrome’s database, a new account is created automatically

Quick Start

Here’s the basic process for setting up externalized authentication:

1. Configure your reverse proxy with authentication. The integration depend on the proxy and authentication service.
2. Configure the reverse proxy to pass the username to Navidrome via an HTTP header. It should additionally be configured to prevent clients from setting the header themselves.
3. Configure Navidrome to trust your reverse proxy as authentication source.
4. (Optional) Configure the reverse proxy to allow unauthenticated requests on specific paths. This is only needed for some Navidrome features.
5. Test the setup

Basic Navidrome Configuration

By default, externalized authentication is disabled. To enable it:

1. Set the ExtAuth.TrustedSources option to tell Navidrome which IP address to trust.
2. Optionally customize the ExtAuth.UserHeader option if your proxy uses a different header than the default Remote-User

In your Navidrome configuration:

## IP address of your reverse proxy (CIDR notation)
ND_EXTAUTH_TRUSTEDSOURCES=192.168.1.10/32
## Optional: Change the header if needed (this is the default)
ND_EXTAUTH_USERHEADER=Remote-User

Special Value for UNIX Sockets

If you’re using UNIX sockets (with the Address option), use @ in your ExtAuth.TrustedSources option to accept the authentication header of requests from the socket:

ND_ADDRESS=/var/run/navidrome.sock
ND_EXTAUTH_TRUSTEDSOURCES=@

User Management

When using externalized authentication:

• The first user authenticated through the proxy will be granted admin privileges (just like the first user in a fresh installation)
• New users are created automatically with random passwords

You can also consider setting EnableUserEditing=false to prevent users from changing their Navidrome passwords (since they’re managed by your auth service):

# Disable password editing in Navidrome
ND_ENABLEUSEREDITING=false

Reverse Proxy Integration

The integration depends on your chosen reverse proxy and authentication service, so you should first get familiar with their documentation.

Some Navidrome features also require specific configuration of your reverse proxy:

• Public Shares: If you plan to use Navidrome’s sharing feature (for creating public links to your library), you need to configure your reverse proxy to bypass authentication for URLs starting with /share/, allowing unauthenticated access to the public shares.
• Subsonic Clients: For a basic setup, you can let Navidrome handle the Subsonic authentication by configuring your reverse proxy to bypass authentication for URLs starting with /rest/. Your users will have to set a password in Navidrome and use it with their Subsonic client (note that this is incompatible with EnableUserEditing=false).

We give some example configurations for popular reverse proxies. You can adapt these to your specific setup. Note that the examples might get outdated, you should always double-check the official documentation of your reverse proxy and authentication service.

Example: Caddy with Authentik

This example shows Navidrome behind Caddy with Authentik for authentication.

example.com {
   # Authentik output endpoint
   reverse_proxy /outpost.goauthentik.io/* http://authentik:9000

   # Protect everything except share and subsonic endpoints
   @protected not path /share/* /rest/*
   forward_auth @protected http://authentik:9000 {
      uri /outpost.goauthentik.io/auth/caddy
      copy_headers X-Authentik-Username>Remote-User
   }

   # Forward everything to Navidrome
   reverse_proxy navidrome:4533
}

Example: Traefik with Authelia

This example uses Traefik with Authelia for authentication, using Docker Compose.

services:
  authelia:
    image: authelia/authelia:4.38.8
    labels:
      # Login page
      traefik.http.routers.authelia.rule: Host(`auth.example.com`)
      traefik.http.routers.authelia.entrypoints: https

      # Authentication middleware
      traefik.http.middlewares.authelia.forwardauth.address: http://authelia:9091/api/verify?rd=https://auth.example.com/
      traefik.http.middlewares.authelia.forwardauth.authResponseHeaders: Remote-User

  navidrome:
    image: deluan/navidrome:0.52.0
    labels:
      # Main Navidrome access with web authentication
      traefik.http.routers.navidrome.rule: Host(`music.example.com`)
      traefik.http.routers.navidrome.entrypoints: https
      traefik.http.routers.navidrome.middlewares: authelia@docker

      # Authentication bypass for share and subsonic endpoints
      traefik.http.routers.navidrome-public.rule: Host(`music.example.com`) && (PathPrefix(`/share/`) || PathPrefix(`/rest/`))
      traefik.http.routers.navidrome-public.entrypoints: https
    environment:
      # Trust all IPs in Docker network - use more specific IP if possible
      ND_EXTAUTH_TRUSTEDSOURCES: 0.0.0.0/0

Security Considerations

Make sure to check the Security Considerations page for important security information.

Key security points:

• Never run Navidrome as root
• Properly secure UNIX sockets if used
• Be careful with dynamic IP addresses in Docker environments
• Ensure that your reverse proxy is properly configured to remove the authentication header if set by clients (some, but not all, do it by default; some do it by default only for specific header names)

Troubleshooting

Common issues and solutions:

1. Authentication not working

   • Check that your reverse proxy IP is in the ExtAuth.TrustedSources option and in CIDR format: X.X.X.X/32
   • Verify the correct that header is being sent by the reverse proxy (Remote-User by default)
   • Check the proxy logs to confirm that the authentication is successful

2. New users not being created

   • Ensure that the header contains the correct username
   • Check the Navidrome logs for any errors

3. Subsonic clients can’t connect

   • Verify your proxy configuration for the /rest/* endpoint
   • Check if your client supports the authentication method you’re using

4. Shared links not working

   • Make sure your proxy allows unauthenticated access to /share/* URLs

FAQ

Q: Can I use this with my existing OAuth provider?
A: Yes, as long as your reverse proxy can integrate with your OAuth provider and pass the username to Navidrome.

Q: What if I want to switch back to Navidrome’s authentication?
A: Remove or comment out the ExtAuth.TrustedSources configuration.

Q: Can I mix authentication methods?
A: Yes, Navidrome will fall back to standard authentication if the reverse proxy header is not present or the request’s source not trusted.

See Also

• Security Considerations for Navidrome
• Configuration Options for all available settings
• Externalized Authentication for the detailed documentation of the feature
• Caddy Forward Auth documentation
• Traefik ForwardAuth middleware

2 - Anonymous Data Collection

Overview

Navidrome includes an anonymous usage statistics feature designed to help improve the project for all users. This page explains what data is collected, how it is used, and how to opt out if you prefer not to participate.

Key Principles

• Anonymous Data Only: Navidrome collects only non-personal, anonymous data to guide future improvements.
• What’s Collected: See Collected Data.
• What’s NOT Collected: No emails, IP addresses, usernames, or other identifiable data. See Excluded Data.
• Opt-Out Available: Enabled by default, but you can disable it anytime.
• In-House Data Handling: Collected data goes to an open-source server hosted by the project—no third-party services.
• Full Transparency: Logs and UI indicators show when data is sent and what it contains.

What Will Be Collected?

Below is a plain-English explanation of what each field is generally intended to represent. Each field corresponds to a piece of information about the running application or its environment:

Top-level Fields

• InsightsID: A unique, randomly generated identifier for a given Navidrome instance. It’s a random ID that allows reports from the same instance to be grouped together. It is NOT directly connected to any of your data, and it cannot be used to directly identify you or your instance.

• Version: Shows which Navidrome version each report came from. In aggregate analysis, this tells you how many users are on a particular version and can highlight upgrade patterns.

• Uptime: The amount of time an instance has been running. When aggregated, this helps gauge the overall stability and average runtime before restarts across the community.

Build Information

Information about custom builds. Aggregated, this can reveal common build configurations used by the community, and if there are any issues (e.g. performance impact or high memory usage) specific to certain build configurations.

• Build.Settings: Key-value pairs representing the compile-time settings for Navidrome (build tags, compiler options, etc.).

• Build.GoVersion: The version of Go used to compile Navidrome.

OS Information

• OS.Type: Operating system type (e.g., “linux”, “windows”, “darwin”). When aggregated, this shows the distribution of OS usage.

• OS.Distro: OS distribution name for Linux-based systems (e.g., “ubuntu”, “debian”). Useful in aggregate form to see which Linux distributions are most common.

• OS.Version: The version of the operating system or distribution. Aggregating these versions helps track environment trends and legacy OS usage.

• OS.Containerized: Whether Navidrome is running in a containerized environment (Docker, Kubernetes, etc..)

• OS.Arch: CPU architecture (e.g., “amd64”, “arm”). This allows to understand how Navidrome is typically deployed (e.g., on Raspberry Pis vs. standard x86 servers).

• OS.NumCPU: The number of logical CPUs available. Aggregated, it helps form a picture of typical hardware profiles used across deployments.

Memory Information

Aggregated memory usage helps analyze typical resource consumption patterns and, together with other metrics, help identify causes for memory leaks.

• Mem.Alloc: Current memory allocated by the Go runtime (in bytes).

• Mem.TotalAlloc: Memory allocated over the lifetime of the application.

• Mem.Sys: Total memory requested from the underlying system.

• Mem.NumGC: Number of completed garbage collection runs. Collected in aggregate, this shows a high-level overview of how Navidrome manages memory across various deployments.

File System Information

Each FS-related field captures information about the directories or storage mediums used by Navidrome. Aggregating this data can help understand how frequently different types of storage are configured and where media content is commonly stored. This information is just the type of the filesystem (ex: nfs, ext4, ntfs…) used for each type of storage, not the actual path.

• FS.Music: File system type for storing music files.

• FS.Data: File system type storing Navidrome’s database.

• FS.Cache: File system type storing cached data.

• FS.Backup: The file system type for backups.

Each of these includes Type, describing the kind of storage (e.g., local disk, network mount). Aggregating them shows how widely different storage setups are used, and their impact on performance.

Library Information

These fields represent aggregate counts of media items and user data within each instance’s library. Across many deployments, they help illustrate general usage trends of the Navidrome library functionality.

• Library.Tracks: Total number of songs (tracks).

• Library.Albums: Total number of albums.

• Library.Artists: Count of distinct artists.

• Library.Playlists: Number of playlists.

• Library.Shares: Number of shares (public links).

• Library.Radios: The count of radio station entries or streaming sources.

• Library.ActiveUsers: Number of currently active users in the last 7 days. This helps understand the average load the server is operating under.

• Library.ActivePlayers: Number of currently active players in the last 7 days. This allows to understand what are the most used players.

Configuration Settings

These are various Navidrome configuration flags and settings. In aggregate, they help show which features are commonly enabled or how the service is typically set up across the community. These are mostly boolean flags or simple settings, NO identifiable data is collected (paths, ids, tokens, etc..). For a reference of what each one represents, take a look at the configuration options page in the documentation.

• Config.LogLevel
• Config.LogFileConfigured
• Config.TLSConfigured
• Config.ScanSchedule
• Config.TranscodingCacheSize
• Config.ImageCacheSize
• Config.EnableArtworkPrecache
• Config.EnableDownloads
• Config.EnableSharing
• Config.EnableStarRating
• Config.EnableLastFM
• Config.EnableListenBrainz
• Config.EnableSpotify
• Config.EnableMediaFileCoverArt
• Config.EnableJukebox
• Config.EnablePrometheus
• Config.SessionTimeout
• Config.SearchFullString
• Config.RecentlyAddedByModTime
• Config.PreferSortTags
• Config.BackupSchedule
• Config.BackupCount
• Config.DefaultBackgroundURL
• Config.DevActivityPanel
• Config.EnableCoverAnimation

In Summary:
When gathered from many Navidrome instances, these metrics and settings are invaluable in understanding the aggregate patterns of usage, deployment environments, media collections, and configuration preferences. This aggregated data is not intended for diagnosing single-instance issues; rather, it provides a high-level view of how Navidrome is deployed and used by its community overall.

Here’s a sample of the data sent: https://gist.github.com/deluan/1c8944fb92329c1658d96bb72a8e8db4

Data Retention

• Sent daily
• Retained for 30 days, then permanently deleted.

What Will NOT Be Collected?

To protect your privacy, the following will not be collected:

• No Personal Information: No emails, usernames, or anything identifiable.
• No Network Information: No IP addresses or device fingerprints.
• No Detailed Playback History: Individual song plays are not tied to specific users.
• No Library Details: Song/artist/album/playlist names are excluded.
• No Sensitive Configuration Data: Passwords, tokens, or logs with personal info are never collected.

Why Collect This Data?

Collecting anonymous usage statistics helps:

• Identify popular platforms and configurations.
• Prioritize features and fixes based on usage patterns.
• Ensure updates don’t unintentionally disrupt the majority of users.

Privacy and Transparency

Transparency Measures

1. Human-Readable Documentation: This page explains all details in a clear, accessible way.
2. Log Transparency: Each data submission logs:
   • The exact payload sent.
   • The destination URL. Example:

   Sent Insights data (for details see http://navidrome.org/docs/getting-started/insights  data="{\"id\":\"4c457065-101a-435a-b158-244b573579cd\",\"version\":\"0.53.3-SNAPSHOT (7f47e0a53)\",\"uptime\":0,\"build\":{\"settings\":{\"-buildmode\":\"exe\",\"-compiler\":\"gc\",\"-ldflags\":\"-extldflags '-static -latomic' -w -s         -X github.com/navidrome/navidrome/consts.gitSha=7f47e0a53         -X github.com/navidrome/navidrome/consts.gitTag=v0.53.3-SNAPSHOT\",\"-tags\":\"netgo\",\"CGO_ENABLED\":\"1\",\"GOAMD64\":\"v1\",\"GOARCH\":\"amd64\",\"GOOS\":\"linux\",\"vcs\":\"git\",\"vcs.modified\":\"true\",\"vcs.revision\":\"7f47e0a5373d1ea067de8929c828ee0cd85a0795\",\"vcs.time\":\"2024-12-15T02:01:46Z\"},\"goVersion\":\"go1.23.4\"},\"os\":{\"type\":\"linux\",\"distro\":\"qts\",\"version\":\"5.2.2\",\"arch\":\"amd64\",\"numCPU\":4},\"mem\":{\"alloc\":2750544,\"totalAlloc\":9076584,\"sys\":14243080,\"numGC\":4},\"fs\":{\"music\":{\"type\":\"ext2/ext3/ext4\"},\"data\":{\"type\":\"ext2/ext3/ext4\"},\"cache\":{\"type\":\"ext2/ext3/ext4\"},\"backup\":{\"type\":\"ext2/ext3/ext4\"}},\"library\":{\"tracks\":85200,\"albums\":6255,\"artists\":1319,\"playlists\":26,\"shares\":19,\"radios\":7,\"activeUsers\":1},\"config\":{\"logLevel\":\"debug\",\"transcodingCacheSize\":\"100GB\",\"imageCacheSize\":\"50GB\",\"enableArtworkPrecache\":true,\"enableDownloads\":true,\"enableSharing\":true,\"enableStarRating\":true,\"enableLastFM\":true,\"enableListenBrainz\":true,\"enableMediaFileCoverArt\":true,\"enableSpotify\":true,\"enableCoverAnimation\":true,\"sessionTimeout\":\"168h0m0s\",\"recentlyAddedByModTime\":true,\"backupSchedule\":\"5 4 * * *\",\"backupCount\":5,\"devActivityPanel\":true,\"defaultBackgroundURL\":true}}" server="https://insights.navidrome.org/collect" status="200 OK"
   

3. UI Indicator: You will be able to see the last submission date/time in the About dialog:

   

How to Opt-Out

Data collection is enabled by default, but you can disable it anytime, by setting the new config option EnableInsightsCollector (or ND_ENABLEINSIGHTSCOLLECTOR env var) to false. If you have EnableExternalServices set to false, it will also disable the insights collection.

Detailed instructions will be provided in the release notes.

Data Collection Server

The data collection server is open-source and hosted by the Navidrome project, ensuring secure, in-house handling. Check it out: Navidrome Insights Server.

Thank You for Your Support

By allowing anonymous usage statistics, you’re contributing to the future of Navidrome. Your trust is invaluable, and if you’re uncomfortable, you can always opt out—no questions asked.

For questions or concerns, feel free to reach out via:

• Discord
• GitHub Discussions
• Reddit

Thank you for being part of the Navidrome community!

Deluan
Navidrome Developer