Authentication and Authorization

Relevant source files

• mobile/openapi/lib/model/permission.dart
• server/src/app.module.ts
• server/src/bin/migrations.ts
• server/src/bin/sync-sql.ts
• server/src/config.ts
• server/src/controllers/index.ts
• server/src/dtos/system-config.dto.ts
• server/src/main.ts
• server/src/maintenance/maintenance-worker.controller.ts
• server/src/maintenance/maintenance-worker.service.spec.ts
• server/src/maintenance/maintenance-worker.service.ts
• server/src/repositories/config.repository.spec.ts
• server/src/repositories/config.repository.ts
• server/src/repositories/database.repository.ts
• server/src/repositories/index.ts
• server/src/services/base.service.ts
• server/src/services/database-backup.service.spec.ts
• server/src/services/database-backup.service.ts
• server/src/services/database.service.spec.ts
• server/src/services/database.service.ts
• server/src/services/index.ts
• server/src/services/system-config.service.spec.ts
• server/src/types.ts
• server/src/utils/config.ts
• server/src/utils/database-backups.ts
• server/src/workers/api.ts
• server/src/workers/microservices.ts
• server/test/medium.factory.ts
• server/test/medium/globalSetup.ts
• server/test/repositories/config.repository.mock.ts
• server/test/utils.ts
• web/src/lib/components/utilities-page/duplicates/duplicate-asset.svelte
• web/src/lib/components/utilities-page/duplicates/duplicates-compare-control.svelte
• web/src/lib/components/utilities-page/duplicates/info-row.svelte
• web/src/lib/services/keyboard.service.ts
• web/src/lib/utils/actions.ts
• web/src/routes/(user)/user-settings/+page.svelte/user-settings/+page.svelte)
• web/src/routes/(user)/utilities/duplicates/[[photos=photos]]/[[assetId=id]]/+page.svelte

This page documents Immich's authentication and authorization systems, covering how users authenticate (prove their identity) and how the system authorizes access to resources. For information about multi-tenant content sharing and access control, see page 4.3.

---

Overview

Immich implements a multi-layered authentication system supporting three primary methods:

Authentication Method	Use Case	Token Type	Key Classes
Email/Password	Web and mobile users	JWT (Bearer + Cookie)	AuthService, CryptoRepository
OAuth 2.0 / OIDC	External identity providers	JWT (Bearer + Cookie)	OAuthRepository, AuthService
API Keys	CLI tools and integrations	API Key (x-api-key header)	ApiKeyRepository

Every API request passes through AuthGuard (registered as NestJS APP_GUARD in ApiModule). The guard delegates to AuthService.authenticate(), which resolves the caller's identity and populates an AuthDto used for downstream authorization checks. The maintenance worker uses a separate MaintenanceAuthGuard.

Sources: server/src/app.module.ts17-49 server/src/middleware/auth.guard.ts

---

Request Authentication Pipeline

AuthGuard

AuthGuard is registered as APP_GUARD in ApiModule and runs on every HTTP request. It reads credentials from three possible locations and calls AuthService.authenticate():

Authentication pipeline diagram

The resulting AuthDto carries the resolved identity through the request. Services call requireAccess() or checkAccess() (from src/utils/access) using an AccessRepository to enforce fine-grained per-resource permissions.

WebSocket connections are also authenticated: BaseModule.onModuleInit() calls websocketRepository.setAuthFn() with a closure that calls AuthService.authenticate() using the socket handshake headers.

Sources: server/src/app.module.ts17-49 server/src/app.module.ts80-86 server/src/services/base.service.ts210-214 server/test/utils.ts117-119

---

Authentication Methods

Password Authentication

Password authentication is the default method for user accounts. The system uses bcrypt for password hashing and issues JWT tokens upon successful authentication.

Password Change Flow:

The system supports password changes with optional session invalidation. When a user changes their password, they can choose to invalidate all existing sessions except the current one.

Sources: server/src/services/auth.service.ts server/src/repositories/crypto.repository.ts

---

OAuth 2.0 / OpenID Connect

OAuth authentication allows users to authenticate using external identity providers (Google, Authentik, Keycloak, etc.). The implementation uses the openid-client library with PKCE (Proof Key for Code Exchange) for enhanced security.

OAuth Configuration:

OAuth is configured via the oauth key in SystemConfig. The full set of fields (from server/src/config.ts):

Config Field	Type	Default	Description
enabled	boolean	false	Enable OAuth login
issuerUrl	string	''	OIDC discovery endpoint
clientId	string	''	OAuth client identifier
clientSecret	string	''	OAuth client secret
scope	string	'openid email profile'	Requested scopes
signingAlgorithm	string	'RS256'	ID token signing algorithm
profileSigningAlgorithm	string	'none'	UserInfo signing algorithm
tokenEndpointAuthMethod	OAuthTokenEndpointAuthMethod	client_secret_post	Token endpoint auth method
timeout	number	30000	Request timeout (ms)
autoRegister	boolean	true	Auto-create user on first OAuth login
autoLaunch	boolean	false	Skip login page, go directly to OAuth
buttonText	string	'Login with OAuth'	Custom button label
mobileOverrideEnabled	boolean	false	Use custom mobile redirect URI
mobileRedirectUri	string	''	Custom mobile redirect URI
defaultStorageQuota	number | null	null	Default quota for OAuth users
storageLabelClaim	string	'preferred_username'	JWT claim for storage label
storageQuotaClaim	string	'immich_quota'	JWT claim for storage quota
roleClaim	string	'immich_role'	JWT claim for admin role

Token Endpoint Authentication Methods (OAuthTokenEndpointAuthMethod):

The OAuthRepository supports three authentication methods:

• none: No authentication (public client)
• client_secret_post: Send client_id and client_secret in POST body
• client_secret_basic: Send credentials in HTTP Basic Auth header

Linking OAuth Accounts:

Users can link their existing password-based account to an OAuth provider using the /oauth/link endpoint, allowing them to authenticate with either method.

Sources: server/src/config.ts98-117 server/src/repositories/oauth.repository.ts

---

API Keys

API keys provide programmatic access to Immich for CLI tools and integrations. Each API key has an associated set of permissions that limit what operations it can perform.

API key authentication flow

API Key Management Endpoints:

• POST /api-keys - Create a new API key with specified permissions
• GET /api-keys - List all API keys for current user
• GET /api-keys/{id} - Get specific API key details
• GET /api-keys/me - Get the current API key (when authenticated with an API key)
• PUT /api-keys/{id} - Update API key name or permissions
• DELETE /api-keys/{id} - Delete an API key

API Key Creation:

Usage:

API keys are sent in the x-api-key HTTP header:

x-api-key: <secret-key>

Sources: server/src/repositories/api-key.repository.ts mobile/openapi/lib/model/permission.dart1-50

---

Mobile-Specific Authentication

Mobile clients have additional authentication features for improved security and user experience.

Pin Codes

Users can set up a PIN code for quick access to the mobile app without entering their full password. PIN codes are stored securely on the device and validated server-side.

Endpoints:

• POST /auth/pin-code - Set up a new PIN code
• PUT /auth/pin-code - Change existing PIN code
• DELETE /auth/pin-code - Reset/remove PIN code
• POST /auth/session/unlock - Unlock session with PIN or password

Pin Code Operations:

Session Locking

Mobile sessions can be locked for security when the app is backgrounded or after a timeout. Locked sessions require PIN or password to unlock.

Endpoints:

• POST /auth/session/lock - Lock the current session
• POST /auth/session/unlock - Unlock with PIN or password (SessionUnlockDto)

Sources: server/src/services/auth.service.ts server/src/controllers/auth.controller.ts

---

Session Management

Sessions track authenticated clients and their state. The system stores session information in PostgreSQL and uses it for token validation, device tracking, and security features.

Session Lifecycle

Session Data Model

Session Response Fields:

Field	Type	Description
id	UUID	Session identifier
userId	UUID	User who owns the session
deviceType	string	Type of device (web, iOS, Android, CLI)
deviceOS	string	Operating system name
appVersion	string	Immich app version
createdAt	timestamp	When session was created
updatedAt	timestamp	Last activity timestamp
expiresAt	timestamp	When session expires (optional)
isPendingSyncReset	boolean	Mobile sync needs reset
current	boolean	Is this the current session

Session Management Endpoints:

• POST /sessions - Create a new session (login)
• GET /sessions - List all sessions for current user
• PUT /sessions/{id} - Update session (e.g., device info)
• DELETE /sessions/{id} - Delete a specific session
• DELETE /sessions - Delete all sessions except current
• POST /sessions/{id}/lock - Lock a session (mobile)

Admin Session Management:

• GET /admin/users/{id}/sessions - List sessions for any user (admin only)

Sources: server/src/repositories/session.repository.ts server/src/services/session.service.ts server/src/controllers/session.controller.ts

---

Authorization System

Authorization in Immich operates at two levels:

1. Endpoint-level: AuthGuard checks whether the caller has the required role (admin vs. standard user) using NestJS metadata decorators applied at the controller level.
2. Resource-level: Service methods call requireAccess() or checkAccess() (from src/utils/access) with an AccessRequest to verify that the authenticated user has the right to act on the specific resource (e.g., owns the asset, is a member of the album).

Permission Model

Authorization layer diagram

AccessRequest structure:

An AccessRequest specifies the permission being requested (a Permission enum value), an auth context, and the ids of the resources being accessed. requireAccess resolves which IDs the caller is permitted to access and throws ForbiddenException for any that are not.

Common Permission Patterns (from Permission enum):

Pattern	Examples
{resource}.read	activity.read, album.read, asset.read
{resource}.create	activity.create, album.create, asset.create
{resource}.update	album.update, asset.update
{resource}.delete	activity.delete, album.delete, asset.delete
adminUser.*	adminUser.read, adminUser.create, adminUser.update, adminUser.delete
adminSession.*	adminSession.read, adminSession.delete

Sources: server/src/services/base.service.ts61-62 server/src/services/base.service.ts210-214 server/src/repositories/access.repository.ts mobile/openapi/lib/model/permission.dart14-50

Security Schemes

Immich supports three credential schemes:

Security scheme summary

Scheme	Header / Location	Credential
bearer	Authorization: Bearer <jwt>	JWT signed by Immich
cookie	Cookie: immich_access_token=<jwt>	JWT signed by Immich
api_key	x-api-key: <secret>	Raw API key secret
shared link	?key=<key> query param	Shared link key

Sources: server/src/services/auth.service.ts server/src/middleware/auth.guard.ts

User Roles and Access Levels

Immich uses a flat two-role model: every user has an isAdmin boolean flag.

User role hierarchy

Admin-Only Controllers:

Controller	Purpose
UserAdminController	CRUD for all user accounts
AuthAdminController	Unlink OAuth for any user
SystemConfigController	Read/write SystemConfig
QueueController	Manage background job queues
MaintenanceController	Toggle maintenance mode
NotificationAdminController	Send test emails

Sources: server/src/controllers/index.ts7-42 server/src/services/index.ts8-9

---

Multi-User Access Control

Beyond basic user roles, Immich implements fine-grained access control for shared resources.

Album Access Control

Albums support role-based sharing with three access levels:

Album User Management:

Album User Fields:

Sources: server/src/repositories/album.repository.ts server/src/repositories/album-user.repository.ts server/src/services/album.service.ts

Partner Sharing

Partner sharing creates a trusted relationship where two users can access each other's entire libraries.

Partner Management:

• POST /partners - Create a partner relationship (requires acceptance)
• GET /partners - List current partners
• PUT /partners/{id} - Update partner settings
• DELETE /partners/{id} - Remove a partner

Partner Permissions:

Partners have access to each other's:

• All uploaded assets
• Asset metadata and EXIF data
• Album memberships (if shared)
• Face recognition data

Partners cannot:

• Delete each other's assets
• Modify original files
• Change account settings

Sources: server/src/repositories/partner.repository.ts server/src/services/partner.service.ts

Shared Links (Public Access)

Shared links allow external access to albums or individual assets without authentication. Links can be password-protected and have expiration dates.

Shared Link Endpoints:

• POST /shared-links - Create a shared link
• GET /shared-links - List all shared links
• GET /shared-links/{id} - Get specific shared link details
• GET /shared-links/me - Get link info when accessing via link
• PUT /shared-links/{id}/assets - Add assets to link
• DELETE /shared-links/{id}/assets - Remove assets from link
• PATCH /shared-links/{id} - Update link settings
• DELETE /shared-links/{id} - Delete a shared link

Shared Link Configuration:

Sources: server/src/repositories/shared-link.repository.ts server/src/services/shared-link.service.ts

---

Maintenance Mode Authentication

When Immich starts in maintenance mode (controlled by the MaintenanceModeState stored in SystemMetadata[SystemMetadataKey.MaintenanceMode]), the regular ApiModule and AuthGuard are replaced by MaintenanceModule with its own MaintenanceAuthGuard.

Maintenance mode boot sequence

The maintenance worker authenticates requests using a JWT signed with a per-session ephemeral secret stored alongside the MaintenanceModeState. The MaintenanceWorkerService (in server/src/maintenance/maintenance-worker.service.ts) uses jwtVerify from the jose library and reads credentials from either the Authorization header or the immich_access_token cookie.

The MaintenanceModeState type encodes this:

MaintenanceModeState =
  | { isMaintenanceMode: true; secret: string; action?: SetMaintenanceModeDto }
  | { isMaintenanceMode: false }

Sources: server/src/main.ts32-65 server/src/app.module.ts105-137 server/src/maintenance/maintenance-worker.service.ts server/src/maintenance/maintenance-auth.guard.ts server/src/types.ts474-476

---

Security Features

PKCE (Proof Key for Code Exchange)

OAuth authentication uses PKCE to prevent authorization code interception attacks. This is especially important for mobile and single-page applications that cannot securely store a client secret.

PKCE Flow:

1. Client generates random code_verifier
2. Client calculates code_challenge = BASE64URL(SHA256(code_verifier))
3. Client sends code_challenge with authorization request
4. Identity provider stores challenge, returns authorization code
5. Client exchanges code + code_verifier for tokens
6. Identity provider verifies: code_challenge == BASE64URL(SHA256(code_verifier))

The OAuthRepository.authorize() method automatically generates PKCE parameters:

Sources: server/src/repositories/oauth.repository.ts server/src/config.ts98-117

Token Security

JWT Token Structure:

JWT tokens are signed using the jose library. The token payload encodes the session identity:

{
  sub: userId,           // User ID (UUID)
  iat: timestamp,        // Issued at
  exp: timestamp,        // Expiration (if set)
}

AuthService.authenticate() validates the JWT signature and then looks up the session record in SessionRepository to confirm the session is still active.

Token Storage:

• Web clients: Stored in immich_access_token cookie (set server-side)
• Mobile clients: Stored in flutter_secure_storage (Keychain on iOS, KeyStore on Android)
• CLI clients: Stored in local config files

Token Transmission:

Tokens can be sent via:

1. Authorization: Bearer <token> header (preferred)
2. immich_access_token cookie (web browser)
3. x-api-key header (API keys, not a JWT)

Sources: server/src/services/auth.service.ts server/src/repositories/session.repository.ts

Password Security

Password Hashing:

Passwords are hashed using bcrypt via CryptoRepository.hashBcrypt(). The salt rounds constant is SALT_ROUNDS (defined in src/constants). Password comparison uses CryptoRepository.compareBcrypt().

The BaseService.createUser() helper hashes the password before writing to UserRepository:

payload.password = await this.cryptoRepository.hashBcrypt(payload.password, SALT_ROUNDS);

Password Policies:

• shouldChangePassword flag on the user record forces a password change on next login
• Password changes can invalidate all existing sessions
• Admin users can force password changes for any user via UserAdminController

Sources: server/src/services/base.service.ts218-240 server/src/repositories/crypto.repository.ts server/src/constants.ts

Session Security

Session Invalidation:

Sessions can be invalidated through multiple mechanisms:

1. Explicit logout: POST /auth/logout deletes session
2. Delete session: DELETE /sessions/{id} removes specific session
3. Delete all sessions: DELETE /sessions removes all except current
4. Password change: Optionally invalidates all sessions
5. Token expiration: Sessions expire based on expiresAt timestamp

Device Tracking:

Each session tracks device information for security auditing:

• Device type (iOS, Android, Web, CLI)
• Operating system and version
• App version
• Creation and last activity timestamps

Sources: server/src/repositories/session.repository.ts server/src/services/session.service.ts

---

Permission Reference

All permissions are defined in the Permission class in mobile/openapi/lib/model/permission.dart (auto-generated from the OpenAPI spec). The following is a representative subset:

Permission value	Category	Description
all	—	Grants all permissions (super-access)
activity.read	Activity	View album activities
activity.create	Activity	Create likes/comments
activity.delete	Activity	Delete activities
activity.statistics	Activity	View activity stats
album.read	Album	View albums
album.create	Album	Create albums
album.update	Album	Modify album metadata/assets
album.delete	Album	Delete albums
album.addAsset	Album	Add assets to album
album.removeAsset	Album	Remove assets from album
album.share	Album	Add/change album users
asset.read	Asset	View assets
asset.create	Asset	Upload assets
asset.update	Asset	Modify asset metadata
asset.delete	Asset	Delete assets
asset.view	Asset	Access asset binary
asset.download	Asset	Download assets
asset.upload	Asset	Upload via shared link
apiKey.read	API Key	View API keys
apiKey.create	API Key	Create API keys
apiKey.update	API Key	Modify API keys
apiKey.delete	API Key	Delete API keys
library.read	Library	View external libraries
library.create	Library	Create libraries
library.update	Library	Modify libraries
library.delete	Library	Delete libraries
library.statistics	Library	View library stats
person.read	Person	View recognized people
person.create	Person	Create person records
person.update	Person	Modify person names/merge
person.delete	Person	Delete person records
person.merge	Person	Merge person records
person.reassign	Person	Reassign faces
sharedLink.read	Shared Link	View shared links
sharedLink.create	Shared Link	Create shared links
sharedLink.update	Shared Link	Modify shared links
sharedLink.delete	Shared Link	Delete shared links
tag.read	Tag	View tags
tag.create	Tag	Create tags
tag.update	Tag	Modify tags
tag.delete	Tag	Delete tags
tag.asset	Tag	Tag/untag assets
adminUser.read	Admin	View any user (admin)
adminUser.create	Admin	Create users (admin)
adminUser.update	Admin	Modify users (admin)
adminUser.delete	Admin	Delete users (admin)
adminSession.read	Admin	View any user's sessions
adminSession.delete	Admin	Delete any user's session
adminAuth.unlinkAll	Admin	Unlink all OAuth for user
adminLibrary.*	Admin	Manage all libraries
adminNotification.read	Admin	View all notifications
adminNotification.create	Admin	Send test notifications
adminSystemConfig.*	Admin	Read/write system config
adminTag.*	Admin	Manage all tags
adminUser.forcePw	Admin	Force password reset
timeline.read	Timeline	Read timeline data
stack.read	Stack	View asset stacks
stack.create	Stack	Create stacks
stack.update	Stack	Modify stacks
stack.delete	Stack	Delete stacks

Sources: mobile/openapi/lib/model/permission.dart server/src/repositories/access.repository.ts

---

Mobile Authentication Flow

Mobile apps have a specialized authentication flow that supports both OAuth and password authentication, with additional features for offline access and biometric authentication.

Mobile-Specific Security:

• Tokens stored in flutter_secure_storage (Keychain on iOS, KeyStore on Android)
• Biometric authentication handled locally by device
• PIN code validated server-side for cross-device consistency
• Session locking prevents unauthorized access if device left unlocked

Sources: mobile/pubspec.yaml36 open-api/immich-openapi-specs.json631-642