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:

Issuer URI

The Issuer URI in your configuration must match the issuer value returned by the /.well-known/openid-configuration endpoint of your OpenID Connect Identity Provider (IdP), for example https://accounts.google.com if you use Google for authentication.

You may not modify the URI in any way, e.g. by adding or omitting slashes at the end. If the values do not match, the validation will fail and users cannot be redirected to your provider's login page. For security reasons, only a generic error message is displayed in this case.

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

Note that both the Site URL configured for your instance and the Redirect URL must start with https:// and that their hostnames must match, as the use of secure connections is a strict requirement for OpenID Connect.

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 follow the same steps as for creating a new account with the same username through the Admin Web UI or the photoprism users add command. You will then be asked if you want to restore the account.

Learn more ›

Frequently Asked Questions

Is it possible to set a default role for new OIDC users?

For security reasons, our Personal Editions currently default to the Guest role, which admins can then upgrade after checking the eligibility of newly registered accounts. If you run our Pro Edition in a trusted corporate network with appropriate security measures - including for the OIDC provider - it can be configured to give new accounts a higher authorization level by default.

Please note in this context that using an external Identity Provider for authorization, and not just for authentication, can easily lead to security issues such as the following, for which we do not want to get a CVE assigned nor do we want to be responsible for any private pictures of our users getting leaked as a result:

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