nextgenpdf/ENTRA_SETUP.md

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

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):

$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):

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:

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:

   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
• OAuth 2.0 Authorization Code Flow
• Microsoft Identity Platform Documentation

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