Authentication proxies

Put apps without OIDC support behind Pocket ID with Tinyauth, caddy-security, OAuth2 Proxy or Traefik forward auth.

Pocket ID only provides OpenID Connect, so it can’t protect an app that has no OIDC support by itself. An authentication proxy closes that gap: it sits in front of the app as the OIDC client, and only lets requests through once the visitor signed in with Pocket ID.

The authentication proxy is the OIDC client. It sends visitors without a session to Pocket ID, and only forwards requests to the app once they signed in.

Most proxies also forward the user’s name, email address and groups to the app in HTTP headers, which some apps use to sign the user in. Use allowed user groups on the proxy’s client to decide who gets through.

The proxies below work with Pocket ID, and most other reverse proxies offer something similar in their documentation.

Tinyauth

Tinyauth is a lightweight authentication middleware designed specifically for homelabs. Currently it integrates with Traefik, Caddy and Nginx Proxy Manager.

Refer to the official Tinyauth Pocket ID documentation for detailed instructions on how to set up Tinyauth with Pocket ID.

Caddy

caddy-security adds OIDC sign-in to Caddy.

Create an OIDC client in Pocket ID with the callback URL https://<service domain>/caddy-security/oauth2/generic/authorization-code-callback, and note its client ID and secret.

Add the plugin to Caddy:

caddy add-package github.com/greenpau/caddy-security

Configure the identity provider, the portal and a policy, and protect your service with them:

{
  # Port to listen on
  http_port 443

    # Configure caddy-security.
  order authenticate before respond
  security {
    oauth identity provider generic {
      delay_start 3
      realm generic
      driver generic
      client_id client-id-from-pocket-id # Replace with your own client ID
      client_secret client-secret-from-pocket-id # Replace with your own client secret
      scopes openid email profile
      base_auth_url https://<domain-where-pocket-id-runs> #Replace
      metadata_url https://<domain-where-pocket-id-runs>/.well-known/openid-configuration #Replace
    }

    authentication portal myportal {
      crypto default token lifetime 3600 # Seconds until you have to re-authenticate
      enable identity provider generic
      cookie insecure off # Set to "on" if you're not using HTTPS
      # cookie domain service.example.com - If using multiple clients/portals you have to set the cookie domain for each one so they do not conflict when trying to refresh the session.
      trust login redirect uri domain exact service.example.com path prefix /

      transform user {
        match realm generic
        action add role user
      }
    }

    authorization policy mypolicy {
      set auth url /caddy-security/oauth2/generic
      allow roles user
      inject headers with claims
    }
  }
}

https://<domain-of-your-service> {
  @auth {
    path /caddy-security/*
    }

  route @auth {
    authenticate with myportal
  }

  route /* {
    authorize with mypolicy
    reverse_proxy http://<service-to-be-proxied>:<port> # Replace with your own service
  }
}

Start Caddy:
Terminal window
```
caddy run --config Caddyfile
```

The caddy-security documentation covers the other options.

OAuth2 Proxy

OAuth2 Proxy runs next to the app and forwards signed-in requests to it, here for Uptime Kuma.

Create an OIDC client in Pocket ID with the callback URL https://<service domain>/oauth2/callback, and note its client ID and secret.

Add OAuth2 Proxy to the app’s docker-compose.yml:

# Example with Uptime Kuma
# uptime-kuma:
#  image: louislam/uptime-kuma
oauth2-proxy:
  image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
  command: --config /oauth2-proxy.cfg
  volumes:
    - './oauth2-proxy.cfg:/oauth2-proxy.cfg'
  ports:
    - 4180:4180

Create oauth2-proxy.cfg next to it:

# Replace with your own credentials
client_id="client-id-from-pocket-id"
client_secret="client-secret-from-pocket-id"
oidc_issuer_url="https://<your-pocket-id-domain>"

# Replace with a secure random string
cookie_secret="random-string"

# Upstream servers (e.g http://uptime-kuma:3001)
upstreams="http://<service-to-be-proxied>:<port>"

# Additional Configuration
provider="oidc"
scope = "openid email profile groups"

# If you are using a reverse proxy in front of OAuth2 Proxy
reverse_proxy = true

# Email domains allowed for authentication
email_domains = ["*"]

# If you are using HTTPS
cookie_secure="true"

# With HTTPS use "__Host-" or "__Secure-" prefix, otherwise leave blank
cookie_name="__Host-oauth2-proxy"

# Listen on all interfaces
http_address="0.0.0.0:4180"

Start the services:
Terminal window
```
docker compose up -d
```

Visitors now reach the app through OAuth2 Proxy on port 4180, which your reverse proxy should forward the app’s domain to. Without Docker the setup is the same, and the OAuth2 Proxy documentation covers the other options.

Traefik

Traefik does not have built-in support for OpenID Connect, but can be integrated in two ways.

Note: Traefik Enterprise has an OIDC middleware out of the box if you happen to be using that.

Using forward auth

Using forward auth, for example with traefik-forward-auth v4, involves running a separate service alongside Traefik (as a “sidecar” configured in the Docker Compose file or Pod spec). Traefik invokes the forward auth service behind the scenes to authorize requests, redirecting the user to it if it needs to authenticate. traefik-forward-auth v4 includes support for Pocket ID and other authentication providers.

See the documentation for configuring traefik-forward-auth and integrating it with Pocket ID.

Using a Traefik plugin

Traefik includes experimental support for plugins that run in-process.

Traefik OpenID Connect Middleware works with Pocket ID. See the Pocket ID configuration docs for Pocket ID specific instructions, and Getting Started for more details on how to apply the configuration to a specific endpoint.