Document national/sovereign cloud usage in Connect-EntraExporter (#118) - #123
eduardarbona (earbona23) wants to merge 2 commits into
Conversation
Connect-EntraExporter already forwards -Environment to Connect-MgGraph, but the parameter was undocumented and the Graph-to-Az environment mapping threw a misleading "Unknown environment" error for valid national/sovereign clouds that simply have no Azure Resource Manager equivalent. - Add comment-based help for -Environment plus a USGov example. - Replace the "Unknown environment" throw with an actionable message explaining that the cloud has no matching Az environment, so Az-based export types (IAM, PIMResources, ...) aren't available there. - Add a "National and sovereign clouds" section to the README: how to use -Environment, listing endpoints via Get-MgEnvironment, the Az-type caveat, and the custom app registration / WAM redirect URI / Microsoft.Graph. Authentication v2.36.1+ requirement for sovereign clouds. Fixes microsoft#118
|
Thanks for submitting this important clean-up/catch-up work! |
There was a problem hiding this comment.
🟡 Changes recommended
Sovereign-cloud custom-application guidance is not usable through Connect-EntraExporter without a client ID connection path.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Documents national and sovereign cloud usage for Connect-EntraExporter.
Changes:
- Documents the
-Environmentparameter and USGov usage. - Clarifies limitations for Az-backed export types.
- Improves unmapped-environment errors.
- Adds sovereign-cloud authentication guidance.
File summaries
| File | Summary |
|---|---|
src/Connect-EntraExporter.ps1 |
Adds environment documentation and improved error handling. |
README.md |
Documents sovereign-cloud configuration and limitations. |
Review details
Suppressed comments (2)
src/Connect-EntraExporter.ps1:12
.Namereturns only the environment names, not their Graph endpoints, so this sentence does not provide the command it claims to provide. UseGet-MgEnvironment | Select-Object Name, GraphEndpointhere as in the README, or limit the claim to listing names.
The value is passed to Connect-MgGraph (and translated to the matching Azure environment for Connect-AzAccount when an Az-based export type is selected). The list of valid names and their Graph endpoints is provided by the installed Microsoft Graph PowerShell SDK and can be listed with (Get-MgEnvironment).Name.
src/Connect-EntraExporter.ps1:14
- Because
Connect-EntraExporterdoes not accept aClientId, this new help text does not provide a usable connection path for the listed sovereign clouds: it invokesConnect-MgGraphwith the default application, which those environments reject. Add a client-id parameter/pass-through or state that users must connect withConnect-MgGraph -ClientId ...and then callExport-Entra.
Sovereign cloud environments (for example BleuCloud, DelosCloud, GovSGCloud) require a custom application registration and Microsoft.Graph.Authentication v2.36.1 or later. See the "National and sovereign clouds" section of the README for details.
- Files reviewed: 2/2 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| > Export types that rely on Azure Resource Manager (for example `IAM`, `PIMResources`) require `Connect-AzAccount` and are only available in clouds that have a matching Azure environment (`Global`, `USGov`, `USGovDoD`, `China`). In other clouds, select only Microsoft Graph based export types. | ||
|
|
||
| > [!IMPORTANT] | ||
| > Sovereign cloud environments (for example `BleuCloud`, `DelosCloud`, `GovSGCloud`) require a **custom application registration** — the default Microsoft Graph PowerShell application cannot be used in these environments. When registering your application, add a redirect URI of `ms-appx-web://Microsoft.AAD.BrokerPlugin/<YOUR_APP_CLIENT_ID>` to support WAM broker-based authentication, and use `Microsoft.Graph.Authentication` v2.36.1 or later. Refer to `Get-Help Connect-MgGraph -Full` and the [Microsoft Graph PowerShell SDK](https://github.com/microsoftgraph/msgraph-sdk-powershell) for the current guidance. |
There was a problem hiding this comment.
Confirmed, and thanks for catching it. Connect-EntraExporter has no -ClientId parameter and calls Connect-MgGraph -TenantId $TenantId -Environment $Environment -Scopes $graphScope, i.e. always the default Graph PowerShell application. So the note as I wrote it pointed at a flow that cannot succeed in those clouds.
Fixed in c230d9d by documenting the path that does work rather than adding a parameter, to keep this PR to documentation: Export-Entra only requires an active Get-MgContext — it says as much in its own "Run Connect-EntraExporter or Connect-MgGraph to sign in and then retry" error — so Connect-MgGraph -ClientId ... -Environment ... -Scopes ... followed by Export-Entra is already a supported entry point. The README note now shows exactly that, and the -Environment help text states the -ClientId limitation instead of implying Connect-EntraExporter can be used there.
Adding a -ClientId pass-through to Connect-EntraExporter does look worth doing, but it changes behaviour rather than documenting it. Happy to open that as a separate PR if you want it.
| 'Germany' { throw "'Germany' is deprecated environment." } | ||
| default { throw "Unknown environment '$Environment'." } | ||
| 'Germany' { throw "'Germany' is a deprecated environment." } | ||
| default { throw "The '$Environment' environment has no matching Azure Resource Manager (Az) environment, so export types that require Az authentication (e.g. IAM, PIMResources) are not available in this cloud. Re-run the export selecting only Microsoft Graph based types." } |
There was a problem hiding this comment.
Agreed — corrected in c230d9d. The throw sits in the Graph-to-Az environment mapping inside Connect-EntraExporter, and whether Az auth is needed at all is derived from the -Type passed to that same command (via Get-EEAzAuthRequirement), so the actionable change is to that call, not to the export. The message now reads:
Re-run Connect-EntraExporter with -Type limited to Microsoft Graph based export types (omit -Type to use the default 'Config' set).
…nd in the Az error Connect-EntraExporter has no -ClientId parameter, so the custom application registration the sovereign-cloud note asks for cannot be supplied through it. Following the note as written still lands on the default Graph PowerShell application. Document the path that does work in those clouds: Connect-MgGraph with -ClientId/-Environment/-Scopes, then Export-Entra, which only needs an active Get-MgContext and already says so in its own error message. - README: show the Connect-MgGraph + Export-Entra flow for sovereign clouds. - The Az mapping throw is raised by Connect-EntraExporter, before any export runs, so name that command and the -Type change instead of saying "re-run the export". - Help for -Environment: (Get-MgEnvironment).Name returns names only, so use Get-MgEnvironment | Select-Object Name, GraphEndpoint as the README does.
|
Thanks for the review, Sam Erde (@SamErde). Since your approval landed just before the automated review comments, flagging that I pushed c230d9d on top — still documentation and help text only, no behaviour change:
The one thing I deliberately did not do is add a |
Addresses #118.
Context
Connect-EntraExporteralready forwards-EnvironmenttoConnect-MgGraph, and the valid names/endpoints come from the Microsoft Graph PowerShell SDK (Get-MgEnvironment) rather than a hardcoded list — so the Graph side stays current with the SDK. What was missing/outdated:-Environmentparameter was undocumented (no comment-based help, no README mention).switchthrew a misleadingUnknown environment '<name>'for any environment without an Azure Resource Manager equivalent (including newer sovereign clouds) when an Az-based export type was selected.Changes
src/Connect-EntraExporter.ps1-Environmentand a-Environment USGovexample.Unknown environmentthrow with an actionable message: the selected cloud has no matching Az environment, so Az-based export types (IAM,PIMResources, ...) aren't available there — re-run with only Microsoft Graph based types. The known mappings (USGov/USGovDoD → AzureUSGovernment, Global → AzureCloud, China → AzureChinaCloud) are unchanged.README.md— new "National and sovereign clouds" subsection:-Environment(with a USGov example).Get-MgEnvironment(so the doc doesn't go stale).ms-appx-web://Microsoft.AAD.BrokerPlugin/<YOUR_APP_CLIENT_ID>WAM redirect URI +Microsoft.Graph.Authenticationv2.36.1+ requirement for sovereign clouds, as noted in Update Connect-EntraExporter with new sovereign cloud endpoints #118.I intentionally did not hardcode Azure environment names for the newer partner sovereign clouds (BleuCloud/DelosCloud/GovSGCloud) or force-bump the module's minimum
Microsoft.Graph.Authenticationdependency, since the v2.36.1 requirement is specific to sovereign clouds and shouldn't be imposed on commercial-cloud users. Happy to adjust if you'd prefer either.Verification
Parser.ParseFile— no syntax errors.PSScriptAnalyzer— no new findings (only pre-existing repo-wide warnings remain).switchstill maps USGov/USGovDoD/Global/China correctly and throws the new actionable message for an unmapped cloud.Related
The actual GCC-High export failure in #117 (batch requests hitting the commercial endpoint) is fixed separately in #122 — that's the change that makes national-cloud exports actually run. This PR complements it by documenting connection and clarifying the Az-type limitation.