diff --git a/ENTRA_SETUP.md b/ENTRA_SETUP.md new file mode 100644 index 0000000..dc26ea3 --- /dev/null +++ b/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 +c:\Users\NateEmmert\pdf-rename-sort\pdf-rename-sort\ENTRA_SETUP.md \ No newline at end of file diff --git a/README.md b/README.md index 06fe0dd..3192280 100644 --- a/README.md +++ b/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"