nano-pro/AUTH_README.md

MSAL Authentication Setup Guide

Overview

Nano Banana Pro now includes Microsoft Authentication Library (MSAL) / Azure AD Single Sign-On (SSO) authentication. The authentication can be toggled on/off via environment variable for seamless testing and deployment.

---

Quick Start

Local Development (No Authentication)

# 1. Ensure .env file exists with:
SSO_ENABLED=false

# 2. Run the app normally in MAMP
# All users get mock "Local Developer" credentials
# No login required

Production (with SSO)

# 1. Update .env file:
SSO_ENABLED=true
SSO_TENANT_ID=your-azure-tenant-id
SSO_CLIENT_ID=your-azure-application-id

# 2. Deploy to server
# 3. Users must login with Microsoft account

---

Installation Steps

1. Install Dependencies

cd /Users/daveporter/Desktop/CODING-2024/NANO-RESEARCH
composer install

This installs the Firebase JWT library required for token validation.

2. Configure Environment

# Copy example file
cp .env.example .env

# Edit .env and set:
SSO_ENABLED=false  # Start with authentication disabled

3. Azure AD Setup (When Enabling SSO)

Create Azure AD App Registration:

1. Go to Azure Portal
2. Navigate to: Azure Active Directory → App registrations → New registration
3. Set name: "Nano Banana Pro"
4. Set redirect URI: https://your-server-url.com/path/to/app/index.php
5. Click Register

Get Credentials:

1. Copy Application (client) ID → This is your SSO_CLIENT_ID
2. Copy Directory (tenant) ID → This is your SSO_TENANT_ID
3. Go to Authentication → Enable ID tokens checkbox
4. Go to API permissions → Add: openid, profile, email

Update .env:

SSO_ENABLED=true
SSO_TENANT_ID=e519c2e6-bc6d-4fdf-8d9c-923c2f002385
SSO_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef

---

File Structure

New Files Created:

/NANO-RESEARCH/
├── composer.json              # PHP dependencies (Firebase JWT)
├── .env                       # Environment config (gitignored)
├── .env.example               # Template for environment variables
├── env_loader.php             # Loads .env file
├── JWTValidator.php           # JWT token validation logic
├── AuthMiddleware.php         # Auth orchestrator + login UI
├── auth.php                   # Auth API endpoint
├── auth-test.php              # Debugging page
├── AUTH_README.md             # This file
└── vendor/                    # Composer dependencies (gitignored)

Modified Files:

config.php                     # Added SSO constants
index.php                      # Added auth check, logout button
api.php                        # Added auth check
enhance_prompt.php             # Added auth check
.gitignore                     # Added .env and vendor/

---

How It Works

When SSO_ENABLED=false (Testing Mode)

1. User visits app
2. AuthMiddleware returns mock "Local Developer" user
3. No login page shown
4. All features work normally
5. Perfect for local testing

When SSO_ENABLED=true (Production Mode)

1. User visits app
2. AuthMiddleware checks for auth_token cookie
3. If no token → Show MSAL login page
4. User clicks "Sign In with Microsoft"
5. MSAL popup opens for Azure AD login
6. User authenticates
7. Token sent to auth.php for validation
8. JWT validated against Azure AD public keys
9. Token stored in httpOnly cookie (24 hours)
10. User redirected to app
11. Logout button visible in header

---

Testing

Test Authentication Status

Visit: http://your-server/auth-test.php

Shows:

• SSO configuration (enabled/disabled)
• Tenant ID and Client ID
• Current authentication status
• User information
• Cookie presence

Test Locally (SSO Disabled)

# 1. Set SSO_ENABLED=false in .env
# 2. Open app in MAMP
# 3. Should see "Welcome, Local Developer" (if SSO was previously enabled)
# 4. App functions normally
# 5. No login/logout buttons

Test on Server (SSO Enabled)

# NOTE: Cannot test locally - Azure AD requires exact redirect URI match

# 1. Deploy to production server
# 2. Set SSO_ENABLED=true in .env on server
# 3. Add Azure AD credentials to .env
# 4. Visit app URL
# 5. Should see login page
# 6. Click "Sign In with Microsoft"
# 7. Complete Microsoft login
# 8. Should redirect to app
# 9. Should see "Welcome, [Your Name]" and logout button

---

Security Features

✅ httpOnly Cookies - Prevents XSS attacks (JavaScript can't access token) ✅ SameSite=Lax - Prevents CSRF attacks ✅ Secure Flag - Cookie only sent over HTTPS in production ✅ JWT Validation - Cryptographic verification of tokens ✅ Expiration Check - Validates exp claim ✅ Not-Before Check - Validates nbf claim ✅ Audience Validation - Ensures token is for our app ✅ Issuer Validation - Ensures token from Azure AD ✅ JWKS Verification - Uses Azure AD public keys ✅ 24-Hour Expiration - Tokens expire after 1 day

---

Troubleshooting

Login Page Shows But Can't Login

• Check Azure AD app registration has correct redirect URI
• Ensure SSO_TENANT_ID and SSO_CLIENT_ID are correct
• Check browser console for MSAL errors
• Visit auth-test.php to verify configuration

"Authentication Required" Error

• Check auth_token cookie exists (browser dev tools)
• Token may have expired (24-hour limit)
• Try logging out and back in
• Check auth-test.php for token status

SSO Not Disabling

• Verify .env has SSO_ENABLED=false (not "false" in quotes)
• Clear browser cookies
• Restart PHP server/MAMP
• Check auth-test.php shows "SSO Enabled: NO"

Token Validation Failing

• Check server can reach Azure AD endpoints
• Verify tenant ID and client ID match Azure AD
• Check token hasn't expired
• Review error_log for JWT validation details

---

API Endpoints

Login

POST /auth.php
Content-Type: application/json

{
    "action": "login",
    "idToken": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

Logout

POST /auth.php
Content-Type: application/json

{
    "action": "logout"
}

Status Check

POST /auth.php
Content-Type: application/json

{
    "action": "status"
}

---

Maintenance

Rotating Credentials

1. Update Azure AD app registration
2. Update .env with new credentials
3. No code changes needed
4. Existing sessions remain valid until cookie expires

Disabling SSO Temporarily

# In .env:
SSO_ENABLED=false

# Immediately disables SSO for all users
# No restart needed
# Users get mock "Local Developer" access

Monitoring

• Check error_log for authentication failures
• Monitor Azure AD sign-in logs
• Track failed login attempts
• Review token validation errors

---

Production Checklist

Before enabling SSO in production:

• Composer dependencies installed (vendor/ directory exists)
• .env file configured with Azure AD credentials
• Azure AD app registration created
• Redirect URI matches production URL exactly
• ID tokens enabled in Azure AD app
• API permissions added (openid, profile, email)
• HTTPS enabled on production server
• auth-test.php shows correct configuration
• Test login/logout flow works
• Error logging enabled

---

Support

For issues with:

• MSAL errors: Check MSAL.js documentation
• Azure AD setup: Check Azure AD app registration guide
• JWT validation: Check Firebase JWT library logs in error_log
• Configuration: Run auth-test.php to see current setup

---

Important Notes

• Cannot test MSAL locally - Azure AD requires exact URL match
• Testing happens on server after deployment
• SSO toggle allows testing without auth before enabling
• httpOnly cookies mean token not accessible via JavaScript
• 24-hour token expiration - users must re-login daily
• Mock user (dev@localhost) used when SSO disabled