A PhotoPrism® Portal is the cluster’s central identity and access-control point. Users sign in once at the Portal, which then logs them in to the instances they are allowed to use. This page explains the authentication and authorization options the Portal provides and helps you decide which to use.
Three rules hold across every cluster, regardless of how you configure it:
- Closed by default. Authenticating at the Portal does not grant access to any instance — access must be granted explicitly, per instance, and is re-evaluated on every login.
- Per-instance isolation. Each instance has its own database and sessions; a session issued for one instance is never valid on another.
- Cluster admin ≠ content access. The Portal-only
cluster_adminrole manages the cluster but, by itself, opens no instance.
Authentication Methods
Each Portal account has an authentication provider that decides how it signs in. The Portal supports three operator-facing methods, which can be combined across accounts:
| Method | How users sign in | Local password | Group mapping source |
|---|---|---|---|
| Local accounts | Username and password managed on the Portal | Required | — |
| Upstream identity (OIDC) | Federated single sign-on against your provider (Entra ID, Keycloak, …) | Optional fallback | Provider groups |
| LDAP / Active Directory | Directory username and password | Replaced by the directory | Directory groups (DN) |
- Local accounts need no external dependency — create users on the Portal and they sign in with a password (and optional two-factor). Best for small or single-organization clusters.
- Upstream identity (OIDC) adds a “Continue with
<provider>” button on the Portal login and enables security-group-based admission and single sign-out. Configure the issuer, client, and secret on the Portal only — see Upstream Identity Provider. - LDAP / Active Directory authenticates users against a directory; matching directory groups feed the same group-to-role admission as OIDC. See the LDAP / Active Directory guide.
The methods are not mutually exclusive: an OIDC or LDAP account can still keep a local password as a fallback, and a cluster can mix local and federated accounts. Configure the upstream provider and directory on the Portal, which authenticates users on behalf of every instance.
Users who sign in through OIDC or LDAP have no local password, so they generate an app password after signing in to use WebDAV and other Basic-Auth clients. If your security policy disallows long-lived credentials, disable app passwords on the Portal and on each instance by adding app-passwords to PHOTOPRISM_DISABLE_FEATURES.
How Cluster Sign-In Works
Instances delegate authentication to the Portal. With cluster OIDC enabled (the default), an instance derives its OpenID client and issuer from its cluster node credentials, so there is no per-instance provider setup — see Cluster Authentication.
After signing in at the Portal, a user with access to one instance is sent straight to it; a user with access to several is shown an instance chooser. Signing out ends the Portal session and, when single sign-out is enabled with an upstream provider, the provider session too.
Authorization: Access Is Closed by Default
A user who can authenticate at the Portal still needs explicit access to each instance. When deciding whether a user may open an instance, the Portal resolves access in this order:
- Per-user grant. An explicit assignment of the user to that instance wins, with its role. An empty role means inherit the user’s Portal account role; a concrete role overrides it.
- Security-group mapping. Otherwise, the user’s groups (from the upstream provider and/or LDAP) are matched against the groups the instance admits; if any matches, access is granted with the mapped role. When several match, the highest-privilege role wins.
- Otherwise, access is denied.
Access is re-evaluated on every login, so revoking a grant or removing a group membership takes effect at the next sign-in. There are two ways to grant access, and you can combine them:
| Approach | Best for | Requires upstream provider | Effort | Granularity |
|---|---|---|---|---|
| Per-user grants | Small clusters, exceptions, contractors, break-glass | No | Manual, per user × instance | Exact (one user, one instance) |
| Security-group mapping | Larger organizations with a directory | Yes (OIDC or LDAP groups) | Set once per group, scales with directory | Group-based (everyone in a group) |
A per-user grant always takes precedence over a group mapping, so you can use group mappings for the bulk of access and per-user grants for exceptions and overrides.
Grants and group mappings are managed in the Portal admin interface or from a terminal:
# Grant one user access to one instance, as viewer
photoprism cluster users access grant --user [user-uid] --node [node-uuid] --role viewer
# Admit a whole security group to an instance, as user
photoprism cluster nodes allow-group [node-uuid] [group-id] --role user
See Cluster Command-Line Tools and Mapping Security Groups to Roles.
Roles
The role a user receives on an instance is a regular PhotoPrism user role, assigned per instance through the grant or group mapping:
| Role | Scope | Summary |
|---|---|---|
admin | Instance | Full access to all content and settings. |
manager | Instance | Like user, plus read-only user management (view users, audit and delete sessions). |
user | Instance | Full access to the library; cannot change library or advanced settings. |
contributor | Instance | Read-only access to its base path and shared albums; may upload to the configured upload path. |
viewer | Instance | Read-only access; cannot see private or archived content, upload, or index. |
guest | Instance | Read-only access to shared resources and its configured base path only. |
cluster_admin | Portal | Manages the cluster (nodes, grants, settings) in the Portal; opens no instance by itself. |
The Portal-only cluster_admin role grants access to the cluster management interface and the photoprism cluster commands. For security, cluster_admin is never assigned through an identity provider or security group, and it does not by itself open any instance — a cluster administrator who also needs to use an instance must be granted access like any other user. The anonymous visitor role (used for share links) likewise cannot be granted through a directory. See Managing User Accounts for the full permission matrix.
Managing Instances & Users
The Portal keeps a registry of every instance (node) and is where you manage them and their users:
- Instances. Each instance registers with the Portal on first boot (role
instance, orservicefor a supporting node). List, inspect, re-role, rotate credentials, and remove nodes with thecluster nodescommands or in the Portal UI. See Adding Instances. - Users. From the Portal management interface, an operator can review which users can open which instances, grant or revoke access, and change roles across the cluster — without signing in to each instance individually.
Decision Guide
- Small cluster, no directory. Use local Portal accounts and per-user grants. Simple, self-contained, no external services.
- Organization with SSO (Entra ID, Keycloak, …). Federate to your upstream identity provider and drive access with security-group mappings; add per-user grants only for exceptions. Enable single sign-out so logout ends the provider session too.
- Active Directory shop. Use LDAP / Active Directory authentication and map directory groups to instance roles, the same way as OIDC groups.
- Mixed. Combine methods — federate most users while keeping a few local break-glass admin accounts, and layer per-user grants over group mappings for fine control.
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: