Add comprehensive Entra ID setup guide

ENTRA_SETUP.md

@@ -0,0 +1,160 @@
+# Microsoft Entra ID Setup Guide
+
+This guide provides step-by-step instructions for setting up Microsoft Entra ID (formerly Azure Active Directory) authentication for the PDF Renamer web application.
+
+## Prerequisites
+
+- An Azure subscription
+- Administrative access to Azure Active Directory
+- The PDF Renamer application code
+
+## Step 1: Access Azure Portal
+
+1. Open your web browser and navigate to [Azure Portal](https://portal.azure.com)
+2. Sign in with your Azure account credentials
+
+## Step 2: Navigate to App Registrations
+
+1. In the Azure Portal, search for "Azure Active Directory" in the search bar
+2. Click on "Azure Active Directory" from the results
+3. In the left sidebar, click on "App registrations"
+4. Click on "New registration" at the top
+
+## Step 3: Register the Application
+
+1. **Name**: Enter a descriptive name for your app, e.g., "PDF Renamer Web App"
+2. **Supported account types**: Select "Accounts in this organizational directory only (Single tenant)"
+3. **Redirect URI**:
+   - Platform: Web
+   - URI: `http://localhost:3000/auth` (for local development)
+   - Note: For production, use your actual domain, e.g., `https://yourdomain.com/auth`
+
+4. Click "Register"
+
+## Step 4: Record Application Details
+
+After registration, you'll be taken to the app's overview page. Record these values:
+
+1. **Application (client) ID**: Copy this value - this is your `CLIENT_ID`
+2. **Directory (tenant) ID**: Copy this value - this is your `TENANT_ID`
+
+## Step 5: Create Client Secret
+
+1. In the left sidebar of your app registration, click on "Certificates & secrets"
+2. Click on "New client secret"
+3. **Description**: Enter a description, e.g., "PDF Renamer Secret"
+4. **Expires**: Choose an appropriate expiration (recommend 1 year for development)
+5. Click "Add"
+
+6. **Important**: Immediately copy the **Value** (not the Secret ID) - this is your `CLIENT_SECRET`
+   - **Warning**: This value will only be shown once. Store it securely!
+
+## Step 6: Configure Authentication Settings
+
+1. In the left sidebar, click on "Authentication"
+2. Under "Web" section, ensure your redirect URI is listed: `http://localhost:3000/auth`
+3. Under "Implicit grant and hybrid flows":
+   - Check "Access tokens (used for implicit flows)"
+   - Check "ID tokens (used for implicit and hybrid flows)"
+4. Click "Save" at the top
+
+## Step 7: Set Environment Variables
+
+Create a `.env` file in your project root directory with the following content:
+
+```env
+TENANT_ID=your-tenant-id-here
+CLIENT_ID=your-client-id-here
+CLIENT_SECRET=your-client-secret-here
+SECRET_KEY=your-random-secret-key-here
+```
+
+**Security Notes**:
+- Never commit the `.env` file to version control
+- Use a strong, random string for `SECRET_KEY` (at least 32 characters)
+- For production, use Azure Key Vault or similar secure storage
+
+## Step 8: Alternative - Set Environment Variables in Shell
+
+If you prefer not to use a `.env` file, you can set environment variables in your shell:
+
+### Windows (PowerShell):
+```powershell
+$env:TENANT_ID = "your-tenant-id-here"
+$env:CLIENT_ID = "your-client-id-here"
+$env:CLIENT_SECRET = "your-client-secret-here"
+$env:SECRET_KEY = "your-random-secret-key-here"
+```
+
+### Windows (Command Prompt):
+```cmd
+set TENANT_ID=your-tenant-id-here
+set CLIENT_ID=your-client-id-here
+set CLIENT_SECRET=your-client-secret-here
+set SECRET_KEY=your-random-secret-key-here
+```
+
+### Linux/macOS:
+```bash
+export TENANT_ID=your-tenant-id-here
+export CLIENT_ID=your-client-id-here
+export CLIENT_SECRET=your-client-secret-here
+export SECRET_KEY=your-random-secret-key-here
+```
+
+## Step 9: Test the Configuration
+
+1. Ensure your virtual environment is activated
+2. Run the application:
+   ```bash
+   python pdf_renamer.py
+   ```
+3. Open your browser to `http://127.0.0.1:3000/`
+4. You should be redirected to Microsoft login
+5. After successful authentication, you'll access the PDF Renamer app
+
+## Troubleshooting
+
+### Common Issues:
+
+1. **"Invalid client" error**:
+   - Verify `CLIENT_ID` and `CLIENT_SECRET` are correct
+   - Ensure the client secret hasn't expired
+
+2. **"Invalid redirect URI" error**:
+   - Check that the redirect URI in Azure matches exactly: `http://localhost:3000/auth`
+   - For production, update to your domain
+
+3. **"Tenant not found" error**:
+   - Verify `TENANT_ID` is correct
+   - Ensure you're using the Directory (tenant) ID, not the Application ID
+
+4. **Permission denied**:
+   - Ensure your Azure account has permissions to register applications
+   - Check that the app registration is in the correct tenant
+
+### Additional Resources:
+
+- [Azure AD App Registration Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
+- [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow)
+- [Microsoft Identity Platform Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
+
+## Production Deployment Notes
+
+When deploying to production:
+
+1. Update redirect URIs to your production domain
+2. Use HTTPS for all URLs
+3. Store secrets securely (Azure Key Vault recommended)
+4. Consider using managed identity for Azure resources
+5. Implement proper logging and monitoring
+6. Set appropriate token lifetimes and refresh policies
+
+## Support
+
+If you encounter issues with the Entra ID setup, please check:
+1. Azure Portal configuration
+2. Environment variable values
+3. Application logs for error messages
+4. Network connectivity to login.microsoftonline.com</content>
+<parameter name="filePath">c:\Users\NateEmmert\pdf-rename-sort\pdf-rename-sort\ENTRA_SETUP.md

README.md

@@ -20,23 +20,12 @@ A Python web application built with Flask that automatically renames PDF files b
 
 ## Microsoft Entra ID Setup
 
-1. **Register an application** in Azure Portal:
-   - Go to Azure Active Directory > App registrations > New registration
-   - Name: PDF Renamer App
-   - Supported account types: Accounts in this organizational directory only
-   - Redirect URI: `http://localhost:3000/auth` (for local development)
+**Detailed setup instructions**: See [ENTRA_SETUP.md](ENTRA_SETUP.md) for comprehensive step-by-step guide to configure Microsoft Entra ID authentication.
 
-2. **Configure authentication**:
-   - In the app registration, go to Authentication
-   - Add redirect URI if not set: `http://localhost:3000/auth`
-   - Enable "Access tokens" and "ID tokens" if needed
-
-3. **Get credentials**:
-   - Client ID: From Overview page
-   - Tenant ID: From Overview page
-   - Client Secret: Go to Certificates & secrets > New client secret
-
-4. **Set environment variables**:
+### Quick Setup:
+1. Register application in Azure Portal
+2. Get Tenant ID, Client ID, and Client Secret
+3. Set environment variables:
    ```bash
    export TENANT_ID="your-tenant-id"
    export CLIENT_ID="your-client-id"