200 lines
7.2 KiB
Markdown
200 lines
7.2 KiB
Markdown
# Auth Login Patterns
|
||
|
||
**Selector:** Set this once per project.
|
||
```
|
||
ACTIVE_LOGIN_METHOD=pb-oauth-via-microsoft
|
||
```
|
||
(Other methods can be added; only one should be active.)
|
||
|
||
---
|
||
|
||
## Environment Variables
|
||
|
||
### Required Variables
|
||
|
||
**Azure AD / Microsoft Authentication:**
|
||
- `CLIENT_ID` - Azure AD Application Client ID
|
||
- `CLIENT_SECRET` - Azure AD Application Client Secret
|
||
- `TENANT_ID` - Azure AD Tenant ID
|
||
- `REDIRECT_URI` - OAuth redirect URI
|
||
|
||
**PocketBase:**
|
||
- `PB_DB` - PocketBase database URL (e.g., `https://pocketbase.ccllc.pro`)
|
||
- `PB_COLLECTION` - Collection name for job data (e.g., `Job_Info_TestEnv`)
|
||
- `PB_AUTH_COLLECTION` - Collection name for user authentication (e.g., `Users`)
|
||
|
||
**Redis/Valkey (Caching & Search):**
|
||
- `REDIS_URL` - Redis/Valkey connection URL (e.g., `redis://localhost:6379` or `redis://redis-server:6379`)
|
||
- If not provided, defaults to `redis://localhost:6379`
|
||
- For production, connect to the same Redis/Valkey instance as Job-Info-Prod
|
||
|
||
**Optional:**
|
||
- `PORT` - Server port (default: 3025)
|
||
|
||
---
|
||
|
||
## Caching & Search
|
||
|
||
This application uses Redis/Valkey for:
|
||
|
||
1. **Data Caching**: Job records are cached for 5 minutes (300 seconds) to reduce PocketBase queries
|
||
2. **Search Results Caching**: Search results are cached for 3 minutes (180 seconds)
|
||
3. **Cache Invalidation**: Automatically clears cache when data is updated
|
||
|
||
### API Endpoints
|
||
|
||
**Get All Jobs (with caching):**
|
||
```
|
||
GET /api/jobs
|
||
Headers: X-PocketBase-Token: <user_token>
|
||
```
|
||
|
||
**Search Jobs (with caching):**
|
||
```
|
||
GET /api/jobs/search?q=<query>
|
||
Headers: X-PocketBase-Token: <user_token>
|
||
```
|
||
Searches across: Job_Number, Job_Full_Name, Job_Name, Company_Client, Contact_Person, Estimator, Job_Status, Project_Manager, Notes
|
||
|
||
**Clear Cache (admin):**
|
||
```
|
||
POST /api/cache/clear
|
||
Headers: X-PocketBase-Token: <user_token>
|
||
```
|
||
|
||
### Cache Strategy
|
||
|
||
- **Source of Truth**: PocketBase remains the source of truth for updates
|
||
- **Read Operations**: Check cache first, fallback to PocketBase if cache miss
|
||
- **Write Operations**: Update PocketBase, then invalidate cache
|
||
- **Future**: Will switch to Job-Info-Prod for production data synchronization
|
||
|
||
---
|
||
|
||
## Shared Rules (All Methods)
|
||
- Serve frontend from the project’s `frontend` folder; show login UI only when not authenticated.
|
||
- Secrets come from `.env`; never hardcode or log secrets/tokens.
|
||
- Token storage: use in-memory auth store (avoid localStorage/sessionStorage unless explicitly required).
|
||
- On logout, clear the auth store and hide the protected UI.
|
||
- Log only context + message; exclude raw tokens or secrets.
|
||
|
||
---
|
||
|
||
## Method: pb-oauth-via-microsoft (PocketBase + Microsoft)
|
||
**Frontend**
|
||
- Use PocketBase SDK OAuth (`provider: 'microsoft'`).
|
||
- Show login button when `!pb.authStore.isValid`; hide the form until valid.
|
||
- On success: keep token in `pb.authStore`; display user email; show logout.
|
||
- On logout: `pb.authStore.clear()`; hide protected UI.
|
||
|
||
**Backend**
|
||
- Endpoints expecting auth (e.g., `/api/submit`) must receive `pbToken`.
|
||
- Call `setUserPocketBaseAuth(pbToken)` before PocketBase operations.
|
||
- Required `.env` keys: `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`, `REDIRECT_URI`, `PB_DB`, `PB_COLLECTION`, `PB_AUTH_COLLECTION`.
|
||
- Validate token via PocketBase client; reject if missing/invalid.
|
||
- Do not log tokens; log context and error message only.
|
||
|
||
**UI States**
|
||
- Logged out: show login UI only.
|
||
- Logged in: hide login UI, show form/app content.
|
||
- Errors: show a visible error container; avoid alert loops.
|
||
|
||
**Security**
|
||
- Enforce CORS as needed; HTTPS in production.
|
||
- Keep `.env` out of version control; use deploy-time secrets.
|
||
|
||
---
|
||
|
||
## Method: pb-and-graph-via-microsoft (PocketBase + Microsoft Graph)
|
||
**Frontend**
|
||
- Same UI pattern as `pb-oauth-via-microsoft` (PocketBase OAuth `provider: 'microsoft'`).
|
||
- Show login when `!pb.authStore.isValid`; hide protected UI until valid.
|
||
- On success: keep token in `pb.authStore`; display user email; show logout; on logout clear auth store.
|
||
|
||
**Backend**
|
||
- Expect `pbToken` on protected endpoints; call `setUserPocketBaseAuth(pbToken)` before PB operations.
|
||
- Acquire Graph token via client credentials for Excel sync.
|
||
- Required `.env` keys:
|
||
- Azure AD: `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`, `REDIRECT_URI`
|
||
- PocketBase: `PB_DB`, `PB_COLLECTION`, `PB_AUTH_COLLECTION`
|
||
- Graph/Excel: `DRIVE_ID`, `ITEM_ID`, `EXCEL_TABLE`, `EXCEL_TABLE_WRITEBACK` (if used)
|
||
- Use Graph scope: `https://graph.microsoft.com/.default`
|
||
- Do not log tokens; log context + message only.
|
||
|
||
**Token Handling**
|
||
- PocketBase token (user): stored in memory via `pb.authStore`; sent to backend as `pbToken`.
|
||
- Graph token (app): obtained server-side via client credentials; never exposed to frontend; short-lived, fetched on demand.
|
||
|
||
**UI States**
|
||
- Logged out: show login UI only.
|
||
- Logged in: hide login UI, show form/app content.
|
||
- Errors: show visible error container; avoid alert loops.
|
||
|
||
**Security**
|
||
- Enforce CORS as needed; HTTPS in production.
|
||
- Keep `.env` out of version control; use deploy-time secrets.
|
||
- Do not log raw tokens or secrets.
|
||
|
||
---
|
||
|
||
## Method: PBandGraphOauth (PocketBase + Microsoft Graph OAuth)
|
||
**Frontend**
|
||
- Use PocketBase SDK OAuth (`provider: 'microsoft'`).
|
||
- Show login button when `!pb.authStore.isValid`; hide protected UI until valid.
|
||
- On success: keep token in `pb.authStore`; display user email; show logout.
|
||
- On logout: `pb.authStore.clear()`; hide protected UI.
|
||
|
||
**Backend**
|
||
- Endpoints expecting auth (e.g., `/api/submit`) must receive `pbToken` from the frontend.
|
||
- Call `setUserPocketBaseAuth(pbToken)` before PocketBase operations.
|
||
- Obtain a Microsoft Graph access token using Azure AD app credentials.
|
||
- Required `.env` keys (exactly from current `.env`):
|
||
- Azure AD: `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`, `REDIRECT_URI`
|
||
- PocketBase: `PB_DB`, `PB_COLLECTION`, `PB_AUTH_COLLECTION`
|
||
- Graph token scope: `https://graph.microsoft.com/.default`.
|
||
- Never log raw tokens or secrets; log only context + messages.
|
||
|
||
**Token Handling**
|
||
- PocketBase token (user): stored in memory via `pb.authStore`; sent to backend as `pbToken` on protected calls.
|
||
- Graph token (app): acquired server-side via client credentials using `CLIENT_ID`/`CLIENT_SECRET`/`TENANT_ID`; never exposed to the frontend.
|
||
|
||
**UI States**
|
||
- Logged out: show login UI only.
|
||
- Logged in: hide login UI; show protected UI.
|
||
- Errors: show a visible error container; avoid alert loops.
|
||
|
||
**Security**
|
||
- Enforce CORS as needed; HTTPS in production.
|
||
- Keep `.env` out of version control; use deploy-time secrets.
|
||
- Do not log raw tokens or secrets.
|
||
|
||
---
|
||
|
||
## Adding Another Method (Template)
|
||
```
|
||
# Example selector
|
||
ACTIVE_LOGIN_METHOD=custom-sso
|
||
|
||
Frontend:
|
||
- Describe SDK/flow
|
||
- Show/hide rules
|
||
- Token storage rules
|
||
|
||
Backend:
|
||
- How tokens are validated
|
||
- Required .env keys
|
||
- How errors are logged/returned
|
||
|
||
Security:
|
||
- CORS/HTTPS rules
|
||
- Logging redactions
|
||
```
|
||
|
||
---
|
||
|
||
## How to Use
|
||
1) Copy this folder into a new project (outside your app code) or reference it as the canonical auth guide.
|
||
2) Set `ACTIVE_LOGIN_METHOD` to the one in use.
|
||
3) Follow only the active method; do not mix flows.
|
||
4) Keep .env values in deploy-time secrets; never commit them.
|