sandbox-reports/SSO-SETUP.md

SSO Setup Guide - Microsoft Azure AD (MSAL)

The VEO3 Report System uses Microsoft Azure AD for Single Sign-On authentication. This protects both the web dashboard and webhook caller pages.

Prerequisites

• Microsoft Azure AD tenant
• Permission to register applications in Azure AD
• PHP 7.4 or higher
• Composer (PHP package manager)

Setup Steps

1. Install PHP Dependencies

cd /path/to/veo3-report
composer install

This installs the firebase/php-jwt library required for token validation.

2. Register Application in Azure AD

1. Login to Azure Portal: https://portal.azure.com

2. Navigate to: Azure Active Directory → App registrations → New registration

3. Register the application:

   • Name: VEO3 Usage Report
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Web → https://your-domain.com/report.php (and add /webhook_caller.php)
   • Click Register

4. Note these values:

   • Application (client) ID: Copy this
   • Directory (tenant) ID: Copy this

5. Configure Authentication:

   • Go to Authentication in left menu
   • Under Implicit grant and hybrid flows:
     • ✅ Check ID tokens
     • ✅ Check Access tokens
   • Click Save

6. Configure API Permissions:

   • Go to API permissions in left menu
   • Should already have Microsoft Graph → User.Read (delegated)
   • This is sufficient for SSO

3. Configure Environment Variables

Edit your .env file:

# SSO Configuration
SSO_ENABLED=true
SSO_TENANT_ID=your-tenant-id-here
SSO_CLIENT_ID=your-client-id-here

For Local Development (disable SSO):

SSO_ENABLED=false

When SSO is disabled, you'll be logged in as "Local Developer" automatically.

4. Deploy to Server

If deploying with the automated script:

# Ensure .env is configured
nano .env

# Run deployment
sudo ./deploy.sh

The deployment script will:

• Copy SSO files
• Install Composer dependencies
• Set up the systemd service

5. Configure Web Server

Apache (.htaccess)

# Enable PHP
AddHandler application/x-httpd-php .php

# Security headers
Header always set X-Frame-Options "SAMEORIGIN"
Header always set X-Content-Type-Options "nosniff"
Header always set X-XSS-Protection "1; mode=block"

# Deny access to sensitive files
<FilesMatch "^\.">
    Require all denied
</FilesMatch>

<Files "composer.json">
    Require all denied
</Files>

<Files "composer.lock">
    Require all denied
</Files>

Nginx

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

# Deny access to sensitive files
location ~ /\. {
    deny all;
}

location ~ composer\.(json|lock)$ {
    deny all;
}

# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;

Testing SSO

1. Test Locally (SSO Disabled)

# In .env
SSO_ENABLED=false

# Start PHP server
php -S localhost:8000

# Visit http://localhost:8000/report.php
# Should show reports without login

2. Test with SSO Enabled

# In .env
SSO_ENABLED=true
SSO_TENANT_ID=your-tenant-id
SSO_CLIENT_ID=your-client-id

# Visit https://your-domain.com/report.php
# Should redirect to Microsoft login

How It Works

Authentication Flow

1. User visits protected page (report.php or webhook_caller.php)
2. AuthMiddleware checks for valid authentication cookie
3. If not authenticated:
   • Shows Microsoft login page
   • User authenticates with Azure AD
   • MSAL returns JWT token
   • Token sent to auth.php for validation
   • Valid token stored in secure cookie
   • Page reloads with authenticated session
4. If authenticated:
   • JWT token validated on each request
   • User information available in $user variable

Security Features

• ✅ JWT validation with Azure AD public keys
• ✅ HttpOnly cookies (not accessible to JavaScript)
• ✅ Token expiration checked (24-hour lifetime)
• ✅ Audience validation (ensures token is for this app)
• ✅ Issuer validation (ensures token from correct Azure tenant)
• ✅ SameSite cookie attribute (CSRF protection)
• ✅ Secure cookies over HTTPS in production

File Structure

veo3-report/
├── AuthMiddleware.php    # Main authentication class
├── JWTValidator.php      # JWT token validator
├── auth.php              # Authentication API endpoint
├── config.php            # SSO configuration
├── env_loader.php        # .env file loader
├── report.php            # Protected: requires auth
├── webhook_caller.php    # Protected: requires auth
└── composer.json         # PHP dependencies

Troubleshooting

"Could not retrieve public keys from Azure AD"

Cause: Network issue or invalid tenant ID Fix:

• Verify SSO_TENANT_ID in .env
• Check server can reach login.microsoftonline.com
• Check PHP error logs: tail -f /var/log/apache2/error.log

"Token signature is invalid"

Cause: Token from wrong tenant or client Fix:

• Verify SSO_CLIENT_ID matches Azure app registration
• Clear browser cookies and try again
• Ensure redirect URI matches exactly in Azure

"Invalid audience"

Cause: Token not intended for this application Fix:

• Verify SSO_CLIENT_ID in .env
• Check Azure app registration client ID

Login popup blocked

Cause: Browser blocking popups Fix:

• Allow popups for your domain
• Try different browser

Token expired

Cause: Token older than 24 hours Fix:

• Clear cookies and login again
• Automatic redirect to login should occur

Disabling SSO

To temporarily disable SSO (for maintenance or testing):

# In .env
SSO_ENABLED=false

# Restart web server/PHP-FPM
sudo systemctl restart apache2
# or
sudo systemctl restart nginx

When disabled:

• No login required
• Mock user "Local Developer" used
• Full access to all features

Adding More Protected Pages

To protect additional PHP pages:

<?php
// At the top of your PHP file
require_once __DIR__ . '/AuthMiddleware.php';
$auth = new AuthMiddleware();
$user = $auth->requireAuth();

// User is authenticated, $user contains:
// - name: Display name
// - preferred_username: Email address
?>

User Logout

Add a logout link:

<a href="javascript:void(0)" onclick="logout()">Logout</a>

<script>
function logout() {
    fetch('auth.php', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({action: 'logout'})
    })
    .then(() => {
        window.location.reload();
    });
}
</script>

Production Checklist

• [ ] Azure app registered with correct redirect URIs
• .env configured with correct tenant/client IDs
• SSO_ENABLED=true in .env
• Composer dependencies installed
• HTTPS enabled (required for production)
• Security headers configured in web server
• Error logs monitored for auth issues
• Test login/logout flow

Support

For SSO issues:

1. Check PHP error logs
2. Check browser console for JavaScript errors
3. Verify Azure app configuration
4. Test with SSO_ENABLED=false to isolate issue