OIDC Single Sign On

OIDC single sign-on

Pinchflat-ngx can require an OAuth2/OpenID Connect provider for the web interface. It discovers provider endpoints from the issuer's /.well-known/openid-configuration document and uses the authorization-code flow with PKCE, state, and nonce validation.

Register Pinchflat-ngx

Create a confidential OAuth2/OpenID Connect application with:

• Flow: authorization code
• Redirect URI: https://pinchflat-ngx.example.com/auth/oidc/callback
• Scopes: openid email profile
• Client type: confidential

Replace the example host with the public address users open in their browser. The redirect URI must match exactly, including the scheme, host, port, and path prefix.

Copy the client ID, client secret, and issuer URL. The issuer is the provider identifier whose discovery document is available at <issuer>/.well-known/openid-configuration; it is not necessarily the provider's home page.

Configure Pinchflat-ngx

Add the required values to the container:

environment:
  OIDC_ISSUER: https://sso.example.com/application/o/pinchflat-ngx/
  OIDC_CLIENT_ID: pinchflat-ngx
  OIDC_CLIENT_SECRET: replace-with-your-client-secret
  OIDC_REDIRECT_URI: https://pinchflat-ngx.example.com/auth/oidc/callback
  OIDC_PROVIDER_NAME: Authentik

Use your deployment's secret-management method for the client secret. Never commit the real value.

Restart Pinchflat-ngx and inspect the result:

docker compose up -d
docker compose logs --tail 100 pinchflat-ngx

Pinchflat-ngx refuses to start when only some of OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET are set. Remove all OIDC_* variables to disable OIDC.

Authentik

Create an OAuth2/OpenID Provider in Authentik and attach it to an application:

1. Set the redirect URI to the exact Pinchflat-ngx callback URL.
2. Select the authorization-code flow and a confidential client.
3. Copy the provider's client ID and client secret into the Pinchflat-ngx environment.
4. Use the OpenID configuration issuer shown by Authentik as OIDC_ISSUER. For an application slug named pinchflat-ngx, this is commonly https://auth.example.com/application/o/pinchflat-ngx/.
5. Keep OIDC_CLIENT_AUTH_METHOD at client_secret_basic unless the provider requires client_secret_post.

Assign Authentik users or groups to the application, then test with a private browser window.

Reverse proxies

Pinchflat-ngx derives the callback URL from the request unless OIDC_REDIRECT_URI is set. A fixed value is recommended in production because it prevents proxy-header mistakes from producing the wrong callback.

Forward the original scheme and host, allow WebSocket upgrades, and use HTTPS. For a redirect URI mismatch, compare the provider's registered URI with OIDC_REDIRECT_URI character for character.

Authentication behavior

• OIDC replaces Basic Auth for web-interface routes when enabled.
• Feed endpoints retain Basic Auth and route tokens for podcast clients.
• API endpoints and /healthcheck remain unauthenticated by design.
• Signing out clears the local Pinchflat-ngx session. It may not end the provider's browser session.

Optional settings

Variable	Default	Purpose
OIDC_SCOPES	openid email profile	Space-separated scopes requested from the provider.
OIDC_CLIENT_AUTH_METHOD	client_secret_basic	Token-endpoint authentication method.
OIDC_PROVIDER_NAME	Single Sign-On	Provider name on the login button.
OIDC_REDIRECT_URI	Derived from the request	Fixed public callback URI. Recommended behind a proxy.