In order for PhotoPrism® Pro to authenticate users via OpenID Connect (OIDC), you can either set up and use a self-hosted identity provider such as ZITADEL or Keycloak, or configure a public service such as those offered by Google, Microsoft, GitHub, or Amazon.

Config Options

Environment CLI Flag Default Description
PHOTOPRISM_OIDC_URI --oidc-uri issuer URI for single sign-on via OpenID Connect, e.g. https://accounts.google.com
PHOTOPRISM_OIDC_CLIENT --oidc-client client ID for single sign-on via OpenID Connect
PHOTOPRISM_OIDC_SECRET --oidc-secret client SECRET for single sign-on via OpenID Connect
PHOTOPRISM_OIDC_PROVIDER --oidc-provider custom identity provider NAME, e.g. Google
PHOTOPRISM_OIDC_ICON --oidc-icon custom identity provider icon URI
PHOTOPRISM_OIDC_REDIRECT --oidc-redirect automatically redirect unauthenticated users to the configured identity provider
PHOTOPRISM_OIDC_REGISTER --oidc-register allow new users to create an account when they sign in with OpenID Connect
PHOTOPRISM_OIDC_USERNAME --oidc-username preferred_username preferred username CLAIM for new OpenID Connect users (preferred_username, name, nickname, email)
PHOTOPRISM_OIDC_WEBDAV --oidc-webdav allow new OpenID Connect users to use WebDAV when they have a role that allows it
PHOTOPRISM_DISABLE_OIDC --disable-oidc disable single sign-on via OpenID Connect, even if an identity provider has been configured

Your PhotoPrism instance and the OpenID Connect Identity Provider (IdP) must be accessible via HTTPS and have valid TLS certificates configured for it. Please also make sure that the hostname in the Redirect URL configured on the IdP matches the Site URL used by PhotoPrism. Single sign-on via OIDC can otherwise not be enabled.

Redirect URL

The Redirect URL that must be specified when registering a new client with an Identity Provider is as follows, where {hostname} must be replaced by the hostname in the Site URL, e.g. configured via PHOTOPRISM_SITE_URL:

https://{hostname}/api/v1/oidc/redirect

Both URLs must begin with https:// to use HTTPS, as otherwise single sign-on via OIDC cannot be enabled.

Preferred Username

When a new user signs in with OpenID Connect1, their preferred username may already be registered. In this case, a random 6-digit number is appended to resolve the conflict.

The config option PHOTOPRISM_OIDC_USERNAME allows you to change the preferred username for new accounts from preferred_username to name, nickname, or verified email. Names are changed to lowercase handles so that, for example, "Jens Mander" becomes "jens.mander".

Existing Accounts

Super admins can manually connect existing user accounts under Settings > Users by changing the authentication to OIDC and then setting the Subject ID to match the account identifier from the configured Identity Provider:

Edit Account

The Edit Account dialog may additionally contain a text field for the Issuer URL. It does not need to be entered manually as it is set automatically after the first login.

Changing the authentication of an account to OIDC does not remove a previously set password, so that it can still be used to log in (optionally also in combination with 2FA). Learn more ›

PhotoPrism® Documentation

For detailed information on specific product features, services, and related resources, see our Knowledge Base, or read the User Guide for help using the web user interface:

  1. PHOTOPRISM_OIDC_REGISTER must be set to "true" to allow new users to create an account ↩