User accounts and signing in

User accounts and signing in

By default, anyone who can reach PhotoStructure on your network can see your whole library — there’s no login screen. That’s the right default for a laptop or a computer only you use, but if other people share the machine or the network, you can ask PhotoStructure to require a sign-in first.

User accounts are opt-in and off by default. Turning them on adds a login screen and lets you decide who gets in and what they can do.

🤔 Do you actually need accounts?

You can safely leave accounts off if:

Turn accounts on if:

  • Other people share the computer or the local network and you don’t want them browsing your photos, or
  • You want to give family or friends their own limited access, or
  • You plan to expose PhotoStructure beyond a trusted network.

Important: requiring a login and exposing PhotoStructure to your network are two separate settings. If you make PhotoStructure reachable by other computers (see remote access), turn on accounts too — otherwise anyone who can reach the address gets in without a password.

✉️ How signing in works

PhotoStructure’s sign-in is passwordless by default. To log in, you enter your email address and PhotoStructure emails you a six-digit code. Type the code in and you’re signed in — nothing to memorize, and no password to leak.

You can also set a password on any account. A password is handy when:

  • you want to sign in without waiting for an email, or
  • the computer is offline or can’t send email.

If you use a single sign-on provider (Google Workspace, Microsoft Entra ID, Keycloak, Authentik, and similar), PhotoStructure can also sign people in through it.

👑 Turning on accounts and creating the first admin

The person who creates the first account becomes the admin — the account that can manage everyone else and change settings.

🧙 During first-run setup

When you first open PhotoStructure, the welcome wizard offers to create your admin account. Enter your email address, an optional display name, and a password, then continue. That’s it — accounts are now on, and you’ll sign in with those credentials from then on.

If you’d rather not require a login, choose “Skip account setup — my network is already secured” on that page. You can always turn accounts on later.

⏳ Turning accounts on later

If you skipped account setup and want to enable it afterward:

  1. Open your library’s settings.toml file (it lives in the hidden .photostructure folder inside your library — see advanced settings) and add:

    enableAuth = true

    You can also set this with the PS_ENABLE_AUTH environment variable.

  2. Restart PhotoStructure (see how to start and stop).

  3. The next time you open PhotoStructure it will walk you through creating the first admin account.

💌 Inviting other people

Once you’re signed in as an admin, open the menu and choose Manage user accounts, then Invite user. You’ll provide:

  • Email address — where their sign-in codes are sent.
  • Display name (optional) — how they appear in the app.
  • Role — what they’re allowed to do (see below).
  • Password (optional) — leave it blank and they’ll sign in with an emailed code.

New people sign in exactly the way you do: they enter their email address and receive a six-digit code.

🎭 Roles: who can do what

PhotoStructure has three roles, from most to least access:

RoleCan do
AdminEverything: view and organize photos, manage accounts, and change settings.
EditorView and organize photos, tags, and albums. Cannot manage accounts or change settings.
ViewerView photos, tags, and albums only. Read-only.

New accounts default to Viewer. You can change anyone’s role, temporarily disable an account, reset a password, or remove an account from the same Manage user accounts page.

Roles apply to the whole library — there’s no per-album or per-folder sharing yet. If you need to share just one album with someone, use a reverse proxy for now.

PhotoStructure won’t let you lock yourself out: you can’t remove, disable, or demote your own account, and you can’t remove the last admin. There will always be at least one admin who can get in.

🎫 Single sign-on (OIDC)

If you already run an identity provider — Google Workspace, Microsoft Entra ID, Okta, Keycloak, Authentik, Authelia, and most others that speak OpenID Connect — PhotoStructure can hand sign-in off to it. A “Sign in with SSO” button then appears on the login screen.

Single sign-on is configured through the oidc* settings. Because getting the provider details right (issuer URL, client ID, and the redirect URL) takes some care, the single sign-on guide walks through the full setup, including the role mapping that lets your provider decide who’s an admin.

🤦 When someone forgets their password

There’s no self-service “forgot password” link yet, but nobody gets locked out:

  • If email works, just use the passwordless option: enter your email on the login screen and sign in with the six-digit code. Then set a new password from your account if you’d like one.
  • If you’re an admin, you can reset any other person’s password (or clear it so they use email codes) from Manage user accounts.
  • If the only admin is locked out and email isn’t an option, an advanced recovery path is available by editing the library database directly. Ask us on the forum and we’ll walk you through it.

🔌 Turning accounts off again

If you decide you don’t want a login screen after all, set enableAuth = false in your library’s settings.toml and restart PhotoStructure. Every route is open again.

Turning accounts off does not delete anyone — the accounts you created are remembered, so if you turn accounts back on later, the same people (and the same admin) are still there.

🔒 A note on security

PhotoStructure is self-hosted: your photos and the accounts you create stay on your own hardware. A few things worth knowing:

  • Sign-in codes and passwords protect the web interface. They don’t encrypt the files on disk — anyone with access to the computer’s filesystem can read your library directly. Protect the machine itself with normal operating-system permissions and backups.
  • If you expose PhotoStructure to the internet, always put it behind HTTPS (a reverse proxy is the usual way). A login over plain http:// can be intercepted. If you’re running PhotoStructure on a server you manage, some basic server hardening is worth doing too.
  • Passwords are never stored as plain text — they’re hashed with Argon2id, a modern, deliberately-slow algorithm designed to resist cracking.

🔗 See also