Add PBandGraphOauth scaffold and auth UI
This commit is contained in:
@@ -0,0 +1,136 @@
|
||||
# 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.)
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user