microsoft · mohamrizwa · Jan 20, 2026 · Jan 14, 2026 · Jan 14, 2026
diff --git a/README.md b/README.md
@@ -59,6 +59,10 @@ If you are interested in contributing to the CoE Starter Kit by fixing issues or
 ## Setup Instructions and Documentation
 Please find all information on how to install and use the kit on https://docs.microsoft.com/power-platform/guidance/coe/starter-kit
 
+### Additional Documentation
+- [Service Principal Support Guide](docs/ServicePrincipalSupport.md) - Guidance on using Service Principals with CoE Starter Kit
+- [Documentation Index](docs/README.md) - Additional guides and documentation
+
 ## Microsoft Open Source Code of Conduct
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,27 @@
+# CoE Starter Kit Documentation
+
+This directory contains additional documentation and guides for the CoE Starter Kit.
+
+## Available Documentation
+
+### [Service Principal Support Guide](./ServicePrincipalSupport.md)
+Comprehensive guide on using Service Principals with the CoE Starter Kit, including:
+- Understanding Service Principals vs Service Accounts
+- Component-specific support details
+- Migration guidance from Service Account to Service Principal
+- Best practices and FAQs
+
+## Official Documentation
+
+For complete setup instructions and documentation, please visit:
+- [Microsoft Power Platform CoE Starter Kit Documentation](https://learn.microsoft.com/power-platform/guidance/coe/starter-kit)
+
+## Contributing
+
+If you'd like to contribute to the documentation, please see [HOW_TO_CONTRIBUTE.md](../HOW_TO_CONTRIBUTE.md) in the root of this repository.
+
+## Questions and Issues
+
+- **Questions**: Use the [Question issue template](../.github/ISSUE_TEMPLATE/5-coe-starter-kit-question.yml)
+- **Bug Reports**: Use the appropriate [issue template](../.github/ISSUE_TEMPLATE/)
+- **Discussions**: Visit [GitHub Discussions](https://github.com/microsoft/coe-starter-kit/discussions)
diff --git a/docs/ServicePrincipalSupport.md b/docs/ServicePrincipalSupport.md
@@ -0,0 +1,238 @@
+# Service Principal Support in CoE Starter Kit
+
+## Overview
+
+This document provides guidance on using Service Principals with the CoE Starter Kit components, including installation, management, and migration from Service Accounts.
+
+## Understanding Service Principals vs Service Accounts
+
+### Service Account
+- A licensed user account (typically with a generic name like `svc-coe@contoso.com`)
+- Requires a Power Platform license
+- Uses traditional username/password or MFA authentication
+- Owns cloud flows and apps
+- Can interact with the UI
+
+### Service Principal (Application User)
+- An Azure AD application registration
+- Uses client ID and secret or certificate for authentication
+- No interactive login capability
+- Does not require a traditional Power Platform license (uses capacity-based licensing)
+- Cannot own cloud flows in the traditional sense
+
+## CoE Starter Kit Component Support
+
+### 1. CoE Core Components (Cloud Flows)
+
+**Current Limitation**: The CoE Core Components primarily use **Cloud Flows** which have the following constraints:
+
+- **Cloud flows require a user context** - They cannot be owned or run purely by a Service Principal
+- Cloud flows need connection references that authenticate as a user
+- The flows execute in the context of the user who owns the flow
+
+**Recommendation**: 
+- **Use a Service Account** for CoE Core Components
+- Ensure the service account has:
+  - Appropriate Power Platform licenses (Power Apps Per User or Per App, or Power Automate Per User)
+  - System Administrator role in the CoE environment
+  - Global View privileges or Power Platform Administrator role for tenant-wide inventory
+
+**Workaround Considerations**:
+While Service Principals cannot directly own cloud flows, you can use Service Principals for specific operations:
+- Custom connectors that need to authenticate to external systems
+- Azure AD app registrations for Power Apps Management cmdlets
+- Backend services called by the flows
+
+### 2. ALM Accelerator for Power Platform
+
+**Full Service Principal Support**: The ALM Accelerator **fully supports** Service Principals and is the recommended approach.
+
+**Capabilities**:
+- Service Principal can be configured as the identity for Azure DevOps service connections
+- Service Principal is assigned as an Application User with System Administrator privileges
+- Handles solution import/export operations
+- Manages environment deployments
+
+**Setup Using CoE CLI**:
+The CoE CLI provides automated setup with Service Principal:
+
+```bash
+coe alm install -f install.json
+```
+
+The install process will:
+- Create the Azure AD application if it doesn't exist
+- Assign the application as the identity for service connections
+- Configure the Application User in Power Platform environments with System Administrator privileges
+- Set up necessary permissions for solution import/export
+
+**Required Permissions**:
+The Service Principal needs:
+- **Azure AD Application Registration permissions** to create the app
+- **Power Platform Application User** role with System Administrator privileges
+- **Power App Management permissions** - Grant using PowerShell:
+
+```powershell
+Install-Module -Name Microsoft.PowerApps.Administration.PowerShell
+Install-Module -Name Microsoft.PowerApps.PowerShell -AllowClobber
+Add-PowerAppsAccount
+
+# Register the Service Principal as a management application
+New-PowerAppManagementApp -ApplicationId <your-app-id>
+```
+
+**Note**: The `New-PowerAppManagementApp` cmdlet grants elevated permissions (Power Platform Admin level). Verify this aligns with your organization's security policies before proceeding.
+
+For more details, see:
+- [ALM Install Documentation](../coe-cli/docs/help/alm/install.md)
+- [Service Connection Setup](../coe-cli/docs/help/alm/connection/add.md)
+
+### 3. Other Components
+
+| Component | Service Principal Support | Notes |
+|-----------|--------------------------|-------|
+| **Governance Components** | Limited (via Service Account) | Cloud flows require user context |
+| **Nurture Components** | Limited (via Service Account) | Cloud flows require user context |
+| **Audit Log Components** | Limited (via Service Account) | Cloud flows require user context |
+| **Innovation Backlog** | Limited (via Service Account) | Cloud flows require user context |
+| **Theming** | Limited (via Service Account) | Cloud flows require user context |
+
+## Migration from Service Account to Service Principal
+
+### For ALM Accelerator (Supported)
+
+If you're currently using a Service Account for the ALM Accelerator and want to migrate to Service Principal:
+
+#### Step 1: Create Service Principal
+1. Register a new Azure AD application
+2. Create a client secret or certificate
+3. Note the Application (client) ID and tenant ID
+
+#### Step 2: Configure Service Principal in Power Platform
+```powershell
+# Add Application User to environments
+Add-PowerAppsAccount
+
+# For each environment, add the Service Principal as an application user
+# This is typically done through the Power Platform Admin Center:
+# Settings > Users + permissions > Application users > New app user
+```
+
+#### Step 3: Update Azure DevOps Service Connections
+1. Navigate to Project Settings > Service connections in Azure DevOps
+2. Create new service connections using the Service Principal
+3. Update pipeline variables to reference the new service connections
+
+#### Step 4: Grant Power App Management Permissions
+```powershell
+Add-PowerAppsAccount
+New-PowerAppManagementApp -ApplicationId <your-service-principal-app-id>
+```
+
+#### Step 5: Test and Validate
+1. Run a test pipeline to ensure the Service Principal has appropriate permissions
+2. Validate solution import/export operations
+3. Verify canvas app sharing and connection updates work correctly
+
+#### Step 6: Update Documentation
+Document the Service Principal details (Application ID, where secrets are stored, etc.) for your team.
+
+### For CoE Core Components (Not Currently Supported)
+
+**Current State**: Direct migration from Service Account to Service Principal is **not supported** for cloud flows.
+
+**Recommended Approach**:
+1. **Continue using a Service Account** for CoE Core Components
+2. Implement best practices:
+   - Use a dedicated service account with a strong, managed password
+   - Store credentials in a secure password vault
+   - Enable MFA if your organization allows for service accounts
+   - Rotate passwords on a regular schedule
+   - Document the account ownership and purpose
+   - Assign minimal required permissions
+
+**Future Considerations**:
+- Monitor Microsoft's roadmap for Service Principal support in cloud flows
+- Consider desktop flows or custom code components that can use Service Principal authentication
+- Evaluate Azure Automation or Azure Functions for operations that can use Service Principal
+
+## Best Practices
+
+### For Service Accounts
+1. **Naming Convention**: Use clear naming like `svc-coe@contoso.com`
+2. **License Management**: Assign appropriate licenses and monitor for compliance
+3. **Security**: 
+   - Store passwords in Azure Key Vault or enterprise password manager
+   - Enable conditional access policies where appropriate
+   - Regularly rotate credentials
+4. **Documentation**: Maintain clear documentation of purpose and ownership
+5. **Monitoring**: Set up alerts for unusual activity
+
+### For Service Principals
+1. **Secret Management**: 
+   - Store client secrets in Azure Key Vault
+   - Use certificates instead of secrets where possible
+   - Rotate secrets before expiration
+   - Set up alerts for expiring secrets
+2. **Permissions**: Grant least-privilege access
+3. **Audit**: Enable Azure AD audit logs for the application
+4. **Documentation**: Document application ID, purpose, and where secrets are stored
+
+## Frequently Asked Questions
+
+### Q: Can I install the entire CoE Starter Kit using only a Service Principal?
+**A**: No. The CoE Core, Governance, Nurture, and Audit components require a Service Account because they use cloud flows that need user context. Only the ALM Accelerator fully supports Service Principal authentication.
+
+### Q: Why can't cloud flows use Service Principals?
+**A**: Cloud flows in Power Automate require connection references that authenticate as a user. The flows execute in the context of the flow owner, which must be a licensed user. This is a platform limitation, not specific to the CoE Starter Kit.
+
+### Q: What licenses does a Service Account need for CoE Core Components?
+**A**: The service account needs:
+- Power Apps Per User license (or Power Apps Per App if only running specific apps)
+- Power Automate Per User license (for flow ownership)
+- Appropriate Dataverse privileges
+- Global View or Power Platform Administrator role for tenant-wide operations
+
+### Q: Can I use a Service Principal for the connection references in cloud flows?
+**A**: No. Connection references in cloud flows must authenticate as a user. However, custom connectors called by those flows can use Service Principal authentication.
+
+### Q: Is there a roadmap for Service Principal support in cloud flows?
+**A**: Service Principal support for cloud flows is not currently available. Check the [Power Platform release plans](https://learn.microsoft.com/power-platform/release-plan/) for future updates.
+
+### Q: What happens to flows when a Service Account password changes?
+**A**: When the service account password changes, all connection references using that account will break. You'll need to:
+1. Navigate to each flow
+2. Edit the connections
+3. Re-authenticate with the new password
+4. Save and test the flow
+
+To minimize disruption, plan password changes during maintenance windows.
+
+### Q: Can I use managed identities instead of Service Principals?
+**A**: Managed identities are primarily for Azure resources. For Power Platform:
+- Desktop flows can use managed identities when running on Azure VMs
+- Cloud flows still require user authentication
+- Azure-hosted components (Functions, Logic Apps) can use managed identities
+
+## Additional Resources
+
+- [Microsoft Power Platform CoE Starter Kit Documentation](https://learn.microsoft.com/power-platform/guidance/coe/starter-kit)
+- [ALM Accelerator Setup Guide](../CenterofExcellenceALMAccelerator/SETUPGUIDE.md)
+- [Power Apps Service Principal Documentation](https://learn.microsoft.com/power-platform/admin/create-users#create-an-application-user)
+- [New-PowerAppManagementApp Cmdlet](https://learn.microsoft.com/powershell/module/microsoft.powerapps.administration.powershell/new-powerappmanagementapp)
+- [Azure AD Application Registration](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal)
+
+## Support
+
+The CoE Starter Kit is provided as-is with community support:
+- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) - Report bugs or ask questions
+- [GitHub Discussions](https://github.com/microsoft/coe-starter-kit/discussions) - Community discussions
+- [Power Platform Community](https://powerusers.microsoft.com/) - Broader Power Platform questions
+
+For production support, consider engaging with Microsoft support or a Microsoft partner.
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: January 2026  
+**Applies To**: CoE Starter Kit All Versions