# 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.

**Note**: Entra ID authentication is optional. The application also supports local admin login. Follow this guide only if you want to enable Microsoft Entra ID authentication.

## 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