Metadata management
Understanding how session and user information are handled by light-auth.
Overview
Light-Auth implements a secure, modern authentication flow based on JWT tokens.
This page explains what is the session token and the difference between the session object, retrieved with getAuthSession() and the user object, retrieved with getUser().
Session vs User: Core Concept
Light-Auth's key innovation is how it handles authentication data. When a user authenticates through an OAuth2/OpenID provider, Light-Authreceives a JWT token containing user information and credentials.
Instead of storing everything in one place, Light-Auth strategically splits this data into two objects:
Why This Approach?
- Performance: Session data in cookies enables fast authentication checks without database queries
- Size Management: Avoids cookie size limitations (~4KB) by storing larger metadata in backend storage
- Security: Keeps sensitive tokens in secure backend storage while maintaining convenient authentication
- Flexibility: Allows different storage mechanisms for different types of data
This separation creates a clean, efficient authentication system where developers can quickly verify a user's identity with await getAuthSession() for common authentication needs, while accessing complete user data with await getUser() only when necessary.
Authentication Workflow
Session vs User Comparison
| Feature | Session | User |
|---|---|---|
| Storage Location | Cookie | Backend store (file system or database) |
| Data Size | Minimal (~4KB limit) | Can be larger (no cookie size limitation) |
| Stored Data |
|
|
| Retrieval Method | await getAuthSession() | await getUser() |
| Storage Mechanism | SessionStore → Cookie | UserAdapter → FileUserAdapter or DatabaseAdapter |
| Purpose | Quick authentication checks | Access to complete user profile and tokens |
Workflow Details
The Light-Auth framework provides a streamlined authentication workflow for SSR applications:
- 1
User Initiates Login
The user clicks a login button in your application, which triggers a request to Light-Auth.
- 2
OAuth2/OpenID Provider Authentication
Light-Auth redirects the user to the selected authentication provider (Google, GitHub, Microsoft, etc.) where they authenticate.
- 3
Token Exchange
After successful authentication, the provider returns an authorization code. Light-Auth exchanges this code for tokens (JWT, access token, refresh token) and user information.
- 4
Session Creation
Light-Auth extracts essential authentication data (userId, sessionId, email, expirationDate) and creates a Session object. This is stored in a cookie via the SessionStore.
- 5
User Data Storage
Light-Auth creates a User object with complete metadata (access token, refresh token, provider details, etc.) and stores it in a backend store via the UserAdapter.
- 6
Data Retrieval
In your application, you can access the session data with
await getAuthSession()for quick authentication checks, and the complete user data withawait getUser()when needed.
Key Benefit
This separation allows Light-Auth to maintain essential authentication data in cookies for quick access while storing larger user metadata in a more appropriate backend storage solution, avoiding cookie size limitations.