Skip to content

ConnectWiseControlAPI 0.5.0: MFA and API-secret login, ScreenConnect wording, fixes - #32

Merged
christaylorcodes merged 30 commits into
masterfrom
release/0.5.0
Nov 11, 2026
Merged

christaylorcodes merged 30 commits into
masterfrom
release/0.5.0

Conversation

@christaylorcodes

@christaylorcodes christaylorcodes commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

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), the CWC command names and the CWC.* ErrorIds are unchanged, so existing scripts keep working.

Breaking changes

  • Remove-CWCSession, Remove-CWCSessionNote and Remove-CWCHostFromSession ask for confirmation by default. Unattended scripts must add -Confirm:$false; without it they fail and remove nothing.
  • Connect-CWC without -Force now switches to a different server, sign-in method or user instead of keeping the old connection.
  • Get-CWCLastContact returns an error when it finds no connection event, instead of the current time.
  • Get-CWCAuditLog covers the last 24 hours unless -StartDate and -EndDate are passed.
  • HTTP 500 errors are retried only for calls that are safe to repeat.

Added

  • MFA login (Hosted instance requires MFA #12). Connect-CWC -Credentials with -Mfa asks for the one-time code (authenticator app, email or SMS); -OneTimeCode takes it as a parameter; -TotpSecret computes 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 next Connect-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). -UrlOnly returns 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-CWCSession and New-CWCSession.
  • Notes, messages and toolbox items work over a normal login as well as the API secret.
  • Remote Workforce: Get-CWCRemoteWorkforceLaunchURL, Get-CWCRemoteWorkforceSession and Initialize-CWCRemoteWorkforceSessionGroup.

Fixed

  • Cookies were never sent back to the server. This is the likely cause of the "Invalid anti-forgery token" errors in invoke-cwccommand error #22.
  • Credentials appeared in output. -Debug and -Verbose printed 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.
  • Repeated actions on server errors. HTTP 500 retries ran on commands, wakes, deletes and user creation, so one request could act twice.
  • Connect-CWC could leave commands going to the wrong server.
  • Connect-CWC validation. It checks the login with a call any role can make, so accounts without ManageSessionGroups can connect (Screenconnect permissons #14).
  • Server calls with the wrong arguments, checked against the server source: wake, audit log, Remote Workforce launch URL, and Update-CWCUser erasing the user's comment.
  • Invoke-CWCCommand matches its own command, so it can't return another command's output.
  • The full list is in CHANGELOG.md.

Repository

  • CI moved from AppVeyor to GitHub Actions: Pester on PowerShell 7 and Windows PowerShell 5.1, PSScriptAnalyzer, Test-ModuleManifest, docs drift.
  • Source moved to source/ (Sampler layout); ./build.ps1 builds the published module. The published module has the same 32 functions.
  • HelpInfoURI removed from the manifest; it pointed at a help file that Update-Help cannot use.

Testing

  • 456 Pester tests pass on both PowerShell 7 and Windows PowerShell 5.1 (25 live tests skip without a server). All HTTP calls are mocked.
  • A build from a fresh clone was published to a temporary local repository and the saved package was imported on both editions: 32 functions, no import warnings, help present for every function.
  • The live smoke test passed on both editions on the final commit (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

christaylorcodes and others added 25 commits November 10, 2026 09:25
.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>
@christaylorcodes christaylorcodes changed the title Release 0.5.0: API secret login, Enter-CWCSession, security and reliability fixes Release 0.5.0: MFA and API-secret login, Enter-CWCSession, security and reliability fixes Nov 10, 2026
christaylorcodes and others added 4 commits November 10, 2026 12:06
- 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>
@christaylorcodes christaylorcodes changed the title Release 0.5.0: MFA and API-secret login, Enter-CWCSession, security and reliability fixes ConnectWiseControlAPI 0.5.0: MFA and API-secret login, ScreenConnect wording, fixes Nov 11, 2026
@christaylorcodes
christaylorcodes merged commit fe534aa into master Nov 11, 2026
11 checks passed
@christaylorcodes
christaylorcodes deleted the release/0.5.0 branch November 12, 2026 21:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant