Skip to content

20260210-authentication

📋 Draft

Status: ✅ Implemented Date: 2026-02-10 Version: 2.0 Priority: High

Overview

Implement authentication for the NextPM website to protect the Prompt Library while keeping all other content public including engineering documentation. The solution uses Azure AD (Microsoft Entra ID) OAuth-based authentication for secure, enterprise-grade access control.

Problem

Current State:

  • NextPM website is completely public and accessible to anyone
  • Prompt library represents valuable intellectual property with no protection
  • No authentication or access control exists
  • Azure Static Web Apps resource is deployed but has no authentication configured

Pain Points:

  • Cannot protect prompt library templates and examples
  • Prompts represent curated intellectual property that should be restricted
  • No way to track who is accessing the prompt library
  • Public content (home, engineering, examples, about pages) should remain open for teaching and portfolio purposes
  • No way to differentiate access levels between public and protected content

User Impact

Primary Users:

  • Site Owner (PM) - Needs to protect prompt library while keeping other content public
  • Authorized Viewers - Need secure access to prompt library using their Microsoft account
  • Public Visitors - Should be able to access all content except prompt library (home, engineering, examples, about pages)

User Benefits:

  • Protect valuable prompt library intellectual property
  • Maintain full public visibility for engineering documentation, examples, and portfolio
  • Enterprise-grade Azure AD OAuth authentication
  • Guest user invitation support for external collaborators
  • No manual user management overhead (handled by Microsoft Entra ID)
  • No impact on public pages - only /prompts/* requires authentication

Proposed Solution

High-Level Approach

Implement section-based authentication using Azure Static Web Apps' built-in Azure AD (Microsoft Entra ID) OAuth capabilities. Only /prompts/* section requires authentication; all other sections (/, /engineering/*, /examples/*, /about/*) remain public.

Key Features

  1. Azure AD Authentication
  2. Microsoft account OAuth 2.0 integration
  3. Supports internal Azure AD users and external guest users
  4. Enterprise-grade security with no custom credential management

  5. Automatic session management by Azure Static Web Apps

  6. Section-Based Access Control

  7. /prompts/* - Protected (Prompt Library only)
  8. /, /engineering/*, /examples/*, /about/* - Public (no authentication required)

  9. Configured via static web app config file with route rules

  10. User Management

  11. Azure AD users: Managed in Azure Portal (Microsoft Entra ID)
  12. Guest user invitations for external collaborators

  13. No manual user database or password management required

  14. Authentication UI

  15. Automatic redirect to Microsoft login page
  16. Seamless redirect back to requested page after login
  17. Built-in Microsoft OAuth UI (no custom login page needed)

Technical Design

Architecture:

  • Azure Static Web Apps built-in authentication for Azure AD
  • staticwebapp.config.json for route-based access control
  • Microsoft Entra ID for user management
  • MkDocs static site remains unchanged

Authentication Flow:

User → Access /prompts/* → Redirect to /login
      ↓
Microsoft OAuth Login Page
      ↓
User authenticates with Microsoft account
      ↓
OAuth callback to Azure Static Web Apps
      ↓
Session cookie set by Azure Static Web Apps
      ↓
Access Granted → Redirect to Originally Requested Page

Access Control Rules:

Routes:
- /prompts/* → Requires: ["authenticated"]
- /* → Requires: ["anonymous", "authenticated"] (public)

Storage:

  • User accounts: Microsoft Entra ID (Azure cloud)
  • Session: Azure Static Web Apps managed (8-hour default)
  • No custom password storage or session management required

Files Created:

  • staticwebapp.config.json - Core authentication configuration

Files Modified:

  • .github/workflows/azure-deploy.yml - No changes needed (authentication is built-in)

Success Metrics

Completion Criteria

  • staticwebapp.config.json created with route-based access control
  • Azure AD app registration completed and configured
  • Azure Static Web Apps configuration includes all required secrets
  • /prompts/* section requires authentication
  • All other sections (/, /engineering/, /examples/, /about/*) remain public
  • Azure AD authentication successfully grants access
  • Logout functionality works correctly
  • Zero downtime during deployment

Quality Indicators

  • Login completes in under 5 seconds (Azure AD OAuth)
  • Microsoft login page works on all major browsers and mobile devices
  • Clear error messages for invalid credentials (handled by Microsoft)
  • No broken links after authentication is added
  • MkDocs build --strict passes
  • GitHub Actions deployment succeeds

User Acceptance

  • Prompt library is inaccessible without authentication
  • All other content (engineering, examples, about) remains freely accessible
  • Login experience is intuitive using familiar Microsoft login
  • Guest users can be invited for external collaborators
  • No impact on site performance or load times

Implementation Notes

Implementation Steps

  1. Create Azure AD app registration in Microsoft Entra ID
  2. Configure redirect URIs and client secrets
  3. Create staticwebapp.config.json with Azure AD provider configuration
  4. Add Azure AD secrets to Static Web App configuration (AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET)
  5. Deploy and test Azure AD login flow
  6. Document user management process for Azure AD (including guest user invitations)
  7. Create PM and Dev Workflow summaries
  8. Update CLAUDE.md with authentication notes

Technical Constraints

  • Azure Static Web Apps Free Tier (100 GB bandwidth/month, 250 MB app size)
  • Session duration fixed at 8 hours (Azure Static Web Apps default)
  • Requires Azure AD app registration (one-time setup)
  • Guest users require email invitation for external collaborators

Why Azure AD Only?

Initial Approach:

Originally planned to support dual authentication (Azure AD + Basic Auth with username/password) to provide flexibility for users without Microsoft accounts.

Technical Limitation Discovered:

Azure Static Web Apps' route-based access control (allowedRoles: ["authenticated"]) only recognizes authentication from built-in OAuth providers (Azure AD, GitHub, Twitter). Custom username/password authentication cannot integrate with this route protection mechanism, even when using Azure Functions to validate credentials and set session cookies.

Attempted Solutions:

  1. Basic Auth with Authorization header → Browser showed infinite popup loop
  2. JSON POST with custom session cookie → Cookie not recognized by Azure Static Web Apps route protection
  3. Azure Function custom authentication → Session doesn't persist across pages

Final Decision:

Azure AD-only authentication provides:

  • ✅ Enterprise-grade security with OAuth 2.0
  • ✅ Proper integration with Azure Static Web Apps route protection
  • ✅ No custom credential or session management complexity
  • ✅ Guest user invitation support for external collaborators
  • ✅ Zero maintenance overhead for user management

Out of Scope

For v1.0 (this feature):

  • ❌ Role-based access control (admin, editor, viewer roles)
  • ❌ User profile management or self-service password reset
  • ❌ Social login (GitHub, Google, Twitter)
  • ❌ Multi-factor authentication (MFA) - relies on Azure AD tenant MFA settings
  • ❌ Audit logs or access tracking
  • ❌ API authentication (for Phase 2 backend features)
  • ❌ Custom session duration or remember-me functionality
  • ❌ Basic Auth or username/password authentication (not supported by Azure Static Web Apps route protection)
  • ❌ Protecting engineering documentation (explicitly kept public for portfolio/teaching)

Explicitly Deferred:

  • Database-backed user storage (not needed - Azure AD handles user management)
  • Admin UI for user management (Azure Portal provides this functionality)

Risks & Mitigations

Risk Impact Mitigation
Azure AD tenant access Low Document guest user invitation process; owner can invite external users as needed
Accidental lockout Medium Always test in incognito before final deployment; maintain rollback plan; engineering docs remain public as fallback
OAuth redirect misconfiguration Medium Carefully document redirect URI setup; test thoroughly before production deployment
Session expiration during use Low 8-hour session is sufficient for typical usage patterns; users can re-authenticate easily

References

Internal Documents

External Resources

  • Tasks: /project/tasks/2026-02-10-01-authentication-tasks.md
  • PM Workflow: /mkdocs-docs/engineering/pm-workflows/2026-02-10-01-authentication.md
  • Dev Workflow: /mkdocs-docs/engineering/dev-workflows/2026-02-10-1528-authentication-implementation.md

Next Steps

  1. ~~Review and approve this specification~~
  2. ~~Create task breakdown in /project/tasks/~~
  3. ~~Begin Phase 1: Azure AD app registration~~
  4. ~~Implement staticwebapp.config.json configuration~~
  5. ~~Deploy and test Azure AD authentication~~
  6. ~~Create PM and Dev Workflow summaries~~
  7. Update CLAUDE.md with authentication notes
  8. Invite guest users as needed for external collaborators

Lessons Learned

What Worked Well:

  • Azure Static Web Apps built-in authentication is powerful and requires minimal configuration
  • OAuth flow with Azure AD provides enterprise-grade security without custom implementation
  • Route-based access control is simple and effective
  • Guest user invitation system works well for external collaborators

Technical Insights:

  • Azure Static Web Apps only supports OAuth providers (Azure AD, GitHub, Twitter) for route protection
  • Custom username/password authentication cannot integrate with allowedRoles in staticwebapp.config.json
  • Session cookies from Azure Functions are not recognized by Azure Static Web Apps authentication framework
  • Attempting to build custom Basic Auth results in session management complexity without proper route enforcement

Process Improvements:

  • Always validate authentication approach against platform limitations before implementation
  • Test authentication integration early to discover compatibility issues
  • Consider OAuth-first for modern web applications on managed platforms

Change History

Version 2.0 - 2026-02-10

  • Changed to Azure AD-only authentication (removed Basic Auth)
  • Reason: Azure Static Web Apps route protection only supports built-in OAuth providers
  • Basic Auth implementation removed after discovering technical incompatibility
  • Simplified authentication flow with direct redirect to Microsoft login
  • Removed custom login page and Azure Functions
  • Updated all documentation to reflect final implementation

Version 1.0 - 2026-02-10

  • Initial spec creation
  • Defined dual authentication approach (Azure AD + Basic Auth)
  • Scoped to /prompts/* protection only (engineering docs remain public)
  • Configuration file storage for Basic Auth users (1-5 users)
  • Both authentication phases to be implemented together
  • Established success criteria and test scenarios

Document Metadata: - Spec Version: 1.0 - Created: 2026-02-10 - Author: Kang (with AI assistance from Claude Sonnet 4.5) - Last Updated: 2026-02-10 - Related Specs: 2026-02-09-01 (Engineering History Tracking) - Status: Living document