Repository navigation
ConnectWiseControlAPI 0.5.0: MFA and API-secret login, ScreenConnect wording, fixes - #32
Merged
Merged
Conversation
.editorconfig, .gitattributes (line-ending normalization), PSScriptAnalyzer settings, GitHub community files and issue/PR templates, expanded .gitignore. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…retries - Invoke-CWCServiceMethod builds the endpoint (built-in service, RESTful API Manager, or another extension), serializes arguments consistently and logs one redacted line. Replaces the hand-built request blocks in every function. - HTTP 500 retries are opt-in (-Idempotent): a 500 after the server acted could repeat a command, wake, delete or user creation. - Credentials connections keep a WebRequestSession so server cookies are sent back (they were sent as a Set-Cookie request header). Likely fix for #22. - Debug/verbose output redacts auth headers, cookies and secret-bearing bodies. - Connect-CWC validates with GetEligibleHosts (any permission, #14), matches the anti-forgery token by shape, keeps the old connection on a failed -Force, adds -ApiSecret (RESTful API Manager), and explains failed logins. - Session event types in one table, verified live; Remove-CWCSession confirms per session with ConfirmImpact High (#30 equivalent). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> # Conflicts: # ConnectWiseControlAPI/Public/PageService/Remove-CWCSession.ps1
Find-CWCSession (API secret only), New-CWCSession, Add-CWCSessionNote, Send-CWCSessionMessage and Send-CWCToolboxItem. On credentials connections the last three queue AddedNote (32), QueuedMessage (45) and QueuedTool (47) events through PageService.AddSessionEvents; New-CWCSession uses PageService.CreateSession. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Get-CWCLauncURL moves under Remote Workforce and forwards to the new Get-CWCRemoteWorkforceLaunchURL (it sent 6 arguments to a 1-argument method, including an unused plaintext password). Adds Get-CWCRemoteWorkforceSession and Initialize-CWCRemoteWorkforceSessionGroup; Add-CWCRemoteWorkforceRequiredRole uses the extension's idempotent EnsureRemoteWorkforceSecurityRoleExists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pester suites for the module, private helpers and public functions (all HTTP mocked; pass on PS 7 and 5.1), an opt-in live read-only suite, and Tests/Live/Invoke-CWCLiveSmokeTest.ps1 for checks against a real server (event types, write paths, MFA login probe, note cleanup). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0.4.0.0 is already on the PowerShell Gallery (published from 889b56b without a manifest bump), so the next release is 0.5.0.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- RemoveRedundantSessions example kept the OLDEST session and deleted newer ones (ascending sort, then Skip 1), and searched an undefined $GroupNameAll. - Remove the empty, never-loaded ConnectWiseControlAPI.Format.ps1xml. - Drop Invoke-CWCWebRequest's OutFile branch; its only caller was commented out. - CLAUDE.md: tighter contributor notes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PlatyPS update of Docs/ (adds the 8 functions that had no page, refreshes parameter sets such as Connect-CWC -ApiSecret), fills the remaining placeholder descriptions, strips the PS 7.4 -ProgressAction parameter PlatyPS leaks in, removes Docs/Private (internal helpers, outdated), and rebuilds en-US/ConnectWiseControlAPI-help.xml (last built 2023). Adds comment-based help to New-CWCAccessToken. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…le sort - .gitignore's *secret* pattern hid Private/Test-CWCApiSecretConnection.ps1, so a clean clone could not connect at all. Whitelist module source, tests and docs, commit the file, and add a test that fails if any module file is git-ignored. - RemoveRedundantSessions example: LastConnectedEventTime is seconds since the last connection, so the original ascending sort was right; restore it. - HTTP 500: a final failure keeps the server's error body instead of only "Max retries hit"; retries wait 2/4/8 seconds (were 2-32 ms), 3 retries. - Strip auth headers from the failed request on PS 5.1 too (HttpWebRequest). - Invoke-CWCCommand compares event times on the server clock (BaseTime). - Restore [string[]] -Group (nested group path parts) on Update-CWCCustomProperty and New-CWCAccessToken. - CHANGELOG: mark the Remove-CWCSession prompt as breaking. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Single -SessionID/-ConnectionID values: with [guid[]], several IDs were serialized into one event entry. - ConfirmImpact High with a readable ShouldProcess target (was the raw body), empty-GUID validation, [string[]] -Group for nested group paths. - Uses Invoke-CWCServiceMethod and the shared event table (48 = QueuedForceDisconnect, verified live); never retried. - Comment-based help crediting the contributor, tests, docs, changelog. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Removes notes by event ID (-NoteEventID) or every note on a session (-All) by adding a DeletedEvent (1) correlated to each note, as the web UI does; notes already deleted are skipped. Credentials connections only. Design and event mechanics from PR #27 by CitybookServicesLTD. Get-CWCSessionDetail -Group now takes nested group path parts ([string[]]), like the other session functions. The live smoke test's note cleanup uses the new function. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Builds the web client's sc-<instance>:// launch URL (format and encoding taken from SC.main.ts getSchemeUrlFunc) from the launch settings in Script.ashx and a Host access token, checks the client's protocol handler, opens it without exposing the URL, and logs the join (LogInitiatedJoin) as the web UI does. -UrlOnly returns the URL with a 5-minute delegated token when the role allows it. Credentials connections only. Also: Connect-CWC no longer blames the credentials for local failures; the module test's expected list gains Remove-CWCHostFromSession; live discovery script Tests/Live/Invoke-CWCHostLaunchDiscovery.ps1; WIP/ prototype removed. Verified live on PS 7 and 5.1 against a real server. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Regenerated docs and MAML help with the full function list; dropped a duplicate entry in the module test's expected-function list left by the rebase. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From the /simplify review of the release branch: - Private Add-CWCSessionEvent owns the AddSessionEvents envelope, skips empty batches and is never retried; the 8 event-queuing functions use it. Request bodies are unchanged. - -Group accepts nested group path parts ([string[]]) on every PageService function that takes it (the server's sessionGroupPathPartsOrName); a single name still binds. - Invoke-CWCWebRequest errors carry ErrorIds (CWC.NotConnected, CWC.AuthModeMismatch, CWC.Http<status>, CWC.NoResponse). Connect-CWC blames the credentials only when the server answered, instead of inferring it from Write-Error. The error text keeps the server's message and drops the ConnectWise Manage-shaped parsing (and its Disconnect-CWC hint). - One auth-mode message (Get-CWCAuthModeMessage) for the transport and the three functions that must check up front. - .psm1 tables for default session groups, ProcessType and SessionPermissions.All. - Enter-CWCSession: platform check before any request, -Name from the pipeline skips the session lookup, a failed delegated-token request isn't retried per pipeline item. - Invoke-CWCCommand polls with a growing delay (1-5 s) on the rate-limited GetSessionDetails. - Get-CWCLastContact reads elapsed time directly; ConvertFrom-CWCEventTime removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From the /simplify review: - Build/Update-Help.ps1 regenerates Docs/ and the MAML help, strips platyPS's -ProgressAction leak and fixes module-page links (was done by hand). Module tests fail if a function has no Docs page or -ProgressAction reappears. - The module test derives the expected functions from Public/*.ps1 and checks FunctionsToExport lists each exactly once (no hand-kept copy to drift). - .gitignore: secret patterns now match secret data files only, so the negation lines for source/tests/docs and the *-help.xml rule are gone; the guard test covers ConnectWiseControlAPI/, Tests/, Docs/, Build/, Examples/. - Live smoke test: requests events only from the rate-limited session details, one note filter instead of two copies, one TryLogin step helper. The live Pester suite limits its session query. - CHANGELOG entries for the user-visible changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- HTTP 500 with a SecurityException body (permission failure, including a wrong password at Connect-CWC) is no longer retried; it only delayed the error by 14 s. - Invoke-CWCCommand identifies its own QueuedCommand by its exact text and prefers the RanCommand whose CorrelationEventID points at it, so a command queued by someone else at the same time can't be returned as ours. - Enter-CWCSession stops trying delegated tokens only after a permission failure, not after any error. - Get-CWCSession defaults -Group to the built-in group for -Type (Support and Meeting queries used 'All Machines'). - Remove-CWCSessionNote help: only -All skips already-deleted notes. - Comment-based help for the 14 public functions this release touched that had none; docs regenerated. CLAUDE.md retry count corrected (3, not 5). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Connect-CWC connects when asked for a different server or auth method even without -Force; it used to keep the old connection with only a warning, so later commands (deletes included) went to the previous server. - HTTP 500 retries only for server faults (no errorType) and rate-limit or timeout errors; application exceptions fail the same way again. - Auth-mode errors name the outermost public command the user ran. - Invoke-CWCCommand stops if queueing the command fails, instead of reporting "queued" or polling until the timeout. - Enter-CWCSession takes SessionType from piped sessions, so piped Support and Meeting sessions use the right group and URL type. - Remove-CWCSessionNote prompts by default (ConfirmImpact High), as its help says. - New-CWCRemoteWorkforceAssignment: comment-based help, nested group paths. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Connect-CWC reuses a cached connection only for the same server, method and identity (user or API secret); a different user or rotated secret reconnects. A failed switch to another server/method/identity leaves the module disconnected instead of falling back to the old connection, so a script's next command can't hit the previous tenant. A failed -Force refresh of the same connection still keeps it. - Get-CWCLastContact counts only guest events (empty Host), so a technician leaving no longer reads as the machine going offline; requests Events only. - On PS 6+, a failed -Sensitive request's body (e.g. a new user's password) is stripped from the error record along with the auth headers. - Get-CWCAuditLog formats times with the invariant culture. - "Max retries hit" only when the retries actually ran out. - RemoveRedundantSessions example: never-connected sessions sort last, so they are never the copy kept. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Records EventID/CorrelationEventID so a live run shows whether RanCommand output points at its QueuedCommand, and checks a wrong password fails within 10 s, names the login causes and leaves the module disconnected. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Unloads any already-imported ConnectWiseControlAPI (e.g. the Gallery version) and keeps the imported module object, instead of Get-Module, which returned two modules and broke the module-scope steps. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Add-CWCSessionNote, Send-CWCSessionMessage and Send-CWCToolboxItem no longer
output the extension's empty {} response (the credentials path outputs
nothing; seen in the live smoke test).
- Help: the extension attributes notes, commands and toolbox runs to its
RESTfulUserName setting, which can be renamed; Send-CWCSessionMessage -From
defaults to 'RESTful API' and must be passed to match a renamed setting.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Connect-CWC -Credentials with -Mfa (prompts for the code; authenticator, email or SMS), -OneTimeCode or -TotpSecret (computes the authenticator code; the secret is not stored) signs in through AuthenticationService.TryLogin and uses the .ASPXAUTH cookie: no Basic auth, no stored password. - Cached MFA logins match on a salted hash of user and password and are re-checked with GetEligibleHosts; an expired one is never restored. - A replaced MFA login is logged out (best effort). - ErrorIds CWC.MfaRequired, CWC.MfaCodeRejected, CWC.LoginFailed, CWC.LoginThrottled; logins are never retried. - TOTP waits for a fresh step near the window end and never reuses a step for the same server and user. - Expired-login hint on permission/anti-forgery errors over MFA connections. - Failed requests no longer keep the Cookie header or cookie jar on $Error. - Smoke test: module-level MFA steps, optional TOTP and expired-login check; raw failed-login probes behind -MfaNegativeProbes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- -Mfa sends a JSON null code (a [string] parameter turned it into ""). - A login that succeeds but then fails validation is logged out. - The old MFA login is logged out before switching identity, so -ErrorAction Stop can't skip it; a -Force refresh or expired login of the same user is not logged out. - The cached-login check treats only server answers as expiry; a network failure keeps the login and reports the error. - No expired-login hint while Connect-CWC is logging in. - The TOTP step is recorded only once the server has seen the code; a bad Base32 secret fails before any request. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Live run (PS 7): -Mfa login, reads, note, cached reconnect all pass; the .ASPXAUTH cookie is persistent (1 year). The TOTP prompt got a value that was not a seed, so the error now names the kind of bad character (never the character itself for letters/digits), and the smoke test skips the TOTP follow-up steps when the TOTP login fails. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Creates a user with a New-CWCMFA seed and the given role, logs in with Connect-CWC -TotpSecret, checks the cached reconnect, the expired-login hint and the re-login (which must wait for a fresh code), then deletes the user. Replaces the prompt for an existing account's TOTP secret. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- ci.yml: Pester on PowerShell 7 and Windows PowerShell 5.1, PSScriptAnalyzer, Test-ModuleManifest and a docs-drift check, all via Tests/test-local.ps1 - pr-validation.yml, dependabot.yml, copilot-instructions.md, .vscode/ - AGENTS.md as the agent guide (CLAUDE.md imports it), style guide under .github/ - Remove AppVeyor runner and badge - PSSA: compatible-syntax targets 3.0/5.1/7.6; hashtable alignment option on the right rule No module code changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keeps the runner working through the CWSC rename and the move to source/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Move ConnectWiseControlAPI/ to source/ (Remote Workforce -> RemoteWorkforce); module-level setup and constants move from the .psm1 to source/prefix.ps1 - build.ps1/build.yaml/RequiredModules.psd1 (Sampler + ModuleBuilder) build output/<Name>/<version>/; tool versions pinned to match CI - Tests import $env:MODULE_TEST_PATH (built module) or source/; test-local.ps1 gains a Build stage, refuses stale builds, tests the build on PowerShell 7 and Windows PowerShell 5.1 - CI: build job -> artifact -> Pester on both editions - Source manifest exports '*'; the build writes the explicit list No behaviour change: the built module exports the same 32 functions, keeps PowerShell 3.0, and passes the same 456 tests on 7.6 and 5.1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ConnectWise renamed Control back to ScreenConnect. Help, messages, examples, doc pages and the Gallery description now say ScreenConnect. The module name, the CWC prefix and the CWC.* ErrorIds are unchanged. - Manifest: new description and tags, HelpInfoURI removed (it pointed at a help file that Update-Help cannot use) - New-CWCMFA: -DisplayName defaults to ScreenConnect; add help - README: upgrading-from-0.4 section listing the breaking changes - CHANGELOG: 0.5.0 heading with a breaking-changes block; correct the 0.3.x dates and links Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The module's first big update since 0.4.0.0, planned as 0.5.0. It adds MFA login and an API-secret login, new functions, fixes checked against the server source and a live server, a test suite, and GitHub Actions CI.
Merging this does not publish anything. The PowerShell Gallery release is a separate step.
Product name
ConnectWise renamed Control back to ScreenConnect. Help, messages, examples and the Gallery description now say ScreenConnect. The module name (
ConnectWiseControlAPI), theCWCcommand names and theCWC.*ErrorIds are unchanged, so existing scripts keep working.Breaking changes
Remove-CWCSession,Remove-CWCSessionNoteandRemove-CWCHostFromSessionask for confirmation by default. Unattended scripts must add-Confirm:$false; without it they fail and remove nothing.Connect-CWCwithout-Forcenow switches to a different server, sign-in method or user instead of keeping the old connection.Get-CWCLastContactreturns an error when it finds no connection event, instead of the current time.Get-CWCAuditLogcovers the last 24 hours unless-StartDateand-EndDateare passed.Added
Connect-CWC -Credentialswith-Mfaasks for the one-time code (authenticator app, email or SMS);-OneTimeCodetakes it as a parameter;-TotpSecretcomputes the authenticator code for unattended scripts and never stores the secret. The module signs in the way the web page does and uses the login cookie: no Basic auth, and the password isn't kept. A still-valid login is reused; an expired one is replaced on the nextConnect-CWC. Logins are never retried, and errors carry ErrorIds (CWC.MfaRequired,CWC.MfaCodeRejected,CWC.LoginFailed,CWC.LoginThrottled).Connect-CWC -ApiSecret: a second way to log in, using the RESTful API Manager extension's secret. It works on servers where every account requires MFA, for a subset of functions.Enter-CWCSession: opens the Host client joined to a session, like Join in the web UI (How can we launch the ScreenConnect Host application from the API? #13).-UrlOnlyreturns the launch URL.Remove-CWCSessionNote, based on added support for session notes #27's design.Remove-CWCHostFromSession(Added a function - Remove-CWCHostFromSession #28), changed to take single IDs and to prompt before acting.Find-CWCSessionandNew-CWCSession.Get-CWCRemoteWorkforceLaunchURL,Get-CWCRemoteWorkforceSessionandInitialize-CWCRemoteWorkforceSessionGroup.Fixed
-Debugand-Verboseprinted the Basic auth header, the anti-forgery token and new users' passwords. Failed requests also left auth headers and the login cookie on the error record kept in$Error.Connect-CWCcould leave commands going to the wrong server.Connect-CWCvalidation. It checks the login with a call any role can make, so accounts without ManageSessionGroups can connect (Screenconnect permissons #14).Update-CWCUsererasing the user's comment.Invoke-CWCCommandmatches its own command, so it can't return another command's output.CHANGELOG.md.Repository
Test-ModuleManifest, docs drift.source/(Sampler layout);./build.ps1builds the published module. The published module has the same 32 functions.HelpInfoURIremoved from the manifest; it pointed at a help file thatUpdate-Helpcannot use.Testing
cadd017), with writes: credentials, MFA and TOTP logins, note, message, command, wake, and session create/remove. The limited-role connect (Screenconnect permissons #14), the API-secret login and the toolbox item were not re-run on this commit; they were last verified live before the wording change.Issues
🤖 Generated with Claude Code