plex-oidc-bridge

KO | EN

gitlite — search

#react #ai #typescript #llm #golang #rust #linux #docker #macos #awesome #cli #kubernetes #openai #ios

plex-oidc-bridge

(★ 14)

This is a repository for a plex OIDC bridge

plex-oidc-bridge Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Plex OIDC Bridge

A lightweight OIDC (OpenID Connect) Provider that uses Plex for authentication. Designed specifically to bridge Plex users into identity flows like **Cloudflare Access**, **Tailscale**, or any other OIDC-compatible client.

## IMPORTANT DISCLAIMERS
1. This project is not affiliated with Plex, Inc. or Cloudflare, Inc. in any way. Use at your own risk. This software is provided "as is", without warranty of any kind.
2. This software is an **AUTHENTICATION** provider only. It does not provide authorization or user management features. You are responsible for configuring your identity platform to manage access control. This software is an easy way to capture Plex identities and use them in your existing OIDC flows. If you are unsure of the differences between authentication and authorization, please research those topics before using this software.
3. You should have a basic understanding of OIDC, OAuth2, and Plex authentication flows to use this software effectively.
4. Always run this software behind HTTPS (e.g., Cloudflare Tunnel, nginx reverse proxy with TLS, etc.) to protect user credentials and tokens. Anyone who can access this service and its signing keys can impersonate authenticated users; protect it accordingly.
5. Review the source code before use to ensure it meets your security requirements. Additionally, this software is for personal or homelab use only and should not be used in production or enterprise environments. It may lack the security features and compliance required for such use cases.
6. Plex may, at any time and without notice, change their authentication mechanisms or APIs, which could break this software. Attempts to update the software will be made on a best effort basis, but no guarantees are made.

## Features

- **Plex Authentication**: Users sign in via the standard Plex OAuth PIN flow.
- **OIDC Discovery**: Fully compliant `/.well-known/openid-configuration`.
- **JWKS Endpoint**: Automatically manages RSA signing keys for JWT verification.
- **Cloudflare Compatible**: Specifically tested with Cloudflare Access for homelab and media server security
- **Stable Identity**: Uses Plex `uuid` as the `sub` (subject) claim for stability, with email fallback.
- **Test Mode**: Optional built-in verification flow (`/test`) to verify the login process.

## Quick Start

### 1. Build & Run locally
```bash
# Build the binary
go build -o plex-bridge .

# Set your external URL (important for OIDC redirects)
export PUBLIC_URL="http://localhost:8080"
export ENABLE_TEST_ENDPOINTS="true"
export ALLOWED_REDIRECT_URIS="http://localhost:8080/test/callback"
export TRUST_PROXY_HEADERS="true"

# Start the bridge
./plex-bridge
```

### 2. Verify with Test Mode
Open your browser to `http://localhost:8080/test`. 
This will walk you through a complete Plex login and display the resulting OIDC claims (Email, Username, UUID, etc.).

## Docker Deployment

The recommended way to run this in a homelab is using Docker or Docker Compose.

### Running with Docker CLI
```bash
docker build -t plex-oidc-bridge .

docker run -d \
  -p 8080:8080 \
  -e PUBLIC_URL="https://auth.example.com" \
  -e ALLOWED_REDIRECT_URIS="https://example.com/callback,https://another.com/redirect" \
  -e TRUST_PROXY_HEADERS="true" \
  -v ./config:/app/config \
  --name plex-bridge \
  plex-oidc-bridge
```

### Running with Docker Compose
```yaml
services:
  plex-bridge:
    image: ghcr.io/blacktirion/plex-oidc-bridge:latest
    container_name: plex-auth-bridge
    ports:
      - "8080:8080"
    volumes:
      - ./config:/app/config
    environment:
      - PUBLIC_URL=https://auth.example.com
      - PORT=8080
      - ALLOWED_REDIRECT_URIS=https://example.com/callback,https://another.com/redirect
      - TRUST_PROXY_HEADERS=true
    restart: unless-stopped
```

## First Run & Setup

On the first run, the bridge will generate an OIDC Client ID and Secret if you don't provide them. 
**Secrets are never printed to logs for security reasons.** Retrieve your credentials from the configuration file:

```bash
# View the generated Client ID and Secret
cat config/clients.json
```

You will see output like this, which you can copy/paste into Cloudflare Access or your identity platform of choice:

```json
{
  "client_id": "AbCdEfGhIjKlMnOpQrStUvWx",
  "client_secret": "aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
}
```

Your OIDC endpoints are:
- **Auth URL**: `https://auth.example.com/authorize`
- **Token URL**: `https://auth.example.com/token`
- **JWKS URL (Certs)**: `https://auth.example.com/.well-known/jwks.json`
- **Discovery URL**: `https://auth.example.com/.well-known/openid-configuration`

## Configuration Parameters

### Persistence
The bridge stores generated keys and configuration in `/app/config`. You should mount this volume to persist your RSA signing keys and Client credentials.
- `oidc.key`: The RSA private key for signing tokens.
- `clients.json`: Stores the generated Client ID and Secret.

### How Parameters Work
- **`PUBLIC_URL`**: This tells the bridge how to construct its own URLs. If you are using a Cloudflare Tunnel or Reverse Proxy, set this to your public domain.

## Cloudflare Access Configuration

To use this bridge with Cloudflare Access/Zero Trust:

1.  **Identity Provider**: Add a new **Generic OIDC** provider.
2.  **Get Your Credentials**: Retrieve your Client ID and Secret from `config/clients.json` (never from logs).
3.  **Configuration**:
    *   **Name**: Plex
    *   **App ID**: `<Client ID from config/clients.json>`
    *   **App Secret**: `<Client Secret from config/clients.json>`
    *   **Auth URL**: `https://your-bridge-url.com/authorize`
    *   **Token URL**: `https://your-bridge-url.com/token`
    *   **Certificate URL**: `https://your-bridge-url.com/.well-known/jwks.json`
4.  **Scopes**: Ensure `openid`, `email`, and `profile` are requested.

## License

MIT

plex-oidc-bridge

plex-oidc-bridge Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

plex-oidc-bridge

plex-oidc-bridge Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README