git-echo/linux_patch_manager
Private
Public Access
1
0
Fork 0
Code Releases 8 Wiki Activity
Files
f58d7a6f17aa1f66f1805da950a0f5f64aa1b754
linux_patch_manager/docs/REST_API.md
Draco-Lunaris-Echo f58d7a6f17 fix(security): stop embedding JWT tokens in SSO callback redirect URL (#4) (#14) 
Replaces URL-embedded JWT tokens with a single-use, 60-second handoff code that the SPA exchanges via server-to-server POST. The URL now contains only `?handoff=<code>` — no tokens are placed in the browser history, proxy access logs, or Referer header.

Backend: new SsoHandoff store (DashMap, 60s TTL, atomic DashMap::remove for single-use), POST /api/v1/auth/sso/handoff endpoint, 7 new tests.

Frontend: SsoCallbackPage rewritten to use useSearchParams + POST exchange, with history.replaceState to clear the handoff code from the address bar. Switched from window.location.search to useSearchParams() for test compatibility. New Vitest infrastructure (vitest, @testing-library/react, jsdom) and 6 new tests.

CI fix in ccba9e3: cargo fmt --all and added searchParams to useEffect dep array to satisfy CI's Rust Format and Frontend Lint checks.

Refs: closes #4
2026-06-03 06:28:08 -05:00

6.6 KiB
Raw Blame History

Linux Patch Manager REST API Reference

Base URL: /api/v1/ Content-Type: application/json Security: JWT Bearer Token (except Public Endpoints)

1. Authentication & Session

Method Endpoint Description
POST /auth/login Authenticate user
POST /auth/logout Invalidate current session
POST /auth/refresh Refresh JWT token
GET /auth/mfa/setup Generate MFA setup QR/code
POST /auth/mfa/verify Verify MFA code
DELETE /auth/mfa Disable MFA for user

1b. SSO (Single Sign-On)

No authentication required. These endpoints implement the OIDC Authorization Code + PKCE flow. See tasks/sso-token-handoff-spec.md for the full design.

Method Endpoint Description
GET /auth/sso/login Initiate OIDC login: redirects browser to the configured IdP's authorization URL
GET /auth/sso/callback OIDC redirect URI: handles the IdP response, issues a single-use 60s handoff_code, stores the JWT access/refresh tokens in memory, and 302-redirects to the SPA with ?handoff=<code> in the URL (no tokens in the URL — see issue #4)
GET /auth/sso/config Returns minimal SSO configuration for the login page (enabled, display_name, auth_url). No secrets exposed
POST /auth/sso/handoff (new in issue #4) Exchange a single-use handoff_code for the JWT access/refresh tokens. The SPA calls this from SsoCallbackPage after the OIDC callback redirect. Returns { access_token, refresh_token, token_type, expires_in, user }. The code is single-use, 60s TTL, and atomically removed on exchange (concurrent attempts: exactly one wins). 400 invalid_handoff on unknown/expired/already-consumed codes

2. Public Endpoints (Self-Enrollment)

No authentication required.

Method Endpoint Description
POST /enroll Submit host enrollment request
GET /enroll/status/{token} Poll enrollment approval status & retrieve PKI

3. Administration (Enrollment Queue)

Requires Admin role.

Method Endpoint Description
GET /admin/enrollments List pending enrollment requests
POST /admin/enrollments/{id}/approve Approve request, generate PKI, migrate to hosts
DELETE /admin/enrollments/{id}/deny Deny and purge enrollment request

4. Host Management

Method Endpoint Description
GET /hosts List managed hosts
POST /hosts Register host manually
GET /hosts/{id} Get host details
DELETE /hosts/{id} Remove host
POST /hosts/{id}/refresh Trigger on-demand data refresh
DELETE /hosts/{id}/groups/{group_id} Remove host from group

5. Certificate Management

Method Endpoint Description
GET /ca/root.crt Download Root CA certificate
GET /certificates List issued certificates (grouped by status/host)
DELETE /certificates/{cert_id} Revoke certificate
POST /certificates/{cert_id}/renew Renew certificate
POST /hosts/{host_id}/certificates Issue client certificate for host
POST /hosts/{host_id}/certificates/reissue Reissue host certificates
GET /hosts/{host_id}/client.crt Download client certificate

6. Discovery & Network Scanning

Method Endpoint Description
POST /discovery/cidr Start CIDR network scan
GET /discovery/{scan_id} Get scan results
POST /discovery/{id}/register Register discovered host

7. Jobs & Patch Deployment

Method Endpoint Description
GET /jobs List patch jobs
POST /jobs Create new patch job
GET /jobs/{id} Get job status/details
POST /jobs/{id}/cancel Cancel running job
POST /jobs/{id}/rollback Rollback completed job

8. Maintenance Windows

Scoped to host.

Method Endpoint Description
GET /hosts/{host_id}/maintenance-windows List windows for host
POST /hosts/{host_id}/maintenance-windows Create window
PUT /hosts/{host_id}/maintenance-windows/{win_id} Update window
DELETE /hosts/{host_id}/maintenance-windows/{win_id} Delete window

9. Health Checks

Method Endpoint Description
GET /health-checks List health checks
POST /health-checks Create health check
POST /health-checks/{check_id}/test Run manual health check

10. Users & Groups

Method Endpoint Description
GET /users List users
POST /users Create user
GET /users/{id} Get user details
PUT /users/{id} Update user
DELETE /users/{id} Delete user
PUT /users/{id}/password Admin reset password
POST /users/{id}/revoke Revoke all user sessions
DELETE /users/{id}/mfa Admin disable MFA
GET /users/me Get current authenticated user
PUT /users/me/password Change own password
GET /groups List groups
POST /groups Create group

11. Settings & Configuration

Method Endpoint Description
GET /settings Get system settings
PUT /settings Update system settings
POST /settings/smtp/test Test SMTP configuration
POST /settings/sso/discover Discover OIDC provider config
POST /settings/sso/test Test SSO connection
POST /settings/azure-sso/test Test Azure SSO compatibility
POST /settings/audit-integrity Verify audit log integrity

12. Single Sign-On (SSO)

Method Endpoint Description
GET /sso/config Get SSO configuration status
GET /sso/login Initiate SSO login flow
GET /sso/callback Handle SSO provider callback

13. Reports & Status

Method Endpoint Description
GET /status/fleet Get fleet-wide status summary
GET /reports/compliance Generate compliance report
GET /reports/patch-history Generate patch history report
GET /reports/vulnerability Generate vulnerability exposure report
GET /reports/audit Generate audit trail report

14. Real-Time Updates (WebSocket)

Method Endpoint Description
POST /ws/ticket Request WebSocket auth ticket
GET /ws/jobs Upgrade to WebSocket for job streaming