SPOService.CrossPlatform

Author(s)

• Henki Papp

Tags

SharePoint SharePointOnline SPO Office365 CSOM CrossPlatform MacOS Linux

Functions

Connect-SPOServiceCrossPlatform Disconnect-SPOServiceCrossPlatform

PSEditions

Core

Dependencies

• • Microsoft.Online.SharePoint.PowerShell (>= 16.0.26615.12013)

Release Notes

Stabilisation release ahead of 1.0. Fixes the 0.2.0 package's corrupted dependency floor, hardens the pre-authentication boundary (admin URL shape, deterministic vendor selection, reflected-API probe), and makes the URL-only quick start actually start interactive sign-in. 0.3.0-rc1 was published for manual verification on macOS; the two findings from that matrix (Ctrl+C during browser sign-in, vendor floor) are fixed in this release and were re-verified against a local build before promotion.

Changed:

- Breaking: Connect-SPOServiceCrossPlatform -Url <admin-url> with no other parameters now starts interactive system-browser sign-in, matching the native Connect-SPOService and the README quick start. Previously the URL-only call bound to the certificate parameter set and prompted for ClientId, TenantId and CertificatePath. -UseSystemBrowser still works and is now optional. Certificate and .env flows are unchanged and still select their parameter sets deterministically; combinations that mix sets fail at parameter binding. Unattended scripts must pass certificate parameters explicitly. To fail fast instead of hanging on a browser that cannot open, interactive sign-in is refused up front over SSH without a forwarded display, on Linux with no DISPLAY/WAYLAND_DISPLAY, and in Azure Cloud Shell, with a message pointing at certificate auth.

Security:

- Admin URL validation now accepts only canonical commercial-cloud hosts of the exact form https://<tenant>-admin.sharepoint.com. Previously the host check allowed arbitrary suffixes after .sharepoint.com, so a URL such as https://contoso-admin.sharepoint.com.attacker.example/ passed validation and reached the sign-in request. Non-default ports, user-info, paths, query strings, fragments, punycode labels and sovereign-cloud domains are rejected, and the check now runs before the vendor module loads. Sovereign clouds (sharepoint.us, .de, .cn) are unsupported until an authority mapping exists; this is a validation fix, not a confirmed token-exfiltration path.

Fixed:

- Vendor module selection is deterministic. Connect-SPOServiceCrossPlatform reuses an already-loaded Microsoft.Online.SharePoint.PowerShell if it meets the manifest minimum, otherwise imports the highest installed version that does, and refuses clearly when the only loaded or installed versions are older (a loaded vendor assembly cannot be swapped; the fix is a new session or Update-Module). Previously the first module returned by Get-Module was used without ordering or a version check.
- Every non-public vendor member the connect path relies on (constructors, sign-in methods, settable properties) is now probed before authentication or any global state change. A vendor build that changed its internals fails with one error listing the missing members, vendor version and path, and PowerShell/runtime/OS/architecture, with a link to the issue tracker and no tenant data. Disconnect-SPOServiceCrossPlatform no longer depends on module list order and stays idempotent.
- -ClientTag is capped at 13 characters at parameter binding. The vendor prepends its own TAPS (<version>) tag and CSOM limits the combined value to 32 characters, so longer tags failed inside the vendor constructor with an opaque out-of-range error on every tested build.
- A failed connection leaves any existing connection untouched and disposes the partially built vendor context. SPOService.CurrentService is only assigned after the admin-site check succeeds; the original error surfaces unchanged.
- Ctrl+C during interactive sign-in now returns the prompt within about a quarter second. The vendor's OAuthSession.SignIn is async in name only: it blocks its calling thread until sign-in completes or its 90-second timer fires, so the previous poll loop never ran and Ctrl+C was ignored until the vendor gave up (found in 0.3.0-rc1 manual testing). The module now invokes sign-in on a background thread via the shim's BackgroundInvoker and polls it. The vendor thread and loopback listener still run until the vendor's timeout because its API exposes no cancellation token.
- Importing this release into a session that already loaded an older shim DLL (for example after testing 0.3.0-rc1) now fails with advice to start a new session, instead of a type-resolution error at sign-in.
- .env handling is pinned by tests as opt-in and literal: only the explicit -EnvPath (default ./.env) is read, with no variable, tilde or shell expansion of values.
- The minimum Microsoft.Online.SharePoint.PowerShell version is raised from 16.0.23408.12000 to 16.0.26615.12013. Manual 0.3.0-rc1 testing against the old floor showed it lacks the certificate OAuthSession constructor and SignInWithCert, so certificate auth could never have worked there; the vendor contract probe refused it cleanly before authentication. Every Gallery build from 16.0.26615.12013 through 16.0.27709.12000 was probed and passes the full member contract; 16.0.26510.12000 and earlier do not.
- Interactive sign-in works with Microsoft.Online.SharePoint.PowerShell 16.0.27709.12000, which replaced the system-browser OAuthSession(string, bool) constructor with OAuthSession(string, bool, Action<string>). Previously the vendor contract probe refused that build before authentication. The module now accepts either shape and passes no warning callback, as the vendor's own Connect-SPOService does on most paths; those warnings belong to the WAM broker path, which the vendor disables for system-browser sign-in.
- Release staging now copies the manifest unchanged, preserving the SPO dependency floor. The 0.2.0 Gallery package incorrectly declared 0.2.0 as its dependency minimum because the release workflow replaced both ModuleVersion assignments.
- Tags must match committed version and prerelease metadata before builds or publishing approval. Failed staging cleans up its output.
- PowerShell Gallery release notes show this version's CHANGELOG section as plain text instead of a link to CHANGELOG.md (0.3.0-rc1 showed the link). The Gallery displays the notes from the packaged manifest verbatim, so release staging writes the section into the staged manifest's ReleaseNotes (Markdown markers removed, wrapped lines joined) and fails if any other manifest key changed. The GitHub release keeps the Markdown.
- Removed identifying certificate fields and captured tenant properties from investigation notes; added source-only privacy checks for pull requests.