Authentication & User Security

Audience: End users and technical evaluators Last Updated: 2026-04-04 Version: 2.0.0

Overview

Llamafin provides secure, flexible authentication that integrates seamlessly with your Jellyfin server. The system supports multiple login methods, automatic session management, and cryptographic security for peer-to-peer features.

Standard Username & Password

The traditional login method compatible with all Jellyfin servers:

How It Works:

Enter your Jellyfin username and password
Credentials sent securely to your Jellyfin server
Server validates and returns an authentication token
Token stored locally for automatic re-login

Security Features:

Passwords never stored locally
Server-side validation only
Encrypted transmission (HTTPS supported)
Token-based authentication with expiry

Quick Connect

Jellyfin's code-based authentication system:

How It Works:

Initiate Quick Connect from your Jellyfin server's dashboard
Server displays a 6-digit code
Enter the code in Llamafin
Instant login without typing credentials

Benefits:

No password entry required
Ideal for TV or shared device logins
Server-controlled authentication
Same security level as password login

Public User Selection

For multi-user households:

Login screen displays all enabled users
Click your user avatar to auto-fill username
Only password entry required
Server administrator controls user visibility

Session Management

Automatic Session Persistence

Once logged in, Llamafin remembers you:

What Gets Stored:

Authentication token (secure, server-issued)
User identifier (hashed for privacy)
Session expiry status

Where It's Stored:

Browser: IndexedDB (secure local storage)
Mobile: Capacitor Preferences (native storage)
Desktop: Application storage (platform-specific)

Session Rehydration

When you reopen Llamafin:

Stored credentials automatically loaded
Token validity checked
User identity restored
Library and player features initialised
Real-time connection to server established

Result: Seamless experience - no re-login required

Session Expiry Detection

Llamafin monitors session health through:

Automatic Checks:

Every API call validates token status
Periodic health checks every 5 minutes while online
Server response monitoring for authentication failures

When Session Expires:

You're automatically returned to the login screen
No data loss - library and settings preserved
Re-login restores your complete session

Security Architecture

Password Security

Llamafin Never Stores Passwords:

Passwords sent only to Jellyfin server
No local password storage
No password caching
No password encryption keys stored

Transmission Security:

HTTPS support for encrypted transmission
Token-based auth after initial login
Server certificate validation

Token-Based Authentication

After login, Llamafin uses tokens instead of passwords:

How Tokens Work:

Server issues unique authentication token
Token attached to all subsequent requests
Token identifies you without re-sending credentials
Server can invalidate tokens if needed

Token Lifecycle:

Issued on successful login
Stored securely on device
Attached to API calls automatically
Validated on every server interaction
Removed on logout or expiry

User Identity Hashing

For privacy in peer-to-peer features:

SHA-256 Hashing:

User ID cryptographically hashed
Hash is one-way (cannot be reversed)
Used only for device discovery
Protects real user identity on network

Why This Matters:

Other devices see hash, not your username
Prevents username exposure on local network
Maintains P2P functionality
Zero-knowledge identity verification

Route Protection

Protected features require authentication:

Guarded Routes:

Home page
Library browsing
Search
Settings
Downloads

Public Routes (no login needed):

Login screen
Server information
Public user list

Navigation Guard:

Blocks access until session confirmed
Redirects to login if unauthenticated
Preserves intended destination for return

HTTP Security Pipeline

Six-Layer Interceptor System

Every HTTP request passes through security checks:

Layer	Function	What It Does
1. Server URL	Routing	Ensures request goes to correct server
2. Error Handling	Monitoring	Catches and logs network errors
3. Authentication	Token Injection	Automatically adds your auth token
4. Retry Logic	Reliability	Retries failed requests automatically
5. Cache Prevention	Freshness	Prevents stale data from cache
6. Unauthorized Handler	Session Management	Detects invalid sessions

Token Injection

Automatic Process:

Request intercepted before sending
Authentication status checked
If authenticated and token valid:
- Token added to request header
- Request sent to server
If token expired:
- Request stopped
- Session expired event triggered
- Return to login screen

Unauthorized Access Detection

What Triggers Detection:

HTTP 401 (Unauthorized) response
HTTP 403 (Forbidden) response
Token validation failures

Response to Detection:

Session immediately invalidated
All stored credentials cleared
User redirected to login
Clear indication of session expiry

Forgot Password Flow

Two-Step Recovery

Jellyfin's built-in password recovery:

Step 1: Initiate Recovery

Enter your username on login screen
Click "Forgot Password"
Server determines recovery method:
- Contact Admin: Administrator must reset
- PIN Code: PIN file generated
- In-Network Required: Must be on local network

Step 2: Complete Recovery

For PIN Code Method:

Server displays PIN file image
Note the PIN code shown
Return to Llamafin login
Enter PIN code when prompted
Password reset successful
Set new password via Jellyfin web interface

Important Notes:

PIN codes expire (server-controlled)
May require server administrator contact
Network location may matter for security

Multi-User Support

Public User Display

Server administrators can control login experience:

User Visibility Settings:

"Show on login screen" per user
Administrator controlled
Privacy for hidden accounts
Quick selection for family members

Login Screen Features:

User avatars displayed
One-click username selection
Password entry only required
Last login dates tracked

User Profiles

Each user maintains separate:

Authentication credentials
Library access permissions
Playback history
Downloaded content
Settings preferences
Playback queues

Complete Isolation:

No data shared between users
Separate offline downloads
Independent playback sessions
Individual settings

Peer-to-Peer Security

Llamafin Connect Identity

For remote control and remote control features:

Cryptographic Device Identity:

Key pair generated per device
Public key shared on network
Private key never leaves device
Device identity cryptographically signed

Secure Discovery:

Devices announce presence via mDNS/Bonjour
Identity verified through key exchange
Session encryption established
Man-in-the-middle protection

User Anonymization:

Real user ID never broadcast
SHA-256 hash used instead
Hash cannot be reversed to username
Network observers cannot identify you

Pairing Security

When connecting devices:

Both devices display pairing codes
Codes must match (visual verification)
Encrypted channel established
Session keys exchanged
Secure communication begins

Protection Against:

Unauthorized device pairing
Eavesdropping on local network
Replay attacks
Identity spoofing

Logout & Data Clearance

User-Initiated Logout

What Happens:

All stored credentials permanently deleted
Authentication token destroyed
User ID hash removed
Session state reset
Navigation to login screen

What's Preserved:

App settings (theme, language, etc.)
Downloaded content (if any)
Server connection info
Feature preferences

Storage Clearance Details

Removed on Logout:

Data Type	Storage Location	Removal
Auth token	IndexedDB/Preferences	✅ Deleted
User ID	IndexedDB/Preferences	✅ Deleted
User ID hash	IndexedDB/Preferences	✅ Deleted

Retained After Logout:

Data Type	Storage Location	Retention
App settings	IndexedDB/Preferences	✅ Kept
Server URL	IndexedDB/Preferences	✅ Kept
Downloaded media	File System	✅ Kept
Appearance prefs	IndexedDB/Preferences	✅ Kept

Session Monitoring

Health Checks

Llamafin continuously monitors session status:

Background Monitoring:

API call responses checked for auth failures
Periodic user profile validation every 5 minutes
WebSocket connection status tracked
Network connectivity verified

User Notifications:

Session expiry toast notification
Clear message explaining required re-login
No silent failures or unexpected behaviour

Network Awareness

Online/Offline Detection:

Session checks paused when offline
Automatic resume when connectivity restored
No false session expiry from network blips
Offline queue for pending operations

Security Best Practices

For Users

Recommended Actions:

Use strong passwords on Jellyfin server
Enable HTTPS for server communication
Regularly review active sessions in Jellyfin
Log out from shared or public devices
Keep Llamafin updated for security patches

When to Re-Login:

After password change on server
If session unexpectedly expires
After server security policy changes
When using shared devices

For Administrators

Server-Side Controls:

Configure user visibility appropriately
Set session timeout policies
Monitor active sessions
Enable/disable Quick Connect as needed
Configure password recovery methods

Authentication Flow Diagrams

User enters credentials
        ↓
Llamafin validates input
        ↓
POST to Jellyfin /Users/AuthenticateByName
        ↓
Server validates credentials
        ↓
Server returns authentication token
        ↓
Llamafin stores token securely
        ↓
Computes SHA-256 hash of user ID
        ↓
Updates settings with user info
        ↓
Navigates to home page
        ↓
Initialises library and player features

Session Rehydration Flow

App starts
        ↓
Loads stored authentication token
        ↓
Token exists and not expired?
    ├─ NO → Redirect to login
    └─ YES
        ↓
Loads user ID and hash
        ↓
Session marked as "rehydrated"
        ↓
Connects to Jellyfin via WebSocket
        ↓
Fetches complete user profile
        ↓
All features unlocked and ready

Token Attachment Flow

User action triggers API call
        ↓
Request intercepted
        ↓
Check if URL is public endpoint
    ├─ YES → Send without token
    └─ NO
        ↓
Wait for session rehydration complete
        ↓
Token expired?
    ├─ YES → Stop request, redirect to login
    └─ NO
        ↓
Attach token to request header
        ↓
Send to server
        ↓
Response received
        ↓
401/403 error?
    ├─ YES → Session expired, redirect to login
    └─ NO → Return data to app

Technical Specifications

Specification	Implementation
Authentication Method	Token-based (Jellyfin access token)
Password Storage	Never stored locally
Token Storage	IndexedDB / Capacitor Preferences
Token Expiry	Server-controlled
Session Validation	Periodic /Users/Me health checks
Health Check Interval	Every 5 minutes while online
Hashing Algorithm	SHA-256 (Web Crypto API)
Hash Purpose	P2P device identity anonymization
Route Protection	Observable-based AuthGuard
HTTP Security	6-layer interceptor pipeline
Public Endpoints	/System/Info/Public, /Users/AuthenticateByName, /Users/Public
Session Monitoring	WebSocket + periodic API checks
Logout Data Clearance	Complete credential removal

Overview​

Login Methods​

Standard Username & Password​

Quick Connect​

Public User Selection​

Session Management​

Automatic Session Persistence​

Session Rehydration​

Session Expiry Detection​

Security Architecture​

Password Security​

Token-Based Authentication​

User Identity Hashing​

Route Protection​

HTTP Security Pipeline​

Six-Layer Interceptor System​

Token Injection​

Unauthorized Access Detection​

Forgot Password Flow​

Two-Step Recovery​

Step 1: Initiate Recovery​

Step 2: Complete Recovery​

Multi-User Support​

Public User Display​

User Profiles​

Peer-to-Peer Security​

Llamafin Connect Identity​

Pairing Security​

Logout & Data Clearance​

User-Initiated Logout​

Storage Clearance Details​

Session Monitoring​

Health Checks​

Network Awareness​

Security Best Practices​

For Users​

For Administrators​

Authentication Flow Diagrams​

Standard Login Flow​

Session Rehydration Flow​

Token Attachment Flow​

Technical Specifications​

Related Documentation​