Skip to content

Commit 6df9bb5

Browse files
aboseabose
committed
docs: login-service-no_dist.md explaning how login works in browser
1 parent fd2ca30 commit 6df9bb5

File tree

2 files changed

+215
-0
lines changed

2 files changed

+215
-0
lines changed

‎src/services/login-browser.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,30 @@
1818

1919
/*global logger*/
2020

21+
/**
22+
* Phoenix Browser Login Service
23+
*
24+
* This module handles user authentication for Phoenix browser applications.
25+
* It integrates with the Phoenix login service to provide secure authentication
26+
* across the phcode.dev domain ecosystem.
27+
*
28+
* IMPORTANT: For detailed setup instructions, development workflows, and
29+
* troubleshooting guide, see: src/services/login-service-no_dist.md
30+
*
31+
* Key Features:
32+
* - Domain-wide session management using 'session' cookie at .phcode.dev level
33+
* - Proxy server support for localhost development (serve-proxy.js)
34+
* - Support for both production (account.phcode.dev) and custom login servers
35+
* - Automatic session validation and user profile management
36+
*
37+
* Development Notes:
38+
* - Production: Uses account.phcode.dev directly with domain-wide cookies
39+
* - Development: Uses /proxy/accounts route through serve-proxy.js for localhost:8000 to account.phcode.dev
40+
* - Session cookies must be manually copied from account.phcode.dev to localhost for testing
41+
*
42+
* @see src/services/login-service-no_dist.md for comprehensive documentation
43+
*/
44+
2145
define(function (require, exports, module) {
2246
const EventDispatcher = require("utils/EventDispatcher"),
2347
PreferencesManager = require("preferences/PreferencesManager"),

‎src/services/login-service-no_dist.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Phoenix Login Service Integration
2+
3+
This document provides comprehensive documentation for integrating with the Phoenix login service in browser applications.
4+
5+
## Overview
6+
7+
The Phoenix browser application uses a login service to authenticate users across the phcode.dev domain ecosystem. The login service handles user authentication, session management, and provides secure API endpoints for login operations.
8+
9+
**Key Files:**
10+
- `src/services/login-browser.js` - Main browser login implementation
11+
- `serve-proxy.js` - Proxy server for localhost development
12+
- This documentation file for detailed integration guide
13+
14+
## Architecture
15+
16+
### Production Environment
17+
18+
In production, the browser application uses `https://account.phcode.dev` as the login service endpoint.
19+
20+
**Domain-Wide Session Management:**
21+
- Login service sets a `session` cookie at the `.phcode.dev` domain level
22+
- This cookie is automatically shared across all subdomains:
23+
- `phcode.dev`
24+
- `dev.phcode.dev`
25+
- `*.phcode.dev` (any subdomain)
26+
- Users login once and stay authenticated across the entire ecosystem
27+
28+
**Communication Flow:**
29+
```
30+
Browser App (*.phcode.dev) → account.phcode.dev
31+
← session cookie set for .phcode.dev
32+
```
33+
34+
### Development Environment (localhost:8000)
35+
36+
**Challenge:**
37+
localhost:8000 doesn't share the `.phcode.dev` domain, so session cookies from account.phcode.dev are not automatically available.
38+
39+
**Solution:**
40+
Manual session cookie copying with proxy server routing.
41+
42+
#### Proxy Server Architecture
43+
44+
The `serve-proxy.js` server handles API routing for localhost development:
45+
46+
```
47+
Browser (localhost:8000) → /proxy/accounts/* → serve-proxy.js → https://account.phcode.dev/*
48+
← Response with cookies
49+
← Cookies forwarded back to browser
50+
```
51+
52+
**Key Function in login-browser.js:**
53+
```javascript
54+
function _getAccountBaseURL() {
55+
if (location.hostname === 'localhost' || location.hostname === '127.0.0.1') {
56+
return '/proxy/accounts'; // Use proxy for localhost
57+
}
58+
return Phoenix.config.account_url.replace(/\/$/, ''); // Direct URL for production
59+
}
60+
```
61+
62+
## Development Setup Instructions
63+
64+
### Standard Development (localhost:8000 → account.phcode.dev)
65+
66+
1. **Login to Production Account Service:**
67+
- Open browser and navigate to `https://account.phcode.dev`
68+
- Login with your credentials
69+
- Account service sets `session` cookie for `.phcode.dev` domain
70+
71+
2. **Copy Session Cookie to Localhost:**
72+
- Open Chrome DevTools (F12) on `https://account.phcode.dev`
73+
- Go to Application → Cookies → `https://account.phcode.dev`
74+
- Find the `session` cookie and copy its value
75+
76+
3. **Set Cookie in Localhost App:**
77+
- Navigate to `http://localhost:8000/src/`
78+
- Open Chrome DevTools (F12)
79+
- Go to Application → Cookies → `http://localhost:8000`
80+
- Create new cookie:
81+
- **Name:** `session`
82+
- **Value:** [paste copied value]
83+
- **Domain:** `localhost`
84+
- **Path:** `/`
85+
- **HttpOnly:** ✓ (check if available)
86+
87+
4. **Verify Integration:**
88+
- Refresh `http://localhost:8000/src/`
89+
- Login should work automatically using the copied session
90+
91+
### Custom Login Server Development (localhost:5000)
92+
93+
For testing with a local account server instance:
94+
95+
1. **Configure Proxy Server:**
96+
- Edit `serve-proxy.js`
97+
- **Comment out:** `const ACCOUNT_SERVER = 'https://account.phcode.dev'; // Production`
98+
- **Uncomment:** `const ACCOUNT_SERVER = 'http://localhost:5000'; // Local development`
99+
100+
2. **Setup Local Account Server:**
101+
- Start your local account development stack on `localhost:5000`
102+
- Ensure all login endpoints are properly configured
103+
104+
3. **Login and Copy Session:**
105+
- Navigate to `http://localhost:5000` in browser
106+
- Login with test credentials
107+
- Copy `session` cookie value from DevTools
108+
109+
4. **Set Cookie in Phoenix App:**
110+
- Navigate to `http://localhost:8000/src/`
111+
- Open Chrome DevTools → Application → Cookies
112+
- Create `session` cookie with copied value (same process as above)
113+
114+
5. **Verify Local Integration:**
115+
- API calls from localhost:8000 now route through serve-proxy.js to localhost:5000
116+
- Authentication should work with local account server
117+
118+
## API Endpoints
119+
120+
The login service provides these key endpoints:
121+
122+
### Authentication
123+
- `POST /signOutPost` - Sign out user (new endpoint with proper JSON handling)
124+
- `GET /resolveBrowserSession` - Validate and resolve current session
125+
- `GET /signOut` - Legacy signout endpoint (deprecated for browser use)
126+
127+
### Session Management
128+
- Session validation through `session` cookie
129+
- Automatic session invalidation on logout
130+
- Session sharing across domain ecosystem
131+
132+
## Communication Paths
133+
134+
### Production (phcode.dev subdomains):
135+
```
136+
Browser App → Direct HTTPS → account.phcode.dev
137+
← Session cookie for .phcode.dev ←
138+
```
139+
140+
### Development (localhost):
141+
```
142+
Browser (localhost:8000) → /proxy/accounts/* → serve-proxy.js
143+
↓
144+
account.phcode.dev (or localhost:5000)
145+
↓
146+
← API response ← serve-proxy.js
147+
```
148+
149+
## Troubleshooting
150+
151+
### Common Issues
152+
153+
**1. "No session found" errors:**
154+
- Verify `session` cookie is set correctly in browser
155+
- Check cookie domain and path settings
156+
- Ensure cookie hasn't expired
157+
158+
**2. CORS errors in development:**
159+
- Verify serve-proxy.js is running on port 8000
160+
- Check proxy configuration in serve-proxy.js
161+
- Confirm account server URL is correct
162+
163+
**3. Login popup doesn't appear:**
164+
- Check if popup blockers are enabled
165+
- Verify account service URL is accessible
166+
- Check browser console for JavaScript errors
167+
168+
**4. Session not persisting:**
169+
- Ensure cookie is set with correct domain
170+
- Check if HttpOnly flag is properly configured
171+
- Verify account service is responding correctly
172+
173+
### Development Tips
174+
175+
1. **Always use Chrome DevTools** to inspect cookies and network requests
176+
2. **Monitor Network tab** to see actual API calls and responses
177+
3. **Check Console** for authentication-related errors
178+
4. **Verify proxy routing** by checking serve-proxy.js logs
179+
5. **Test both login and logout flows** to ensure complete functionality
180+
181+
## Security Considerations
182+
183+
- Session cookies are HttpOnly and secure in production
184+
- Always use HTTPS in production environments
185+
- Local development should never use production user credentials in local account servers
186+
- Session cookies should have appropriate expiration times
187+
- Logout should properly invalidate sessions on both client and server
188+
189+
---
190+
191+
For implementation details, see the source code in `src/services/login-browser.js` and related files.

0 commit comments

Comments
 (0)