Add troubleshooting documentation for Office 365 Management API Subscription flow authentication errors

docs/troubleshooting/GITHUB-ISSUE-COMMENT-template.md

@@ -0,0 +1,114 @@
+# GitHub Issue Comment - Office 365 Management API Subscription Flow Error
+
+**Copy and paste this comment to the GitHub issue**
+
+---
+
+Thank you for reporting this issue! I've analyzed the problem and created comprehensive documentation to help you resolve it.
+
+## 🔍 Issue Analysis
+
+The error `Action 'Get_Azure_Secret' failed. Error occurred while reading secret: Value cannot be null. Parameter name: input` indicates that the required environment variables for Office 365 Management API authentication are not properly configured in your CoE environment.
+
+## ⚡ Quick Fix (Start Here!)
+
+For the fastest resolution, please follow our **Quick Fix Guide**: 
+[QUICK-FIX-audit-logs-get-azure-secret-error.md](../docs/troubleshooting/QUICK-FIX-audit-logs-get-azure-secret-error.md)
+
+**TL;DR** - The flow needs these environment variables configured:
+1. ✅ `admin_auditlogsclientid` - Your Azure AD app's Application (Client) ID
+2. ✅ `admin_auditlogsclientsecret` - Your Azure AD app's client secret (simpler option)
+   OR `admin_auditlogsclientazuresecret` - Azure Key Vault secret reference (production option)
+3. ✅ `admin_TenantID` - Your Azure Tenant ID
+
+## 📚 Documentation Created
+
+I've created comprehensive troubleshooting documentation for this issue:
+
+### 1. **Quick Fix Checklist** ⚡ (2-3 minutes)
+**Location**: `docs/troubleshooting/QUICK-FIX-audit-logs-get-azure-secret-error.md`
+
+- Fast checklist format
+- Step-by-step fastest fix
+- Common mistakes highlighted
+
+### 2. **Detailed Troubleshooting Guide** 📖 (Complete reference)
+**Location**: `docs/troubleshooting/audit-logs-office365-management-api-subscription-flow-errors.md`
+
+Includes:
+- Root cause analysis
+- Understanding the flow architecture
+- Step-by-step Azure AD app setup
+- Environment variable configuration (both methods)
+- Cloud-specific configurations (Commercial, GCC, GCC High)
+- Common errors and solutions
+- Prerequisites checklist
+
+### 3. **Issue-Specific Analysis** 🎯
+**Location**: `docs/troubleshooting/ISSUE-ANALYSIS-office365-management-api-subscription.md`
+
+- Analysis specific to your reported issue
+- Immediate action steps
+- Expected behavior after fix
+- Follow-up checklist
+
+### 4. **Troubleshooting Index**
+**Location**: `docs/troubleshooting/README.md`
+
+- Central index of all troubleshooting guides
+
+## 🔧 What You Need to Do
+
+### Step 1: Set Up Azure AD App Registration (if not done)
+
+1. Go to Azure Portal > Azure Active Directory > App registrations
+2. Create a new app registration for CoE Audit Logs
+3. Add API permissions: `ActivityFeed.Read`, `ActivityFeed.ReadDlp`, `ServiceHealth.Read` (Office 365 Management APIs)
+4. Grant admin consent
+5. Create a client secret and copy it immediately
+6. Note your Application (Client) ID and Tenant ID
+
+### Step 2: Configure Environment Variables
+
+1. Navigate to Power Platform Admin Center > Your CoE Environment > Solutions
+2. Open "Center of Excellence - Core Components" solution
+3. Go to Environment variables
+4. Set the required values (see Quick Fix guide above)
+
+### Step 3: Test the Flow
+
+1. Open the flow in Power Automate
+2. Test with operation: "list"
+3. Verify success
+
+## 📋 Prerequisites
+
+Before the flow can work, ensure:
+- ✅ Unified Audit Log is enabled in Microsoft Purview (takes up to 24 hours after enabling)
+- ✅ You have Office 365/Microsoft 365 E3 or E5 licenses
+- ✅ You have appropriate admin permissions
+
+## 🆘 Still Having Issues?
+
+If you continue to experience problems after following the documentation:
+
+1. Check that all environment variables have values (not empty)
+2. Verify your client secret hasn't expired
+3. Confirm admin consent was granted for API permissions
+4. Ensure Unified Audit Log is enabled and has been active for 24+ hours
+
+**Please provide**:
+- Screenshot of your environment variables (with secrets redacted)
+- Flow run history screenshot showing the error
+- Your cloud environment type (Commercial, GCC, etc.)
+
+## 🔗 Additional Resources
+
+- [CoE Starter Kit Setup Guide](https://learn.microsoft.com/power-platform/guidance/coe/setup)
+- [Set Up Audit Log Components](https://learn.microsoft.com/power-platform/guidance/coe/setup-auditlog)
+- [Office 365 Management API Reference](https://learn.microsoft.com/office/office-365-management-api/office-365-management-activity-api-reference)
+
+---
+
+**This issue has been addressed with comprehensive troubleshooting documentation. Please follow the guides above and let us know if you have any questions or need further assistance!**
+

docs/troubleshooting/ISSUE-ANALYSIS-office365-management-api-subscription.md

@@ -0,0 +1,188 @@
+# Issue Response: Admin | Audit Logs | Office 365 Management API Subscription Flow Fails
+
+## Issue Summary
+
+**Reported Issue**: The Admin | Audit Logs | Office 365 Management API Subscription Flow fails on Action 'Get_Azure_Secret' with error: "Error occurred while reading secret: Value cannot be null. Parameter name: input"
+
+**Solution Version**: 4.50.6
+**Component**: Core - Audit Logs
+**Environment**: CoE - Governance environment
+
+## Analysis
+
+### Root Cause
+The flow is failing because the required environment variable for Office 365 Management API authentication is not properly configured. The flow expects one of these environment variables:
+- `admin_auditlogsclientazuresecret` (Azure Key Vault secret reference), or
+- `admin_auditlogsclientsecret` (text-based client secret)
+
+When the `Get_Azure_Secret` action receives a null or empty input, it throws this error.
+
+### Flow Architecture
+The flow uses a two-tier authentication approach:
+1. **Primary**: Attempts to retrieve the secret from Azure Key Vault using `admin_auditlogsclientazuresecret`
+2. **Fallback**: If Azure Key Vault fails, it uses the text-based secret from `admin_auditlogsclientsecret`
+
+The error occurs before the fallback mechanism can engage, indicating the primary environment variable is missing or null.
+
+## Troubleshooting Steps
+
+### Immediate Action Required
+
+1. **Verify Environment Variables Exist**
+   - Navigate to: Power Platform Admin Center > Your CoE Environment > Solutions
+   - Open: "Center of Excellence - Core Components" solution
+   - Go to: Environment variables
+   - Check for these variables:
+     - `admin_auditlogsclientid` ✅
+     - `admin_auditlogsclientazuresecret` OR `admin_auditlogsclientsecret` ✅
+     - `admin_TenantID` ✅
+     - `admin_AuditLogsAudience` ✅
+     - `admin_AuditLogsAuthority` ✅
+
+2. **Verify Values are Not Empty**
+   - Click each environment variable
+   - Confirm "Current Value" field contains a value
+   - If empty, proceed to configuration steps below
+
+### Configuration Steps
+
+#### Prerequisites
+Before configuring the flow, ensure you have:
+
+1. **Azure AD App Registration** set up:
+   - Go to: Azure Portal > Azure Active Directory > App registrations
+   - If no app exists for CoE Audit Logs, create one:
+     - Click "New registration"
+     - Name: "CoE Audit Logs API Access"
+     - Supported account types: Single tenant
+     - Click "Register"
+
+2. **API Permissions** configured:
+   - In app registration, go to "API permissions"
+   - Add "Office 365 Management APIs" permissions:
+     - `ActivityFeed.Read` (Application)
+     - `ActivityFeed.ReadDlp` (Application)
+     - `ServiceHealth.Read` (Application)
+   - Click "Grant admin consent"
+
+3. **Client Secret** created:
+   - In app registration, go to "Certificates & secrets"
+   - Click "New client secret"
+   - Add description and set expiration
+   - **IMPORTANT**: Copy the secret value immediately
+
+4. **Application Details** noted:
+   - From app registration Overview, copy:
+     - Application (client) ID
+     - Directory (tenant) ID
+
+#### Configure Environment Variables (Simple Method)
+
+For quickest resolution, use text-based secret:
+
+1. In Power Platform, open environment variables in the Core Components solution
+2. Set the following values:
+   - `admin_auditlogsclientid` = Your Application (Client) ID
+   - `admin_auditlogsclientsecret` = Your Client Secret value
+   - `admin_TenantID` = Your Tenant ID
+   - `admin_AuditLogsAudience` = `https://manage.office.com` (for Commercial cloud)
+   - `admin_AuditLogsAuthority` = `https://login.windows.net` (for Commercial cloud)
+
+**Note**: If using GCC or other clouds, adjust the audience and authority URLs accordingly.
+
+#### Configure Environment Variables (Azure Key Vault Method - Recommended)
+
+For production environments:
+
+1. Create/use Azure Key Vault and add your client secret
+2. Configure environment variables:
+   - `admin_auditlogsclientid` = Your Application (Client) ID
+   - `admin_auditlogsclientazuresecret` = (Type: Secret, linked to Key Vault)
+   - `admin_TenantID` = Your Tenant ID
+   - Set audience and authority URLs as above
+
+### Testing the Flow
+
+After configuration:
+
+1. Open the flow in Power Automate
+2. Click "Test" > "Manually"
+3. Enter "list" as the operation parameter
+4. Run the flow
+5. Check results:
+   - **Success**: Flow shows "Succeeded" status
+   - **Still failing**: Check flow run history for specific error details
+
+## Quick Reference Documentation
+
+We've created comprehensive troubleshooting documentation for this issue:
+
+### 1. Quick Fix Guide (⚡ Start Here)
+**File**: `docs/troubleshooting/QUICK-FIX-audit-logs-get-azure-secret-error.md`
+- Checklist format
+- Fastest path to resolution
+- Common mistakes to avoid
+
+### 2. Detailed Troubleshooting Guide
+**File**: `docs/troubleshooting/audit-logs-office365-management-api-subscription-flow-errors.md`
+- Comprehensive step-by-step instructions
+- Understanding flow logic
+- All configuration scenarios
+- Common errors and solutions
+- Cloud-specific configurations
+
+### 3. Issue Response Template
+**File**: `docs/troubleshooting/ISSUE-RESPONSE-TEMPLATE-audit-logs-get-azure-secret.md`
+- Template for responding to similar issues
+- Can be used by maintainers
+
+## Additional Prerequisites
+
+Before the flow can work, ensure:
+
+1. **Unified Audit Log Enabled**:
+   - Go to: Microsoft Purview compliance portal > Audit
+   - Turn on audit log search
+   - Allow 24 hours for activation
+
+2. **Appropriate Licenses**:
+   - Office 365 E3/E5 or Microsoft 365 E3/E5
+   - Required for audit logging capabilities
+
+3. **Required Permissions**:
+   - Azure AD: Application Administrator or Global Administrator
+   - Power Platform: System Administrator on CoE environment
+   - Office 365: Global Administrator (to enable audit logging)
+
+## Expected Behavior After Fix
+
+Once properly configured, the flow should:
+1. Authenticate using the configured credentials
+2. Successfully connect to Office 365 Management API
+3. Perform the requested operation (list/start/stop)
+4. Return a success status with operation results
+
+## Related Links
+
+- [CoE Starter Kit Setup Guide](https://learn.microsoft.com/power-platform/guidance/coe/setup)
+- [Set Up Audit Log Components](https://learn.microsoft.com/power-platform/guidance/coe/setup-auditlog)
+- [Office 365 Management Activity API](https://learn.microsoft.com/office/office-365-management-api/office-365-management-activity-api-reference)
+- [Enable Unified Audit Logging](https://learn.microsoft.com/microsoft-365/compliance/audit-log-enable-disable)
+
+## Follow-up
+
+After implementing the fix, please:
+1. Confirm the flow runs successfully
+2. Test all operations: list, start, stop
+3. Verify audit log data collection is working
+4. Update this issue with your results
+
+If issues persist after following these steps, please provide:
+- Screenshot of environment variables (with secrets redacted)
+- Flow run history screenshot
+- Specific error messages from the failed run
+- Your cloud environment type (Commercial, GCC, etc.)
+
+---
+
+**Note**: This issue has been addressed with comprehensive documentation to help current and future users resolve similar configuration problems.

docs/troubleshooting/ISSUE-RESPONSE-TEMPLATE-audit-logs-get-azure-secret.md

@@ -0,0 +1,90 @@
+# Issue Response Template: Office 365 Management API Subscription Flow - Get_Azure_Secret Error
+
+Use this template when responding to issues related to the Office 365 Management API Subscription flow failing with "Get_Azure_Secret" errors.
+
+---
+
+## Response Template
+
+Thank you for reporting this issue. The error you're experiencing with the **Admin | Audit Logs | Office 365 Management API Subscription** flow is a common configuration issue related to missing or empty environment variables.
+
+### Summary
+
+The error `Action 'Get_Azure_Secret' failed. Error occurred while reading secret: Value cannot be null. Parameter name: input` occurs when the flow attempts to retrieve the Azure Key Vault secret for Office 365 Management API authentication but the required environment variable is not configured.
+
+### Root Cause
+
+The flow expects one of these environment variables to be configured:
+- `admin_auditlogsclientazuresecret` (Azure Key Vault-based secret - recommended)
+- `admin_auditlogsclientsecret` (text-based secret - simpler setup)
+
+When neither is properly configured, the flow fails at the `Get_Azure_Secret` action.
+
+### Quick Resolution
+
+For a fast resolution, please follow our **[Quick Fix Guide](../docs/troubleshooting/QUICK-FIX-audit-logs-get-azure-secret-error.md)** which provides a checklist and the fastest path to get your flow working.
+
+**TL;DR**:
+1. Verify environment variables exist and have values (Solutions > Environment variables)
+2. Set up an Azure AD app registration with Office 365 Management API permissions
+3. Configure `admin_auditlogsclientid` with your Application (Client) ID
+4. Configure `admin_auditlogsclientsecret` with your client secret value
+5. Configure `admin_TenantID` with your Azure Tenant ID
+6. Rerun the flow
+
+### Detailed Troubleshooting
+
+For comprehensive troubleshooting steps, including:
+- Understanding the flow logic and fallback mechanisms
+- Azure AD app registration setup
+- Azure Key Vault configuration
+- Cloud-specific endpoint configurations
+- Common errors and their solutions
+
+Please see our **[Detailed Troubleshooting Guide](../docs/troubleshooting/audit-logs-office365-management-api-subscription-flow-errors.md)**.
+
+### Prerequisites
+
+Before using this flow, ensure:
+1. ✅ Unified Audit Log is enabled in Microsoft Purview
+2. ✅ You have appropriate licenses (Office 365/Microsoft 365 E3 or E5)
+3. ✅ You have required admin permissions (Azure AD Application Administrator, Power Platform System Administrator)
+
+### Related Issues
+
+This issue is similar to:
+- Missing environment variable configurations during initial setup
+- Azure AD app registration not properly configured
+- Client secrets that have expired
+
+### Next Steps
+
+After following the troubleshooting guides:
+1. Test the flow with the `list` operation to verify the configuration
+2. If successful, you can proceed with `start` or `stop` operations
+3. If you continue to experience issues, please provide:
+   - Screenshot of your environment variables (with sensitive values redacted)
+   - Flow run history screenshot showing the specific error
+   - Your CoE Starter Kit version
+   - Your cloud environment type (Commercial, GCC, GCC High, etc.)
+
+### Additional Resources
+
+- [CoE Starter Kit Setup Guide](https://learn.microsoft.com/power-platform/guidance/coe/setup)
+- [Set Up Audit Log Components](https://learn.microsoft.com/power-platform/guidance/coe/setup-auditlog)
+- [Office 365 Management Activity API Reference](https://learn.microsoft.com/office/office-365-management-api/office-365-management-activity-api-reference)
+
+---
+
+Please let us know if you have any questions or if you're still experiencing issues after following these guides!
+
+---
+
+## Customization Notes for Responders
+
+When using this template:
+1. Replace relative links with full GitHub links to the documentation files
+2. Adjust the response based on the specific details provided by the issue reporter
+3. If they've already tried some steps, acknowledge that and focus on what they haven't tried
+4. If multiple issues are reported, address each one or ask them to split into separate issues
+5. Add labels: `area: audit logs`, `type: configuration`, `status: needs information` (if waiting for user response)