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_SCOPES --oidc-scopes openid email profile address client authorization SCOPES 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 redirects unauthenticated users to the configured identity provider
PHOTOPRISM_OIDC_REGISTER --oidc-register allows 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_DOMAIN --oidc-domain verified email domain NAME for single sign-on via OpenID Connect pro
PHOTOPRISM_OIDC_ROLE --oidc-role guest default user ROLE for new OpenID Connect users pro
PHOTOPRISM_OIDC_GROUP_CLAIM --oidc-group-claim group claim NAME to read from OIDC tokens (default groups)
PHOTOPRISM_OIDC_GROUP --oidc-group require membership in at least one group ID (repeat flag to add multiple)
PHOTOPRISM_OIDC_GROUP_ROLE --oidc-group-role map GROUP=ROLE; repeat to add more (roles: admin, guest, visitor, or none)
PHOTOPRISM_OIDC_WEBDAV --oidc-webdav allows new OpenID Connect users to use WebDAV when they have a role that allows it
PHOTOPRISM_DISABLE_OIDC --disable-oidc disables 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 allow users to log in via OIDC, you can either set up and use a self-hosted identity provider such as ZITADEL or Keycloak, or choose a public authentication service such as those provided by Google, Microsoft, GitHub, or Amazon.

Single sign-on can then be configured automatically through your identity provider's /.well-known/openid-configuration service discovery endpoint, 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 claim for new accounts from preferred_username to name, nickname or verified2 email. The other claims are used as fallback if no value is returned for the configured claim. Names are changed to lowercase so that, for example, "John Doe" becomes "john.doe".

Learn more ›

Existing Accounts

Super admins can manually connect existing user accounts3 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.

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 ›

Using Security Groups from Microsoft Entra ID

The following features are supported by our current implementation:

  • Reads security groups from the groups claim in ID or access tokens; accepts GUIDs or names (case-insensitive, sanitized via NormalizeGroupID).
  • Optional required membership: --oidc-group (or PHOTOPRISM_OIDC_GROUP) lists one or more groups that must be present; login is rejected if none match. If the token signals overage via _claim_names.groups and contains no groups, login is denied with an audit entry explaining that membership could not be validated.
  • Group-to-role mapping: --oidc-group-role (GROUP=ROLE, repeatable) assigns the first matching role; falls back to --oidc-role (default guest) when no mapping matches.
  • Keeps app/directory roles (roles, wids) separate from security groups to avoid accidental privilege escalation.
  • Claim name is configurable via --oidc-group-claim (default groups).

You can use the following config options to map security groups and roles in PhotoPrism® Pro:

  • --oidc-group-claim / PHOTOPRISM_OIDC_GROUP_CLAIM: claim to read (default groups).
  • --oidc-group / PHOTOPRISM_OIDC_GROUP: comma- or multi-flag list of groups required for login (IDs or names accepted, normalized to lowercase alphanumerics/hyphen/underscore).
  • --oidc-group-role / PHOTOPRISM_OIDC_GROUP_ROLE: mapping GROUP=ROLE (roles: admin|manager|user|contributor|viewer|guest|none). First match wins.
  • --oidc-role / PHOTOPRISM_OIDC_ROLE: fallback role if no group mapping matches (defaults to guest).

Support for Entra ID Security Groups is only available with our team plans, not the personal editions.

Integration Guide for Entra ID Groups

  1. Register an app in Microsoft Entra ID (v2) or reuse your existing PhotoPrism registration. Note the tenant ID and the application (client) ID.
  2. Redirect URI: add https://{hostname}/api/v1/oidc/redirect.
  3. Token configuration → Add optional claim → Token type = ID (and Access if you prefer) → Groups → choose Security groups.
  4. Under “Emit groups as”, pick Group name (cloud-only) or sAMAccountName / DNSDomainName\sAMAccountName for synced AD; this makes tokens carry human-friendly names instead of GUIDs.
  5. If you keep Group ID, leave PhotoPrism config in GUID mode; if you emit names, set PHOTOPRISM_OIDC_GROUP / PHOTOPRISM_OIDC_GROUP_ROLE to those names (lowercase in config for consistency). When Microsoft signals group overage (too many groups to fit in the token), it sets _claim_names.groups and may omit groups entirely; PhotoPrism will currently block login if required groups are configured and no groups are present.
  6. Grant admin consent for the chosen scopes (at minimum openid profile email, plus offline_access if you need refresh tokens).
  7. Configure PhotoPrism (example .env-oidc with placeholder secrets): 
    PHOTOPRISM_OIDC_URI="https://login.microsoftonline.com/f8b10857-a7f2-49ba-b73c-6f619715f574/v2.0"
PHOTOPRISM_OIDC_CLIENT="11111111-2222-3333-4444-555555555555"
PHOTOPRISM_OIDC_SECRET="asecure-random-oidc-client-secret"
PHOTOPRISM_OIDC_GROUP_CLAIM="groups"
PHOTOPRISM_OIDC_GROUP="photoprism-admins, photoprism-users"        # names or GUIDs
PHOTOPRISM_OIDC_GROUP_ROLE="photoprism-admins=admin, photoprism-users=user"
  8. Restart PhotoPrism; on login the service will:
    • Read groups from ID token, then fall back to userinfo if absent.
    • Deny login if required groups are configured but none are present (and overage is signaled).
    • Apply the first matching group→role mapping; otherwise assign the fallback role.

Usage Tips

  • If tokens still contain GUIDs, revisit Token configuration → Groups and change “Emit groups as” to a name format; reissue tokens by signing out/in. Names must be unique in your tenant for deterministic mapping.
  • Overage: when the _claim_names.groups marker is present and no groups are in the token, PhotoPrism cannot validate membership and will block login if oidc-group is set. (Graph-based resolution is described in the next section but is not yet implemented.)
  • For mixed environments, you can supply both names and GUIDs in oidc-group / oidc-group-role; all entries are normalized and deduplicated.

Documentation & References

Frequently Asked Questions

Can I configure a custom claim for the preferred username?

You can choose between preferred_username, name, nickname and verified2 email, where preferred_username is the default. The other claims are used as fallback if no value is returned for the configured claim.

Please note that it is currently not possible to use other standard or non-standard claims, as these may not be suitable for generating a username and no logic is implemented for doing so.

Learn more ›

What if my provider does not return any claims for generating a username?

Certified OIDC Identity Providers, as well as public service providers such as Google, should support (at least) a subset of the standard claims that PhotoPrism can use to generate a username for newly registered accounts. These are preferred_username, name, nickname and verified2 email, where preferred_username is the default.

If only an unverified email address2 or none of these claims are returned, we recommend that you report this to the vendor of the Identity Provider you are using, as this is also likely to cause problems with other software. In a future release, we may offer additional config options to work around this issue, e.g. by generating a random username. However, this is currently not possible.

Learn more ›

PhotoPrism® Documentation

For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:

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

  2. The email_verified flag must be set by the OIDC Identity Provider so that the email address can be used to send notifications and/or confirm the identity of users. If we do not insist on verification, this could otherwise have a negative impact on trust and security. ↩ ↩ ↩ ↩

  3. Admins are unable to change the authentication method of their own user account through the Admin Web UI, so they cannot accidentally lock themselves out e.g. by setting it to None. ↩