btg-sandbox-markdown-formatter/README.md

Markdown Formatter

A secure web-based Markdown to HTML converter application with Microsoft Azure AD authentication. The application provides real-time Markdown processing with clipboard functionality, all protected behind enterprise-grade authentication.

Features

• Real-time Markdown Processing: Convert Markdown to HTML instantly as you type
• Secure Authentication: Microsoft Azure AD/Entra ID integration with PKCE flow
• Clipboard Integration: Copy HTML or plain text output with modern Clipboard API
• Server-side Security: JWT validation on all requests with httpOnly cookies
• Responsive Design: Clean, modern interface with Montserrat font
• Enterprise Ready: Stateless authentication suitable for production deployments

Architecture

Security-First Design

• Authentication Gateway: All pages require valid Azure AD authentication
• JWT Validation: Server-side token verification using Azure AD public keys
• httpOnly Cookies: Secure token storage preventing XSS attacks
• PKCE Flow: Authorization Code with Proof Key for Code Exchange

Technology Stack

• Frontend: Vanilla JavaScript, HTML5, CSS3
• Backend: PHP 7.4+ with Composer dependency management
• Authentication: MSAL.js + Azure AD
• Markdown Processing: marked.js library
• JWT Handling: Firebase JWT library

Prerequisites

• PHP 7.4 or higher with OpenSSL extension
• Composer (PHP dependency manager)
• Web server (Apache, Nginx, or PHP built-in server)
• Microsoft Azure AD tenant with app registration
• Modern web browser with JavaScript enabled

Installation

1. Clone the Repository

git clone <repository-url>
cd markdown-formatter

2. Install PHP Dependencies

composer install

This will install the Firebase JWT library required for token validation.

3. Azure AD App Registration

1. Go to Azure Portal

2. Navigate to Azure Active Directory → App registrations

3. Click New registration

4. Configure the application:

   • Name: Markdown Formatter
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI:
     • Platform: Single-page application (SPA)
     • URI: http://localhost:8000 (for local development)

5. After registration, note the Application (client) ID and Directory (tenant) ID

6. Configure API permissions:

   • Add Microsoft Graph → User.Read (delegated)
   • Grant admin consent if required

4. Update Configuration

The application is pre-configured with these Azure AD settings:

• Client ID: 9079054c-9620-4757-a256-23413042f1ef
• Tenant ID: e519c2e6-bc6d-4fdf-8d9c-923c2f002385

If you need to use different Azure AD settings, update the configuration in:

• js/script.js (MSAL configuration)
• JWTValidator.php (tenant validation)

5. Start Local Development Server

php -S localhost:8000

6. Access the Application

Open your browser and navigate to:

http://localhost:8000

You will be redirected to Microsoft's login page for authentication.

File Structure

markdown-formatter/
├── index.php                 # Main application page (auth required)
├── auth.php                  # Authentication endpoint
├── process.php               # Server-side processing (auth required)
├── config.php                # PHP configuration
├── composer.json             # PHP dependencies
├── AuthMiddleware.php        # Authentication middleware
├── JWTValidator.php          # JWT validation logic
├── js/
│   └── script.js            # Client-side application logic
├── css/
│   └── style.css            # Application styling
└── vendor/                  # Composer dependencies

Authentication Flow

1. Initial Access: User visits any page
2. Authentication Check: AuthMiddleware validates httpOnly cookie
3. Login Redirect: Unauthenticated users see login page
4. Azure AD Login: MSAL.js initiates popup-based PKCE flow
5. Token Exchange: Valid Azure AD tokens stored as httpOnly cookies
6. Page Reload: User redirected to requested page
7. JWT Validation: Every request validates token against Azure AD

Development

Local Development Setup

1. Ensure PHP OpenSSL extension is enabled:

php -m | grep openssl

2. Start the development server:

php -S localhost:8000

3. The application will be available at http://localhost:8000

Dependency Management

Update PHP dependencies:

composer update

Testing Authentication

• Test with different browsers to verify cookie behavior
• Use browser developer tools to inspect authentication flow
• Check Network tab for JWT validation requests

Production Deployment

Server Requirements

• PHP 7.4+ with OpenSSL extension
• Web server with HTTPS support
• Composer for dependency management

Configuration Updates

1. Azure AD Redirect URIs: Add your production domain
2. HTTPS: Ensure all authentication flows use HTTPS
3. Error Reporting: Disable in production (modify config.php)
4. Cookie Settings: Verify httpOnly cookies work with your domain

Security Considerations

• Always use HTTPS in production
• Configure proper CORS policies if needed
• Monitor authentication logs for suspicious activity
• Regularly update dependencies for security patches

Usage

1. Login: Click "Login with Microsoft" button
2. Write Markdown: Type or paste Markdown in the left panel
3. View HTML: Real-time conversion appears in the right panel
4. Copy Output: Use clipboard buttons to copy HTML or plain text
5. Logout: Click logout to clear authentication

Troubleshooting

Common Issues

Authentication fails with popup blocked

• Allow popups for your domain in browser settings
• Try using incognito/private browsing mode

JWT validation errors

• Verify system clock is synchronized
• Check that OpenSSL extension is enabled
• Ensure network connectivity to Azure AD

Clipboard functionality not working

• Modern browsers require HTTPS for Clipboard API
• Fallback uses document.execCommand for HTTP

Dependencies missing

• Run composer install to install required packages
• Verify PHP version meets minimum requirements

Debug Mode

Enable detailed error reporting by modifying config.php:

error_reporting(E_ALL);
ini_set('display_errors', 1);

License

[Add your license information here]

Support

[Add your support contact information here]