DevicetoAADGroupGUI

A PowerShell GUI application to manage Azure AD device group memberships.

Features

• User-friendly GUI interface
• Import device names from text input (supports comma, semicolon, or space-separated values)
• Create and manage CSV files containing device names
• Add devices to Azure AD groups
• Exact-match validation for Azure AD group and device names to avoid unintended assignments
• Confirmation dialogs before cleanup and Azure AD membership changes
• Asynchronous Add-to-Group processing with progress feedback in the GUI
• Configurable retry and timeout handling for Azure AD operations
• Detailed logging of operations
• Real-time CSV content preview

Prerequisites

System Requirements

• PowerShell 7+
• Windows 10/11 or Windows Server 2016+
• .NET Framework 4.7.2+ (for Windows PowerShell) or .NET 6+ (for PowerShell 7)
• Single-Threaded Apartment (STA) mode support for GUI and authentication dialogs

Microsoft Graph PowerShell Modules

• Microsoft.Graph PowerShell SDK (will be auto-installed if missing)

  Install-Module Microsoft.Graph -Scope CurrentUser -Force

• Automatic fallback: If AzureAD cannot be found in configured repositories, the script switches to Microsoft Graph modules automatically.

Permissions & Authentication

• Microsoft Entra ID account with appropriate permissions:
  • Directory Reader or Groups Reader role to search for devices and groups
  • Groups Administrator, User Administrator, or Global Administrator role to modify group memberships
• Interactive login capability - the script requires browser-based or window-based authentication
• Network connectivity to Azure AD endpoints

PowerShell Execution Policy

• Execution policy must allow script execution:

  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Additional Notes

• For PowerShell 7 users: The script uses Microsoft Graph directly and no longer depends on AzureAD compatibility mode
• Corporate environments: Ensure Group Policy doesn't block interactive authentication dialogs
• Multi-factor Authentication (MFA): Supported through interactive login window

Installation

1. Clone the repository:

   git clone https://github.com/roalhelm/DevicetoAADGroupGUI.git
   cd DevicetoAADGroupGUI

2. Set execution policy (if needed):

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Install Microsoft Graph (auto-installed on first run, or manually):

Install-Module Microsoft.Graph -Scope CurrentUser -Force

4. **Verify PowerShell version and STA mode:**
```powershell
# Check PowerShell version
$PSVersionTable.PSVersion

# Check if running in STA mode (should be 'STA')
[System.Threading.Thread]::CurrentThread.ApartmentState

5. Test Microsoft Graph connectivity (optional):

Connect-MgGraph -Scopes "Group.ReadWrite.All","GroupMember.ReadWrite.All","Device.Read.All","Directory.Read.All"

## Usage

1. Run the main script:
```powershell
.\DevicetoAADGroupGUI.ps1

2. In the GUI:
   • Enter device names in the left text box (separated by commas, semicolons, or spaces)
   • Click "Create CSV" to generate the device list
   • Enter the Azure AD group name

• Click "Add to AAD Group" to add the devices (exact group and device name matching)
• Track progress in the status area while the operation runs asynchronously
• Use "Cleanup CSV" to clear the device list (with confirmation)
• Monitor the operation results in the generated log files

Files

• DevicetoAADGroupGUI.ps1 - Main GUI application
• Add-DevicesToAADGroupFunction.ps1 - Core functionality for Azure AD operations
• Devices.csv - Generated CSV file containing device names
• MANUAL_TEST_MATRIX.md - Reproducible manual test scenarios and expected results

Logging

The script generates two log files for each operation:

• logs/Device_Addition_Log_[timestamp].txt - General operation log
• logs/Device_Addition_ErrorLog_[timestamp].txt - Error details

Troubleshooting

Authentication Issues

• Login window doesn't appear:

  • Ensure you're running in STA mode (the script auto-handles this)
  • Try running PowerShell as Administrator
  • Check if Group Policy blocks interactive authentication

• Authentication fails:

  • Verify your Microsoft Entra ID account has the required permissions
  • Try device code authentication as fallback:

    Connect-MgGraph -UseDeviceCode

PowerShell 7 Specific

• Microsoft Graph module issues:
  • Ensure Microsoft.Graph.Authentication, Microsoft.Graph.Groups, and Microsoft.Graph.Identity.DirectoryManagement are installed
  • If issues persist, try updating the Microsoft Graph PowerShell SDK

GUI Issues

• Window doesn't open:
  • Ensure .NET Framework 4.7.2+ is installed
  • Check execution policy allows script execution
  • Verify STA apartment state

Permission Errors

• "Access Denied" when adding to groups:
  • Verify you have the required Entra ID role and Graph permissions
  • Ensure the target group exists and you have write access
  • Check if the group is security-enabled and supports device members

Common Error Solutions

• "Multiple groups found": Use a more specific group name
• "Device not found": Verify device names match exactly as registered in Microsoft Entra ID
• Module import errors": Try updating Microsoft.Graph and reinstalling the required submodules

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Created by Ronny Alhelm (2025)