Plex LDAP Gateway

Some apps only know how to log in against LDAP. Plex does not speak LDAP. This project sits in the middle and makes your Plex users look like LDAP users so those apps can authenticate with Plex-backed identities.

When an LDAP client tries to log in, this service asks Plex to verify the username and password, and then returns an LDAP login success or failure. The LDAP side is only a read-only view of Plex. Passwords stay in Plex rather than being copied into a separate LDAP database.

What the service exposes

• An LDAPv3 listener for bind, search, and unbind operations
• A small HTTP server with health and readiness endpoints
• An in-memory LDAP tree built from the Plex owner account and matching shared users
• A single process that runs HTTP and LDAP listeners

Running in Docker

Install and run the published image directly from GHCR:

docker pull ghcr.io/archmonger/plex-ldap-gateway:latest
docker run -d `
	--name plex-ldap-gateway `
	-p 1389:1389 `
	-p 7576:7576 `
	-v "<your-preferred-data-path>:/config" `
	-e PLEX_OWNER_TOKEN="<your-plex-owner-token>" `
	-e PLEX_MACHINE_IDENTIFIER="<your-plex-machine-identifier>" `
	ghcr.io/archmonger/plex-ldap-gateway:latest

Running locally

1. Install Python 3.11 or higher on your machine.
2. Open this repository's files on your local machine within terminal and set the required environment variables.
3. Install the python project then start the bundled runner via the following commands:

pip install -e .
plex-ldap-gateway

Alternatively, you can also start the ASGI app through an external server:

uvicorn --factory plex_ldap_gateway.app:create_app --host 0.0.0.0 --port 7576

Environment variables

Required application settings:

• PLEX_OWNER_TOKEN: Plex owner or admin token used to enumerate and authorize directory users
• PLEX_MACHINE_IDENTIFIER: Plex Media Server machineIdentifier used to scope directory access

Optional application settings:

• PLEX_BASE_URL: defaults to https://plex.tv
• PLEX_CLIENT_IDENTIFIER: defaults to plex-ldap-gateway-{PLEX_MACHINE_IDENTIFIER}
• PLEX_CLIENT_PRODUCT: defaults to Plex LDAP Gateway
• PLEX_CLIENT_VERSION: defaults to the package version
• PLEX_TIMEOUT_SECONDS: defaults to 10
• GATEWAY_LDAP_STRICT_MACHINE_MATCH: defaults to true
• GATEWAY_LDAP_REFRESH_SECONDS: defaults to 300
• GATEWAY_LDAP_BASE_DN: defaults to dc=plex,dc=ldap
• GATEWAY_LDAP_HOST: defaults to 0.0.0.0
• GATEWAY_LDAP_PORT: defaults to 1389
• GATEWAY_HTTP_HOST: defaults to 0.0.0.0
• GATEWAY_HTTP_PORT: defaults to 7576
• GATEWAY_LOG_LEVEL: defaults to ERROR
• GATEWAY_LOG_OUTPUT: defaults to console; supported values are console, file, and both
• GATEWAY_LOG_FILE_PATH: defaults to plex-ldap-gateway.log; used when GATEWAY_LOG_OUTPUT includes file output

Docker specific settings:

• PUID, PGID, TZ
• GATEWAY_LDAP_BIND_ADDRESS, GATEWAY_HTTP_BIND_ADDRESS
• SERVICE_CRASH_MAX_ATTEMPTS, SERVICE_CRASH_WINDOW_SECONDS, SERVICE_CRASH_BACKOFF_SECONDS

GATEWAY_LDAP_BIND_ADDRESS and GATEWAY_HTTP_BIND_ADDRESS only control host port publishing in compose.yml. They are not application settings. Inside the container, the service binds with GATEWAY_LDAP_HOST=0.0.0.0 and GATEWAY_HTTP_HOST=0.0.0.0.

Common client settings

Here is an example LDAP client settings, written from the perspective of the Jellyfin LDAP-Auth plugin:

Technical overview

How the directory is built

1. Load settings from environment variables.
2. Fetch the Plex owner account with PLEX_OWNER_TOKEN.
3. Fetch the Plex users shared by that owner.
4. If GATEWAY_LDAP_STRICT_MACHINE_MATCH=true, keep only users who can access PLEX_MACHINE_IDENTIFIER.
5. Build a read-only LDAP tree rooted at GATEWAY_LDAP_BASE_DN, with all users under ou=users.

Binding behavior

Credentialed binds can resolve a user by:

• Full DN, such as uid=alice,ou=users,dc=plex,dc=ldap
• Plain identifier, such as alice
• Email address, such as alice@example.com
• Simple attr=value input, such as uid=alice

Short-form identifiers only work when they map to exactly one generated user in the current directory snapshot.

An empty bind DN is treated as an anonymous bind. Non-anonymous binds with empty passwords are rejected.

LDAP layout

By default, the generated directory looks like this:

dc=plex,dc=ldap
+-- ou=users
	+-- uid=<generated-user-id>

The root DN is configurable with GATEWAY_LDAP_BASE_DN. User entries always live under ou=users,<base DN>.

Each generated user entry is read-only and exposes these LDAP attributes:

HTTP endpoints

• GET /healthz: process status, directory size, last refresh timestamp, and listener state
• GET /readyz: readiness state, refreshing from Plex when the cache is stale
• GET /readyz?force=1: forces a fresh Plex directory refresh before responding

Testing and CI

Useful local commands:

hatch fmt --check
hatch test -m "not live_plex"
hatch test --cover

Live Plex tests need these environment variables:

• PLEX_OWNER_TOKEN
• PLEX_MACHINE_IDENTIFIER
• PLEX_TEST_BIND_LOGIN
• PLEX_TEST_BIND_PASSWORD

Optional live-test variables:

• PLEX_TEST_BIND_IDENTITY: defaults to PLEX_TEST_BIND_LOGIN
• PLEX_TEST_EXPECTED_USERNAME
• PLEX_TEST_EXPECTED_EMAIL

Security and behavior notes

• LDAP simple bind sends credentials in cleartext unless you add transport security. Put this behind trusted network boundaries or wrap LDAP with TLS separately.
• The generated LDAP directory is read-only.
• Passwords are validated against Plex at bind time rather than stored in LDAP.
• The gateway runs within a single process and is limited to ~50,000 requests per second. It can be scaled horizontally behind a load balancer, if needed.