Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / web-administration-and-authentication

Web administration and authentication

The web administration and authentication experience gives people a safe path into the service and gives administrators control over accounts, access rules, server settings, and maintenance work. It joins public sign-in screens with signed-in user settings and protected administration pages so each person sees the actions allowed by their account. It is part of the wider web application experience, with library-facing effects described in web library workflows.

Access and session control

Access control is the gate for web pages that need a signed-in user or an administrator. The web app restores the current user and preferences when an authentication cookie is present, sends unknown users to sign-in with their intended destination, and sends non-admin users away from administrator pages. A session can also be locked behind a personal PIN without ending the account session. web/…/auth.ts• L8-28 web/…/auth-manager.svelte.ts• L24-82 web/…/+layout.ts• L1-8

When a session ends, the web app clears its local user state and follows the server's redirect. A server event can also request logout, which keeps the page state aligned with session changes made elsewhere. web/…/auth-manager.svelte.ts• L44-48 web/…/auth-manager.svelte.ts• L92-119

flowchart TD
    A[Open protected page] --> B{Signed in?}
    B -- No --> C[Sign-in page]
    C --> D{Password or OAuth succeeds?}
    D -- No --> C
    D -- Yes --> E{Onboarding or password change needed?}
    E -- Yes --> F[Complete required account step]
    E -- No --> G[Return to requested page]
    B -- Yes --> H{Admin page?}
    H -- No --> G
    H -- Yes --> I{Administrator?}
    I -- Yes --> G
    I -- No --> J[Return to photo view]

References: web/…/auth.ts• L8-28 web/…/auth-manager.svelte.ts• L24-82 web/…/auth-manager.svelte.ts• L92-134 web/…/+layout.ts• L1-8

Sign-in and account entry

The sign-in page is the main entry point for an existing account. It can offer password sign-in, external OAuth sign-in, or both according to public server settings. After sign-in, it preserves the page the person first requested and routes new accounts through the required first-login steps. web/…/+page.svelte• L31-37 web/…/+page.svelte• L80-110

OAuth can start automatically when the server enables that behavior. Its callback either completes sign-in or opens onboarding for an account that still needs setup. The page shows a clear error when password or OAuth sign-in cannot complete, and it warns when all sign-in methods are disabled. web/…/+page.svelte• L39-78 web/…/+page.svelte• L113-185

The first server account uses a separate registration page. It collects the administrator's email, name, and password, then returns to sign-in after the account is created. web/…/+page.svelte• L28-47

Onboarding and password setup

Onboarding turns a successful first sign-in into a usable account and server. It presents shared user choices such as theme, language, privacy, and mobile app setup. The privacy step also lets the person choose whether to enable Google Cast, and saves that choice when the step ends. web/…/+page.svelte• L45-119 web/…/OnboardingUserPrivacy.svelte• L9-26 The first administrator also sees server choices such as server privacy, storage layout, and backup setup. The flow records user completion and administrator completion separately before it opens the main photo view. web/…/+page.svelte• L129-160

An account that must change its password cannot skip that step. The page accepts and confirms a new password, then signs the person out so the next sign-in uses the new credential. web/…/+page.svelte• L17-29

User settings

User settings let a signed-in person manage account identity, local app behavior, access, and personal features from one page. The settings are grouped into expandable sections so account and security changes remain separate from photo and sharing preferences. web/…/+page.svelte• L18-22 web/…/UserSettingsList.svelte• L49-159

The security sections provide these controls:

  • Profile changes for the email address and display name.
  • Password changes with an option to end other device sessions.
  • OAuth account linking, unlinking, and access to the external account manager when configured.
  • Authorized device review with single-device or all-device logout.
  • PIN creation and change for locking the current web session.
  • API key, notification, feature, download, and sharing settings.

Feature settings give the person control over optional library views and related behavior. They cover folders, time-based memories, people, ratings, shared links, tags, Google Cast, recently added items, and album sort order; changes are saved together as the person's preferences. These choices shape the library experience described in web library workflows. web/…/FeatureSettings.svelte• L11-72

Sharing settings extend these controls to relationships between users. A person can manage membership in a people cluster group, review pending invitations, leave a group when another member remains, and ask the service to rebuild group face data. Partner sharing lets the person add or remove partners, see what each partner shares, and choose whether incoming partner assets appear in the timeline. These controls connect personal settings to the access and sharing rules described in identity, access, and sharing.

References: web/…/SharingSettings.svelte• L43-245 web/…/SharingSettings.svelte• L248-409

Profile changes update the active account state immediately. Password and device actions affect session access, so the page gives them separate controls and confirmation steps. web/…/UserProfileSettings.svelte• L11-29 web/…/ChangePasswordSettings.svelte• L7-20 web/…/DeviceList.svelte• L15-49

PIN session lock

The PIN flow protects an already signed-in web session without asking the person to enter the account password again. The settings page creates or changes the PIN, and the lock prompt checks it before returning the person to the page they wanted. A wrong PIN stays on the prompt and shows an error; a missing PIN can be created from the same entry point. web/…/PinCodeSettings.svelte• L9-32 web/…/+page.svelte• L20-37 web/…/+page.svelte• L41-70

Administrator workspace

The administrator workspace is a protected area for server owners. Its shared page layout organizes account management, server settings, status, queues, libraries, and maintenance as operational views rather than as part of the normal photo experience. Every administrator route first checks both authentication and administrator status. web/…/+layout.ts• L1-8 web/…/+page.svelte• L20-30

User administration

User administration gives an administrator a list and a detail view for account life-cycle work. It supports creating users, changing profile and quota data, granting administrator access, resetting credentials or PINs, and deleting or restoring accounts. User detail also shows feature access, storage use, authorized devices, and upload activity so an administrator can understand the effect of an account change. web/…/+layout.svelte• L35-55 web/…/+page.svelte• L11-61 web/…/+layout.svelte• L74-103 web/…/+layout.svelte• L143-229

New users can receive a welcome message when email is enabled. An administrator can require a password change at the next sign-in, set a storage quota, and mark the new account as an administrator. Quota warnings compare the requested limit with the server disk size so a bad limit is visible before the account is used. web/…/+page.svelte• L21-31 web/…/+page.svelte• L74-105

Authentication settings

Authentication settings control how people enter the server. An administrator can enable password login, configure OAuth, change the OAuth button and account behavior, and remove all linked OAuth accounts. The page asks for confirmation before saving a state with no enabled login method. web/…/AuthSettings.svelte• L19-42 web/…/AuthSettings.svelte• L44-62 web/…/AuthSettings.svelte• L65-87 web/…/AuthSettings.svelte• L302-318

The OAuth controls also cover the identity provider details, claims used for account roles and storage limits, mobile redirects, and optional external account management. These settings define the contract between the server and the identity provider, while the sign-in and user settings pages consume the resulting account state. web/…/AuthSettings.svelte• L89-297

Server settings

System settings provide one administrator view for server-wide behavior. The page groups settings by concern and supports search, while the visible groups cover authentication, backup, jobs, libraries, logging, maps, metadata, notifications, storage layout, themes, trash, user defaults, version checks, and media processing. web/…/+page.svelte• L59-199 web/…/+page.svelte• L201-230

Some installations manage configuration outside the web page. When that happens, the interface warns the administrator and does not present the page as the source of truth. The same workspace supports copying, importing, and exporting system settings where the server allows it. web/…/+page.svelte• L210-229

Server status and jobs

Server status turns system use into a short operational view. It reports total photos, videos, and storage, then breaks storage and media use down by user. The view refreshes on a timer so an administrator can watch changes without leaving the page. web/…/+page.svelte• L15-31 web/…/ServerStatisticsPanel.svelte• L64-72 web/…/ServerStatisticsPanel.svelte• L135-187

The queue view exposes background work that keeps the library usable. Administrators can start, refresh, clear, or reprocess work such as thumbnails, metadata, library scans, search, faces, OCR, video conversion, and storage migration. Some costly actions require confirmation, and the page listens for queue updates so its state follows the server. web/…/+page.svelte• L19-43 web/…/QueuePanel.svelte• L35-89 web/…/QueuePanel.svelte• L93-123

Maintenance and recovery

The maintenance view helps an administrator find library integrity problems and manage database backups. It can run checks for files that are untracked, missing, or different from their stored checksum, refresh the reports, and open a report for the affected items. It also offers database backup restore through a staged flow. web/…/+page.svelte• L33-50 web/…/+page.svelte• L84-107 web/…/+page.svelte• L112-188

Maintenance mode is a separate web experience because normal service work may be unavailable during a restore. It shows the current action, progress, task, and error, lets an authenticated administrator end maintenance when possible, and guides an authorized restore through installation checks and backup selection. web/…/+page.svelte• L19-39 web/…/+page.svelte• L41-93 web/…/MaintenanceRestoreFlow.svelte• L5-19

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the login continuation path aligned with every new protected route so a person returns to the page they requested after sign-in.
  • Keep the first-login checks aligned between password sign-in, OAuth sign-in, password change, and onboarding completion.
  • Keep the administrator guard aligned with any new route that can change users, authentication, system settings, queues, or maintenance state.
  • Keep OAuth provider settings aligned with the login button, callback handling, linked-account controls, and mobile redirect contract.
  • Keep user session actions aligned with password changes, PIN unlocks, logout events, and the device list so stale sessions do not remain visible.
  • Keep quota and storage labels aligned between user creation, user editing, user detail, and server usage views.
  • Keep maintenance job names aligned with the integrity report cards, active-job tracking, refresh behavior, and report links.
  • Keep feature preference keys aligned between onboarding defaults, user settings, and the library views that consume them.
  • Keep cluster-group invitations, membership actions, partner sharing state, and timeline display changes aligned with their settings refresh paths.

Important failure modes

TriggerConsequenceGuard
Password login and OAuth are both disabledNo user can sign in through the web login pageThe authentication settings page asks for confirmation before saving this state, and the login page shows a warning when it occurs.
A protected route has no valid sessionThe requested page does not openThe route guard redirects to sign-in and preserves the original path and query.
A non-admin user opens an administrator routeThe user could reach a server control surfaceThe administrator layout checks the loaded account and redirects non-admin users to the photo view.
An OAuth callback cannot completeThe account is not signed in or linkedThe login and settings pages keep the user on the relevant page and show an error.
A user is required to change a passwordThe user could enter the main app with a temporary credentialSign-in routes the user to the password-change page before normal navigation.
An integrity job is still active when a new check startsThe report can show incomplete or changing resultsThe maintenance page tracks active jobs and disables the related check and refresh actions.
A restore reports an errorThe server may remain in maintenance mode with incomplete workThe maintenance page shows the task error and provides an end-maintenance action when the state permits it.
A sharing action succeeds but the settings view does not refresh its relationship stateThe person can see stale group or partner membership and use the wrong controlSharing settings reload group and partner data after membership and sharing actions.

Key files

FileWhy to read it
web/…/auth.tsDefines the web rule for public, signed-in, and administrator routes.
web/…/auth-manager.svelte.tsShows how the web app loads, refreshes, resets, and ends the current session.
web/…/+page.svelteShows password and OAuth entry, continuation, first-login checks, and error behavior.
web/…/+page.svelteShows how user and server setup steps are selected and completed.
web/…/OnboardingUserPrivacy.svelteShows the privacy-step preference for enabling Google Cast during onboarding.
web/…/UserSettingsList.svelteShows the account and security controls available to a signed-in user.
web/…/FeatureSettings.svelteShows the optional library features and display preferences a user can save.
web/…/SharingSettings.svelteShows group membership, partner sharing, pending requests, and timeline display controls.
web/…/+layout.tsDefines the access gate for the whole administrator workspace.
web/…/+layout.svelteShows the administrator's account list and account actions.
web/…/+layout.svelteShows the account detail view and the context around user changes.
web/…/AuthSettings.svelteShows how administrators control password and OAuth sign-in.
web/…/+page.svelteShows the overall grouping and navigation model for server settings.
web/…/+page.svelteShows the live server status experience.
web/…/QueuePanel.svelteShows the background work an administrator can start or control.
web/…/+page.svelteShows integrity checks, backup management, and restore entry.
web/…/+page.svelteShows the separate maintenance and recovery experience.