ENTRA-REFACTOR-MAPPING.json
|
{
"refactor_summary": { "project": "O365-Toolkit", "objective": "Replace Microsoft.Graph SDK with Entra PowerShell modules", "scope": "All files in Public/ directory", "total_files_affected": 13, "migration_notes": [ "Connect-MgGraph → Connect-Entra (with updated scopes)", "Disconnect-MgGraph → Disconnect-Entra", "Get-MgContext → Get-EntraContext", "Get-Mg* → Get-Entra* (most cases)", "New-Mg* → New-Entra* (most cases)", "Set-Mg* → Set-Entra* (most cases)", "Remove-Mg* → Remove-Entra* (most cases)", "Update-Mg* → Set-Entra* or Update-Entra* (depends on cmdlet)", "Invoke-MgGraphRequest → Replace with native Entra cmdlets where possible", "Parameter name mappings vary by cmdlet (e.g., -UserId → -ObjectId for users, but -UserId for some other contexts)", "Beta cmdlets use format Get-EntraBeta<Noun> for beta-only features" ] }, "replacements_by_file": { "Authentication.ps1": { "file_path": "Public/Authentication.ps1", "total_replacements": 8, "replacements": [ { "old_pattern": "Connect-MgGraph", "new_pattern": "Connect-Entra", "notes": "All instances across the file. Update scopes to Entra equivalents.", "parameter_mapping": { "-Scopes": "-Scopes (same structure but use Entra scope names)", "-TenantId": "-TenantId (same)", "-AppId": "-AppId (same)", "-CertificateThumbprint": "-CertificateThumbprint (same)", "-Environment": "Not applicable in Entra (use -Environment parameter differently or handle beta separately)" }, "occurrences": 3, "lines": [49, 158, 167], "complexity": "high", "notes_detailed": "Line 49: Interactive browser auth - scopes may need adjustment. Lines 158, 167: Certificate-based and beta env connections need special handling." }, { "old_pattern": "Disconnect-MgGraph", "new_pattern": "Disconnect-Entra", "notes": "Direct 1:1 replacement", "occurrences": 1, "lines": [200], "complexity": "low" }, { "old_pattern": "Get-MgContext", "new_pattern": "Get-EntraContext", "notes": "Direct 1:1 replacement", "occurrences": 3, "lines": [50, 291, 321], "complexity": "low" }, { "old_pattern": "Invoke-MgGraphRequest -Uri \"/v1.0/organization\"", "new_pattern": "Get-EntraOrganization", "notes": "Replace with native Entra cmdlet for getting organization info", "occurrences": 2, "lines": [60, 375], "complexity": "medium", "parameter_mapping": { "-Uri \"/v1.0/organization\"": "No parameters needed (Get-EntraOrganization returns org info directly)" }, "code_changes": "Remove | Select-Object -ExpandProperty value | Select-Object -First 1 if Entra cmdlet returns single object" } ] }, "UserManagement.ps1": { "file_path": "Public/UserManagement.ps1", "total_replacements": 6, "replacements": [ { "old_pattern": "New-MgUser", "new_pattern": "New-EntraUser", "notes": "Create new users with Entra cmdlet", "parameter_mapping": { "-UserId": "Not used in New-EntraUser", "All parameters": "Should map 1:1 for standard user properties" }, "occurrences": 1, "lines": [108], "complexity": "medium" }, { "old_pattern": "Set-MgUserLicense", "new_pattern": "Set-EntraUserLicense", "notes": "License assignment", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify Entra naming)", "-AddLicenses": "-AddLicenses (same structure)", "-RemoveLicenses": "-RemoveLicenses (same structure)" }, "occurrences": 1, "lines": [118], "complexity": "medium" }, { "old_pattern": "Get-MgUser", "new_pattern": "Get-EntraUser", "notes": "Retrieve user information", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)", "-Filter": "-Filter (same syntax)" }, "occurrences": 3, "lines": [198, 261, 263], "complexity": "medium" }, { "old_pattern": "New-MgInvitation", "new_pattern": "New-EntraInvitation", "notes": "Guest user invitations", "parameter_mapping": { "-InvitedUserEmailAddress": "-InvitedUserEmailAddress (same)", "-InviteRedirectUrl": "-InviteRedirectUrl (same)", "-SendInvitationMessage": "-SendInvitationMessage (same)" }, "occurrences": 1, "lines": [256], "complexity": "low" }, { "old_pattern": "Remove-MgUser", "new_pattern": "Remove-EntraUser", "notes": "Delete user accounts", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)" }, "occurrences": 1, "lines": [263], "complexity": "low" } ] }, "ConditionalAccess.ps1": { "file_path": "Public/ConditionalAccess.ps1", "total_replacements": 5, "replacements": [ { "old_pattern": "Get-MgIdentityConditionalAccessPolicy", "new_pattern": "Get-EntraConditionalAccessPolicy", "notes": "Retrieve CA policies", "parameter_mapping": { "-All": "-All (same)", "-ConditionalAccessPolicyId": "-ObjectId or -Id (verify exact parameter name)" }, "occurrences": 5, "lines": [26, 91, 138, 185, 188], "complexity": "low" }, { "old_pattern": "Update-MgIdentityConditionalAccessPolicy", "new_pattern": "Set-EntraConditionalAccessPolicy", "notes": "Modify CA policy state and properties", "parameter_mapping": { "-ConditionalAccessPolicyId": "-ObjectId or -Id (verify exact parameter name)", "-BodyParameter": "May need parameter restructuring for Entra" }, "occurrences": 1, "lines": [98], "complexity": "medium" }, { "old_pattern": "New-MgIdentityConditionalAccessPolicy", "new_pattern": "New-EntraConditionalAccessPolicy", "notes": "Create new CA policies", "parameter_mapping": { "-BodyParameter": "May need parameter restructuring for Entra" }, "occurrences": 2, "lines": [154, 257], "complexity": "medium" } ] }, "Group.ps1": { "file_path": "Public/Group.ps1", "total_replacements": 6, "replacements": [ { "old_pattern": "New-MgGroup", "new_pattern": "New-EntraGroup", "notes": "Create Microsoft 365 Groups", "parameter_mapping": { "-DisplayName": "-DisplayName (same)", "-MailEnabled": "-MailEnabled (same)", "-MailNickname": "-MailNickname (same)", "-GroupTypes": "-GroupTypes (same)" }, "occurrences": 1, "lines": [39], "complexity": "low" }, { "old_pattern": "Get-MgUser", "new_pattern": "Get-EntraUser", "notes": "Retrieve user for group member/owner operations", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)" }, "occurrences": 4, "lines": [42, 50, 78, 86], "complexity": "low" }, { "old_pattern": "Remove-MgGroup", "new_pattern": "Remove-EntraGroup", "notes": "Delete groups", "parameter_mapping": { "-GroupId": "-ObjectId or -Id (verify exact parameter name)" }, "occurrences": 1, "lines": [64], "complexity": "low" }, { "old_pattern": "Get-MgGroup", "new_pattern": "Get-EntraGroup", "notes": "Retrieve group information", "parameter_mapping": { "-GroupId": "-ObjectId or -Id (verify exact parameter name)" }, "occurrences": 2, "lines": [72, 92], "complexity": "low" }, { "old_pattern": "Update-MgGroup", "new_pattern": "Set-EntraGroup", "notes": "Modify group properties", "parameter_mapping": { "-GroupId": "-ObjectId or -Id (verify exact parameter name)", "-DisplayName": "-DisplayName (same)" }, "occurrences": 1, "lines": [74], "complexity": "low" }, { "old_pattern": "Add-MgGroupMember / Add-MgGroupOwner", "new_pattern": "Add-EntraGroupMember / Add-EntraGroupOwner", "notes": "Add members and owners to groups", "parameter_mapping": { "-GroupId": "-ObjectId or -Id (verify exact parameter name)", "-DirectoryObjectId": "-ObjectId or -RefObjectId (verify exact parameter name)" }, "occurrences": 2, "lines": [implied in member/owner loops], "complexity": "low" } ] }, "Teams.ps1": { "file_path": "Public/Teams.ps1", "total_replacements": 2, "replacements": [ { "old_pattern": "Get-MgGroup", "new_pattern": "Get-EntraGroup", "notes": "Retrieve Teams (which are special Groups with resourceProvisioningOptions)", "parameter_mapping": { "-Filter": "-Filter (same syntax)" }, "occurrences": 1, "lines": [18], "complexity": "low" }, { "old_pattern": "Get-MgGroupOwner", "new_pattern": "Get-EntraGroupOwner", "notes": "Retrieve Team owners", "parameter_mapping": { "-GroupId": "-ObjectId or -Id (verify exact parameter name)" }, "occurrences": 1, "lines": [22], "complexity": "low" } ] }, "License.ps1": { "file_path": "Public/License.ps1", "total_replacements": 3, "replacements": [ { "old_pattern": "Set-MgUserLicense", "new_pattern": "Set-EntraUserLicense", "notes": "Remove and reassign licenses", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)", "-RemoveLicenses": "-RemoveLicenses (same structure)", "-AddLicenses": "-AddLicenses (same structure)" }, "occurrences": 3, "lines": [40, 52, 53], "complexity": "low" }, { "old_pattern": "Get-MgUser", "new_pattern": "Get-EntraUser", "notes": "Retrieve user for license operations", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)" }, "occurrences": 1, "lines": [44], "complexity": "low" } ] }, "Reporting.ps1": { "file_path": "Public/Reporting.ps1", "total_replacements": 8, "replacements": [ { "old_pattern": "Set-MgRequestContext", "new_pattern": "No direct equivalent in Entra", "notes": "This Graph-specific cmdlet may not be needed with Entra, or may be handled differently.", "occurrences": 2, "lines": [34, 157], "complexity": "high", "migration_strategy": "Research Entra retry/timeout handling or remove if not needed" }, { "old_pattern": "New-MgBetaSecurityAuditLogQuery", "new_pattern": "New-EntraBetaSecurityAuditLogQuery", "notes": "Create audit log query (beta endpoint)", "parameter_mapping": { "-BodyParameter": "May need restructuring for Entra beta cmdlet" }, "occurrences": 1, "lines": [48], "complexity": "medium" }, { "old_pattern": "Get-MgBetaSecurityAuditLogQuery", "new_pattern": "Get-EntraBetaSecurityAuditLogQuery", "notes": "Retrieve audit log query status (beta endpoint)", "parameter_mapping": { "-AuditLogQueryId": "-ObjectId or -Id (verify exact parameter name)" }, "occurrences": 2, "lines": [55, 65], "complexity": "medium" }, { "old_pattern": "Get-MgBetaSecurityAuditLogQueryRecord", "new_pattern": "Get-EntraBetaSecurityAuditLogQueryRecord", "notes": "Retrieve audit log records (beta endpoint)", "parameter_mapping": { "-AuditLogQueryId": "-ObjectId or -Id (verify exact parameter name)", "-All": "-All (same)" }, "occurrences": 1, "lines": [71], "complexity": "low" }, { "old_pattern": "Get-MgContext", "new_pattern": "Get-EntraContext", "notes": "Direct replacement", "occurrences": 1, "lines": [120], "complexity": "low" }, { "old_pattern": "Get-MgUser", "new_pattern": "Get-EntraUser", "notes": "Retrieve user information", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)" }, "occurrences": 1, "lines": [127], "complexity": "low" }, { "old_pattern": "Get-MgUserMailFolderMessage", "new_pattern": "No direct Entra equivalent", "notes": "This is an Exchange/Mail-related cmdlet. May need to stay as Get-MgUserMailFolderMessage or switch to Exchange Online cmdlets.", "occurrences": 3, "lines": [160, 169, 175], "complexity": "high", "migration_strategy": "Research if Entra has mail folder cmdlets; may need hybrid approach with Exchange Online cmdlets" }, { "old_pattern": "Get-MgServiceAnnouncementMessage", "new_pattern": "Get-EntraServiceAnnouncementMessage", "notes": "Retrieve service messages", "parameter_mapping": { "-Sort": "-Sort (same)", "-All": "-All (same)" }, "occurrences": 1, "lines": [241], "complexity": "low" } ] }, "Lifecycle.ps1": { "file_path": "Public/Lifecycle.ps1", "total_replacements": 6, "replacements": [ { "old_pattern": "Get-MgUser", "new_pattern": "Get-EntraUser", "notes": "Retrieve user information", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)" }, "occurrences": 1, "lines": [36], "complexity": "low" }, { "old_pattern": "Update-MgUser", "new_pattern": "Set-EntraUser", "notes": "Update user properties (e.g., disable account)", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)", "-AccountEnabled": "-AccountEnabled (same)" }, "occurrences": 1, "lines": [46], "complexity": "low" }, { "old_pattern": "Get-MgUserDrive", "new_pattern": "No direct Entra equivalent (SharePoint/OneDrive API)", "notes": "This is a SharePoint-related cmdlet; may need to stay with Graph or use PnP.PowerShell.", "occurrences": 1, "lines": [67], "complexity": "high", "migration_strategy": "Consider keeping this as Get-MgUserDrive or switching to Get-PnPSite / SharePoint cmdlets" }, { "old_pattern": "Set-MgUserManagerByRef", "new_pattern": "Set-EntraUserManager", "notes": "Set user's manager relationship", "parameter_mapping": { "-UserId": "-ObjectId or -UserId (verify exact parameter name)", "-AdditionalProperties": "May need restructuring for Entra" }, "occurrences": 1, "lines": [167], "complexity": "medium" }, { "old_pattern": "Send-MgUserMail", "new_pattern": "No direct Entra equivalent (Exchange/Mail API)", "notes": "This is an Exchange-related cmdlet; keep as Send-MgUserMail or use Exchange Online cmdlets.", "occurrences": 1, "lines": [189], "complexity": "high", "migration_strategy": "Keep as Get-MgUserMail or switch to Send-ExoMail or Exchange cmdlets" }, { "old_pattern": "New-MgGroupPlannerPlan", "new_pattern": "New-EntraGroupPlannerPlan", "notes": "Create Planner plan for group", "parameter_mapping": { "-GroupId": "-ObjectId or -Id (verify exact parameter name)", "-Title": "-Title (same)" }, "occurrences": 1, "lines": [249], "complexity": "low" } ] }, "Security.ps1": { "file_path": "Public/Security.ps1", "total_replacements": 1, "replacements": [ { "old_pattern": "Get-MgIdentityConditionalAccessPolicy", "new_pattern": "Get-EntraConditionalAccessPolicy", "notes": "Retrieve CA policies for security analysis", "parameter_mapping": { "No parameters": "Should return all policies by default" }, "occurrences": 1, "lines": [155], "complexity": "low" } ] }, "Export.ps1": { "file_path": "Public/Export.ps1", "total_replacements": 0, "notes": "No direct Graph/Entra calls in this file. It's a utility for HTML export." }, "SharePoint.ps1": { "file_path": "Public/SharePoint.ps1", "total_replacements": 0, "notes": "No Microsoft.Graph or Entra calls in this file. Uses PnP.PowerShell and SharePoint Online cmdlets." }, "Jobs.ps1": { "file_path": "Public/Jobs.ps1", "total_replacements": 0, "notes": "No Graph/Entra calls. Generic PowerShell job management." }, "Gui.ps1": { "file_path": "Public/Gui.ps1", "total_replacements": 0, "notes": "GUI wrapper; calls other functions. No direct Graph/Entra cmdlets. Will inherit changes from called functions." }, "IdentityGovernance.ps1": { "file_path": "Public/IdentityGovernance.ps1", "total_replacements": 0, "notes": "Scanned for Graph/Entra calls - none found. File likely contains JSON-based workflows for Access Packages and permissions but doesn't directly call Graph cmdlets." }, "Configuration.ps1": { "file_path": "Public/Configuration.ps1", "total_replacements": 0, "notes": "Scanned for Graph/Entra calls - none found. File likely contains DSC-style configuration templates." } }, "critical_considerations": { "parameter_name_variations": { "note": "Entra cmdlets may use different parameter names than Graph cmdlets. Common variations:", "examples": [ { "graph_param": "-UserId", "entra_param": "-ObjectId or -UserId (varies by cmdlet)", "recommendation": "Verify each cmdlet's parameters in Entra documentation" }, { "graph_param": "-GroupId", "entra_param": "-ObjectId or -Id", "recommendation": "Verify each cmdlet's parameters in Entra documentation" }, { "graph_param": "-ConditionalAccessPolicyId", "entra_param": "-ObjectId or -Id", "recommendation": "Verify exact parameter naming in Entra CA cmdlets" } ] }, "api_calls_without_direct_entra_equivalents": [ { "graph_call": "Invoke-MgGraphRequest to organization endpoint", "recommendation": "Replace with Get-EntraOrganization if available", "fallback": "Keep Invoke-MgGraphRequest if no Entra equivalent exists" }, { "graph_call": "Set-MgRequestContext (retry/timeout settings)", "recommendation": "Research Entra equivalent or remove if Entra handles retries automatically", "impact": "Affects Reporting.ps1" }, { "graph_call": "Get-MgUserMailFolderMessage (mail/Teams messages)", "recommendation": "No direct Entra equivalent. Keep Graph call or use Exchange Online cmdlets.", "impact": "Affects Reporting.ps1" }, { "graph_call": "Get-MgUserDrive (OneDrive/SharePoint)", "recommendation": "No direct Entra equivalent. Keep Graph call or use PnP.PowerShell.", "impact": "Affects Lifecycle.ps1" }, { "graph_call": "Send-MgUserMail (mail sending)", "recommendation": "No direct Entra equivalent. Keep Graph call or use Exchange Online cmdlets.", "impact": "Affects Lifecycle.ps1 and UserManagement.ps1" } ], "scope_changes_needed": { "note": "Entra scopes differ from Microsoft Graph scopes", "action": "Update all scope definitions in Authentication.ps1", "files_affected": ["Authentication.ps1"] }, "beta_feature_handling": { "note": "Entra beta cmdlets use Get-EntraBeta<Noun> format", "affected_cmdlets": [ "Get-EntraBetaSecurityAuditLogQuery", "New-EntraBetaSecurityAuditLogQuery", "Get-EntraBetaSecurityAuditLogQueryRecord" ], "files_affected": ["Reporting.ps1"] }, "connection_string_format": { "note": "Entra connection differs from Microsoft Graph", "change": "Connect-Entra replaces Connect-MgGraph with different scope/environment handling", "files_affected": ["Authentication.ps1"] } }, "implementation_order": [ { "phase": 1, "description": "Authentication Layer", "files": ["Authentication.ps1"], "priority": "CRITICAL", "rationale": "All other functions depend on proper connection management" }, { "phase": 2, "description": "Core User & Directory Operations", "files": ["UserManagement.ps1", "Group.ps1"], "priority": "HIGH", "rationale": "Foundation for other operations" }, { "phase": 3, "description": "Security & Governance", "files": ["ConditionalAccess.ps1", "Security.ps1"], "priority": "HIGH", "rationale": "Policy-critical operations" }, { "phase": 4, "description": "Licensing & Teams", "files": ["License.ps1", "Teams.ps1"], "priority": "MEDIUM", "rationale": "User-facing features" }, { "phase": 5, "description": "Lifecycle & Reporting", "files": ["Lifecycle.ps1", "Reporting.ps1"], "priority": "MEDIUM", "rationale": "Advanced operations with some Graph-specific APIs" }, { "phase": 6, "description": "Specialized Modules", "files": ["IdentityGovernance.ps1", "Configuration.ps1", "Export.ps1", "SharePoint.ps1", "Jobs.ps1", "Gui.ps1"], "priority": "LOW", "rationale": "Depend on other modules or are utility wrappers" } ], "testing_recommendations": [ "Test authentication with both interactive and certificate-based methods", "Verify all parameter mappings work correctly with sample data", "Test CA policy operations with -WhatIf before enabling on real policies", "Validate user creation, licensing, and group membership workflows", "Test Reporting.ps1 with audit log queries and Teams message searches", "Verify Lifecycle.ps1 onboarding and offboarding workflows", "Ensure GUI (Gui.ps1) functions work with new Entra cmdlets" ], "known_limitations": [ { "limitation": "Mail-related operations (Get-MgUserMailFolderMessage, Send-MgUserMail)", "affected_files": ["Reporting.ps1", "Lifecycle.ps1", "UserManagement.ps1"], "recommendation": "May need to retain Microsoft.Graph calls or hybrid approach with Exchange Online cmdlets" }, { "limitation": "OneDrive/SharePoint API calls (Get-MgUserDrive)", "affected_files": ["Lifecycle.ps1"], "recommendation": "May need to retain Microsoft.Graph calls or use PnP.PowerShell" }, { "limitation": "Planner API calls (New-MgGroupPlannerPlan)", "affected_files": ["Lifecycle.ps1"], "recommendation": "Verify if Entra has direct Planner cmdlets or if Graph retention is necessary" } ] } |