Architecture
Understanding Nuxt Aegis architecture and authentication flows.
Overview
Nuxt Aegis implements a secure OAuth 2.0 + JWT authentication system with token refresh and authorization CODE flow.
Key Components
Client-Side Components
useAuth()Composable - Reactive authentication state management$apiPlugin - Authenticated API calls with automatic bearer token injection and 401 refresh/retry when automatic refresh is enabled- Router Middleware - Client-side route protection
- Token Storage - JWT access token management
- Refresh Cookie - HttpOnly refresh token cookie
Server-Side Components
- OAuth Routes - Handle OAuth flows (
/auth/{provider}) - Token Endpoints - Token exchange and refresh (
/auth/token,/auth/refresh) - Server Middleware - Automatic route protection
- Server Utils -
requireAuth(),getAuthUser() - Storage Layer - Persistent refresh token storage (Redis/filesystem)
Authentication Flow
Detailed authentication flow documentation:
Architecture Diagrams
High-Level Flow
The OAuth callback creates the short-lived Aegis authorization CODE, not the application's refresh token. After the client exchanges that CODE at POST /auth/token, the server creates and stores an Aegis refresh token (if enabled) and sets its HttpOnly cookie on the token-exchange response. This token is separate from any refresh token returned by the OAuth provider.
Token Refresh Flow
Route Protection Flow
Nuxt Aegis enforces authentication on protected routes by verifying the JWT and applying configured issuer and audience checks. It does not automatically enforce roles or permissions. The authorization check and 403 response shown above must be implemented by application route handlers or middleware; an authenticated user is not necessarily authorized for an operation.
Security Layers
JWT signing and verification use a shared symmetric secret, with HS256 as the default algorithm. RS256 is not supported yet by the current key handling: setting token.algorithm to 'RS256' does not import an RSA key and causes signing to fail.
Data Flow
User Data Storage
User-info transformation uses the provider-level onUserInfo callback when configured, otherwise the global Aegis handler's onUserInfo callback.
Refresh token records are stored in plaintext by default. To enable AES-256-GCM encryption at rest, set nuxtAegis.tokenRefresh.encryption.enabled to true and configure an encryption key. See Storage Configuration.
Token Types
| Token Type | Lifetime | Storage | Purpose |
|---|---|---|---|
| Authorization CODE | 60 seconds | Memory | Exchange for JWT |
| JWT Access Token | 1 hour | Client (memory only) | API authentication |
| Refresh Token | 7 days | Server (Redis/filesystem) | Generate new JWTs |
| OAuth Provider Tokens | Provider-dependent | Request-local only; not persisted by Aegis | Fetch user info and supply configured callbacks |
Provider tokens remain available to OAuth user-info and provider-level custom-claims callbacks, provider-level success callbacks, and global success hooks during authentication. Aegis does not store them in authCodeStore; the authorization-code record contains user information, provider identity, resolved custom claims, and creation and expiration timestamps. Aegis token exchange and refresh do not require provider tokens. Application callbacks remain responsible for any credentials they explicitly persist or copy into user data or custom claims.
Module Integration
Performance Considerations
Caching Strategy
- JWT tokens: Short-lived (1h) to balance security and performance
- Refresh tokens: Long-lived (7 days) to minimize re-authentication
- User data and custom claims: Stored with the refresh token and reused during ordinary refresh; no user-data reload or claims recomputation
To recompute claims explicitly, use refresh({ updateClaims: true }), which calls /auth/update-claims before refreshing the token. See Updating JWT Claims. Without an explicit update, stored roles and permissions can remain stale.
Scalability
- Stateless JWTs: No server-side session storage for access tokens
- Redis storage: Horizontal scaling for refresh tokens
- Token refresh: Automatic refresh prevents auth interruptions