Skip to content

Single Sign-On via OpenID Connect

OpenID Connect (OIDC) allows users to log in and optionally register through an external identity provider instead of manually entering a username and password:

oidc-login

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.

Identity Providers

To authenticate users via OIDC, you can either set up and use a self-hosted identity provider such as ZITADEL or Keycloak, or configure a public identity provider service such as those operated by Google, Microsoft, GitHub, or Amazon.

Single sign-on can be configured automatically if the identity provider offers a standardized /.well-known/openid-configuration endpoint for service discovery, for example:

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 accounts2 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 Dialog

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.

Alternatively, you can run the following command in a terminal to allow authentication via OIDC and set a Subject ID to connect existing accounts:

photoprism users mod --auth=oidc --auth-id=[sub] [username]

Learn more ›

Passwords

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).

If a local password has been set for an account, you can remove it by running the following command in a terminal:

photoprism passwd --rm [username]

Super admins can alternatively set the account password to a long random value through the Admin Web UI or CLI to effectively prevent local authentication.

Learn more ›

Deleting Accounts

Deleted accounts remain linked to the Subject ID, so logging in via OIDC is no longer possible and no new account can be registered for the same Subject ID either.

If you wish to change the connected user account or create a new account instead, you must therefore change the authentication of the old account e.g. to None before deleting it:

photoprism users mod --auth=none [username]

To restore a previously deleted account, admins can create a new account with the same username through the Admin Web UI or the photoprism users add command.

Learn more ›


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

  2. Admins cannot change the authentication of their own user account through the Admin Web UI so that they do not accidentally lock themselves out e.g. by setting it to None