Secure PowerShell Remoting with WinRM HTTPS and JEA
Validate PKI, expose source-restricted WinRM HTTPS, build a parameter-constrained JEA role, test every denied path, protect transcripts, and rehearse renewal and rollback.
Provide one auditable remote maintenance task without granting a full administrator PowerShell session or weakening transport trust.
- Windows Server 2025
- PowerShell 7.6 current
- Windows Remote Management Windows Server 2025
- Domain and management path Reliable DNS/time/domain authentication, hardened management subnet and independent out-of-band or known-good recovery path.
Resolve-DnsName {{serverFqdn}}; Test-ComputerSecureChannel - Enterprise PKI certificate LocalMachine certificate with exact SAN, Server Authentication EKU, trusted chain/revocation, protected private key and renewal owner.
Test-Certificate -Cert (Get-Item Cert:\LocalMachine\My\{{certificateThumbprint}}) -Policy SSL -DNSName {{serverFqdn}} - Reviewed operator groups Dedicated domain group for the bounded task, current membership review and no unsafe nested JEA role overlap.
- Protected evidence storage Transcript/event capacity, restrictive ACLs, retention/privacy and tamper-resistant forwarding are configured.
- Maintenance and negative-test window WinRM restart dependencies are drained and authorized/unmapped/outside-source test identities are available.
OneLiners never runs these steps or stores secrets. Review placeholders, versions, current state, and change-control requirements before using a command.
Full guide
What you will build
- A Windows Server 2025 WinRM HTTPS listener on TCP/5986 using a private-key certificate whose SAN matches the server FQDN, whose Server Authentication EKU and chain are valid, and whose private key ACL, renewal owner and revocation behavior are verified without exposing certificate material.
- A network boundary that allows HTTPS remoting only from approved management subnets, keeps `AllowUnencrypted` and Basic authentication disabled, uses Kerberos or certificate-based enterprise authentication as designed, and never relies on `TrustedHosts='*'` or certificate-validation bypass.
- A Just Enough Administration endpoint with a RestrictedRemoteServer session, a versioned role-capability module, exact command and parameter constraints, group-based role mapping, virtual account, protected transcripts and an endpoint ACL that exposes only the intended maintenance task.
- A positive/negative test and investigation workflow covering certificate identity, TLS/listener/firewall, authentication, endpoint registration, role mapping, command visibility, parameter restrictions, transcript/audit evidence, service restarts, certificate renewal and rollback.
- `Test-WSMan -UseSSL` and a current PowerShell client connect to the server by its certificate-matching FQDN from an approved management subnet with full certificate validation and no Basic/unencrypted fallback.
- The JEA operator can inspect and restart only the approved Print Spooler service in the tutorial fixture. Attempts to invoke arbitrary commands, other services, providers, scripts, native executables or unrestricted parameters fail.
- The endpoint permission and RoleDefinitions map only reviewed domain groups. JEA runs the allowed command under a virtual account, transcripts are protected and centralized evidence identifies the connecting user and commands.
- Registration, certificate replacement and rollback are planned maintenance operations because endpoint changes can restart WinRM and interrupt remoting. A tested out-of-band or separate known-good management path remains available.
Architecture
How the parts fit together
The management client resolves the server FQDN, validates the HTTPS listener certificate and connects to TCP/5986 through a source-restricted Windows Firewall rule. WinRM authenticates the caller using the domain design and encrypts the transport; Basic and unencrypted service/client settings remain disabled, and no wildcard TrustedHosts trust is introduced. The caller names a registered PowerShell session configuration. Its endpoint ACL controls who can enter, RoleDefinitions maps domain groups to a narrowly authored `.psrc` role capability, and RestrictedRemoteServer uses NoLanguage with no providers or executables by default. A virtual account performs the permitted local action without disclosing a reusable privileged credential. PowerShell/JEA transcripts and Windows event logs are written to protected storage and forwarded. Certificate, firewall, listener, endpoint and role artifacts are versioned and rotated through a canary maintenance path.
- Define the remote task, caller groups, source networks, certificate lifecycle, command/parameter allowlist, evidence and break-glass design.
- Capture current WinRM listeners, service/client authentication, firewall, endpoints, session ACLs, logs and dependencies.
- Enroll and validate a certificate by FQDN, SAN, EKU, chain, revocation, private key and renewal ownership.
- Create the HTTPS listener and source-restricted firewall rule while keeping Basic and unencrypted communication disabled.
- Author and syntax-test the role capability and RestrictedRemoteServer session configuration offline.
- Register the endpoint in a maintenance window, verify ACL/role mapping and test permitted/forbidden commands through HTTPS.
- Protect/forward transcripts and event evidence, monitor certificate/listener/endpoint drift and rehearse previous-artifact rollback.
Assumptions
- The target is a domain-joined Windows Server 2025 host with current security updates, PowerShell remoting/WinRM available, reliable DNS/time and a separately tested console or management path.
- An enterprise PKI issues a nonexportable or appropriately protected machine certificate with the exact server FQDN in SAN, Server Authentication EKU, trusted chain, revocation availability and automated renewal ownership.
- The client uses a current supported PowerShell release and resolves/connects by FQDN; connecting by IP is outside this Kerberos/certificate identity design.
- Only approved management subnets can reach TCP/5986, and the network team confirms asymmetric routing, proxies and TLS interception do not invalidate server identity.
- The fixture role is intentionally narrow: members of a domain group may view and restart only the Print Spooler service. Broader server administration requires separate roles/endpoints and review.
- Transcripts and event logs have restricted ACLs, capacity/retention, tamper-resistant forwarding and privacy approval; they may contain command arguments and operational data.
Key concepts
- WinRM listener
- The WS-Management network endpoint configured by transport, address and certificate; it is distinct from a PowerShell session configuration.
- HTTPS server identity
- The client validates certificate trust, lifetime, revocation, EKU and FQDN/SAN before authenticating the remote management service.
- JEA endpoint ACL
- Controls who may connect to the registered endpoint; role mapping separately controls which capabilities they receive.
- Role capability
- A `.psrc` data file in a PowerShell module that exposes specific cmdlets, functions, providers and external commands.
- RestrictedRemoteServer
- A JEA session type with NoLanguage and a minimal default command surface; additional capabilities must be explicitly exposed.
- Virtual account
- A temporary local identity used by JEA to perform permitted actions without sharing a reusable privileged credential with the caller.
Before you copy
Values used in this guide
{{serverFqdn}}Server DNS name present in the listener certificate SAN.
Example: print01.corp.example{{certificateThumbprint}}Validated LocalMachine\My listener certificate thumbprint.
Example: 8A2F9B77D8E158D41EECFC89A8E0D9FE72263701{{managementSubnet}}Approved source prefix for WinRM HTTPS.
Example: 10.20.30.0/24{{endpointName}}Versioned JEA endpoint registration name.
Example: OneLiners.PrintOperator.v1{{operatorGroup}}Domain group mapped to the narrow role.
Example: CORP\GG-JEA-PrintOperators{{roleModulePath}}AllUsers PowerShell module root containing RoleCapabilities.
Example: C:\Program Files\PowerShell\Modules\OneLinersJEA\1.0.0{{transcriptPath}}Protected local transcript staging directory.
Example: D:\JEA\Transcripts\PrintOperatorSecurity and production boundaries
- HTTPS does not make an overprivileged endpoint safe. Network reachability, authentication, endpoint ACL, role mapping, command/parameter constraints and OS authorization are separate controls.
- Keep WinRM service/client `AllowUnencrypted=false` and Basic authentication disabled. Never solve workgroup or name-resolution problems with `TrustedHosts='*'` or a certificate-validation bypass.
- Visible cmdlets can expose unsafe alternate parameters, script blocks or object inputs. Restrict parameters and test command composition, aliases, help, formatting and error paths.
- A JEA virtual account can be locally privileged. The endpoint must expose only operations whose full transitive behavior is understood, including modules, scripts and external programs they invoke.
- Transcripts are important but not complete tamper-proof forensic evidence. Protect and forward them with PowerShell Operational, WinRM Operational and security events.
- Registering, unregistering or changing a session configuration can restart WinRM and interrupt active remoting/DSC operations. Use a maintenance window and separate recovery path.
Stop before continuing if
- Stop if DNS/FQDN, time, certificate SAN/EKU/chain/revocation/private key or renewal ownership is invalid or unknown.
- Do not create a listener with a self-signed production certificate, Basic authentication, unencrypted traffic, certificate validation bypass or wildcard TrustedHosts.
- Stop if TCP/5986 cannot be restricted to approved sources or another service/listener already conflicts.
- Do not register a JEA endpoint whose role exposes wildcard cmdlets, arbitrary scripts/native executables, providers, unrestricted service names or language features.
- Stop when endpoint ACL and RoleDefinitions differ, an unmapped principal can connect, transcripts are writable by operators, or the recovery path depends on the endpoint being changed.
- Do not remove or disable an existing management listener until every dependency and rollback test passes.
instruction
Define the remote task, identities, network, and evidence boundary
Specify the one allowed task, operator and eligibility groups, target servers, source subnets, authentication path, certificate lifecycle, exact cmdlet parameters, virtual-account rights, transcripts, maintenance interruption and out-of-band rollback.
Why this step matters
JEA begins with a task, not with a list of familiar administrative cmdlets. Cmdlets often expose alternate parameter sets or object pipelines that reach far beyond the intended operation. The contract states the exact service, actions, identities, network origins, evidence and recovery path. It separates transport trust from authorization: HTTPS validates the server and protects transport, WinRM authenticates the caller, endpoint ACL admits a group, RoleDefinitions selects a capability, and the capability constrains commands. A virtual account may hold local administrative power, so only the narrow operation can be surfaced. Maintenance impact matters because endpoint registration can restart WinRM and terminate active sessions.
What to understand
Name the exact service and read/restart actions; exclude arbitrary service administration.
Use domain security groups for operators and separate endpoint eligibility if required.
Define canonical FQDN, source networks, port and certificate issuer/renewal.
List every permitted cmdlet/parameter and forbidden composition path.
Define transcript/event retention, alerting and a recovery path independent of this endpoint.
System changes
- Creates the reviewed remoting/JEA design; no host changes.
Syntax explained
virtual account- Temporary run-as identity whose local rights do not grant the caller a reusable credential.
RestrictedRemoteServer- Starts with NoLanguage and minimal commands instead of a full PowerShell session.
Get-Content .\security\jea-print-operator-contract.json | ConvertFrom-Json | Format-ListTask : inspect/restart Print Spooler only Operators : CORP\GG-JEA-PrintOperators Targets : print servers Transport : WinRM HTTPS / 5986 / canonical FQDN Authentication : Kerberos domain identity RunAs : VirtualAccount Providers : none ExternalCommands : none Rollback : console + previous endpoint artifacts
Checkpoint: Every exposed operation is finite and testable
Test-Path .\security\jea-print-operator-contract.json; Get-FileHash .\security\jea-print-operator-contract.jsonContinue whenApproved task, groups, FQDN/subnet/certificate, command parameters, logging, interruption plan and independent rollback.
Stop whenThe role says general administration, needs arbitrary scripts/commands, lacks source restriction, or rollback uses the endpoint being modified.
If this step fails
Operators ask for Invoke-Command or arbitrary PowerShell.
Likely causeThe task has not been decomposed into bounded operations.
Inventory real maintenance cases and required object changes.
ResolutionCreate separate narrow capabilities or a purpose-built service.
The task needs a reusable domain credential on the server.
Likely causeThe run-as design is overprivileged or crosses remote resource boundaries.
Model local versus network resource access and identity delegation.
ResolutionUse a reviewed gMSA/resource design or keep the task local; never embed credentials.
Security notes
- Do not place secrets in the design, commands or transcripts.
Alternatives
- Use a signed scheduled action invoked through a narrow API when PowerShell authorization remains too broad.
Stop conditions
- The role says general administration, needs arbitrary scripts/commands, lacks source restriction, or rollback uses the endpoint being modified.
verification
Capture WinRM, firewall, endpoint, and dependency baseline
Record OS/PowerShell versions, WinRM service/listeners, client/service authentication and encryption settings, firewall rules, registered session configurations, endpoint permissions, active sessions and recent WinRM/PowerShell errors before making changes.
Why this step matters
Windows Server commonly has PowerShell remoting enabled, so creating a new listener or running broad quick configuration can alter existing firewall, service and endpoint behavior. Inventory current listeners by transport/address/hostname/thumbprint, service and client authentication settings, TrustedHosts, firewall source scope, registered endpoints and integrations such as DSC or monitoring. Preserve endpoint permissions and artifact hashes for rollback. `AllowUnencrypted=false` and Basic disabled are gates. Existing HTTP with Kerberos is not identical to unencrypted remoting because WinRM protects message traffic after authentication, but this tutorial builds a dedicated HTTPS path and does not remove existing management until dependencies are migrated.
What to understand
Record OS and both Windows PowerShell/PowerShell versions used by endpoint and client.
List listener keys, ports, hostnames and certificate thumbprints.
Capture service/client Auth, AllowUnencrypted and TrustedHosts values.
Map firewall profiles/source addresses and every registered endpoint permission.
Identify DSC, monitoring and automation sessions that a WinRM restart would interrupt.
System changes
- None; creates protected pre-change configuration and dependency evidence.
Syntax explained
WSMan provider- Exposes effective WinRM client/service/listener settings for precise inspection.
Permission- Human-readable endpoint ACL summary; retain full configuration evidence as well.
$PSVersionTable; Get-Service WinRM; Get-ChildItem WSMan:\localhost\Listener; Get-Item WSMan:\localhost\Service\AllowUnencrypted,WSMan:\localhost\Service\Auth\Basic; Get-PSSessionConfiguration | Select Name,PermissionOS : Windows Server 2025 Datacenter PowerShell : 7.6.0 WinRM : Running / Automatic HTTP listener : 5985 HTTPS listener : none AllowUnencrypted : false Service Basic : false Default endpoint : Microsoft.PowerShell Active dependencies: 2 management integrations
Checkpoint: Existing management dependencies and secure defaults are known
Get-Item WSMan:\localhost\Service\AllowUnencrypted,WSMan:\localhost\Service\Auth\Basic; Get-NetTCPConnection -State Listen -LocalPort 5985,5986 -ErrorAction SilentlyContinueContinue whenAllowUnencrypted false, Basic false, complete listener/firewall/endpoint inventory, dependency owners and preserved prior artifacts.
Stop whenBasic or unencrypted is enabled, wildcard TrustedHosts exists, listener ownership is unknown, or WinRM restart/recovery impact is unowned.
If this step fails
WSMan provider is unavailable in pwsh.
Likely causeWSMan components/module compatibility differs on the management host.
Run the supported Windows PowerShell/WinRM tools locally and record versions.
ResolutionUse the supported host for configuration and current PowerShell for client tests.
An undocumented HTTPS listener exists.
Likely causePrior automation or stale configuration owns TCP/5986.
Inspect listener hostname/thumbprint, certificate and firewall/dependencies.
ResolutionResolve ownership and migrate/remove only through a separate reviewed change.
Security notes
- Do not print credential objects or certificate private-key material.
Alternatives
- Collect equivalent baseline through signed configuration-management inventory with exact effective values.
Stop conditions
- Basic or unencrypted is enabled, wildcard TrustedHosts exists, listener ownership is unknown, or WinRM restart/recovery impact is unowned.
verification
Validate the WinRM HTTPS certificate and renewal path
Select the LocalMachine personal-store certificate by recorded thumbprint, then verify SAN contains the canonical FQDN, Server Authentication EKU, validity, trusted chain, revocation, private key presence/ACL and renewal ownership. Never choose a certificate only by subject text.
Why this step matters
HTTPS security depends on the client validating the exact server name and a trusted certificate. Subject display text alone is insufficient; modern identity is carried in SAN. The certificate must be valid now, include Server Authentication EKU, chain to a trusted issuer, pass revocation policy and have a private key usable by the service. The thumbprint binds the listener to one exact certificate, but it changes on renewal, so monitoring and rebinding automation must be designed before deployment. Selecting newest by expiration without validating SAN/EKU/issuer can bind an unrelated certificate. Private key ACL and exportability follow PKI policy and are never displayed or copied into scripts.
What to understand
Resolve and use the canonical FQDN clients will request.
Retrieve one exact thumbprint from LocalMachine\My.
Validate SAN, EKU, time, chain and revocation for SSL server policy.
Confirm private key availability and least-privilege ACL without exporting it.
Define renewal threshold, new-cert validation, listener rebind and old-cert retirement.
System changes
- None; validates the already-enrolled machine certificate.
Syntax explained
-Policy SSL -DNSName- Tests certificate trust and suitability for the requested TLS server name.
Thumbprint- Exact certificate identity used by the WinRM listener; renewal produces a new value.
Values stay on this page and are never sent or saved.
$cert=Get-Item Cert:\LocalMachine\My\{{certificateThumbprint}}; $cert | Select Subject,DnsNameList,NotBefore,NotAfter,Thumbprint,HasPrivateKey,EnhancedKeyUsageList; Test-Certificate -Cert $cert -Policy SSL -DNSName {{serverFqdn}}Subject : CN=print01.corp.example
DnsNameList : {print01.corp.example}
NotBefore : 7/01/2026 00:00:00
NotAfter : 7/01/2027 00:00:00
Thumbprint : 8A2F9B77D8E158D41EECFC89A8E0D9FE72263701
HasPrivateKey : True
EKU : Server Authentication (1.3.6.1.5.5.7.3.1)
Test-Certificate : TrueCheckpoint: Server identity and lifecycle are valid before listener creation
Test-Certificate -Cert (Get-Item Cert:\LocalMachine\My\{{certificateThumbprint}}) -Policy SSL -DNSName {{serverFqdn}}Continue whenTrue validation, exact SAN/EKU, trusted current chain/revocation, protected private key and tested renewal/rebind owner.
Stop whenName/EKU/chain/revocation/time/private key fails, certificate is self-signed for production, or renewal/rebind is undefined.
If this step fails
Test-Certificate fails revocation.
Likely causeCRL/OCSP is unreachable, stale or certificate status is invalid.
Inspect chain status and PKI publication from the server/client network.
ResolutionRepair PKI reachability/status or reissue; never disable revocation checking.
Certificate has no private key.
Likely causeOnly the public certificate was imported or enrollment occurred elsewhere.
Inspect enrollment history and certificate provider/key association.
ResolutionEnroll correctly on the server through enterprise PKI; do not transfer an unprotected key.
Security notes
- Never output or export the private key/password in this workflow.
- Do not add client validation bypass to compensate for PKI errors.
Alternatives
- Use a supported enterprise certificate autoenrollment template with monitored automatic renewal/rebinding.
Stop conditions
- Name/EKU/chain/revocation/time/private key fails, certificate is self-signed for production, or renewal/rebind is undefined.
config
Create the HTTPS listener bound to the validated certificate
Create one WinRM listener for HTTPS, Address `*`, canonical HostName and the exact validated certificate thumbprint. Re-read effective listener configuration and TCP state; do not run broad quick-config commands that rewrite unrelated settings.
Why this step matters
The listener is the network transport endpoint, not the JEA authorization endpoint. Bind it to the previously validated thumbprint and canonical hostname so the client can authenticate the server. Address `*` means all local addresses, which is acceptable only when Windows Firewall and upstream controls restrict approved sources; use a more specific address design if multi-homed exposure requires it. `-Force` replaces a conflicting listener and therefore must only be used after the baseline proved ownership and backup. Verify effective WSMan configuration and HTTP.sys listening state immediately. Do not remove the prior listener or broaden authentication during this step.
What to understand
Ensure no conflicting HTTPS listener or TCP/5986 service exists.
Use exact FQDN and thumbprint values from validated artifacts.
Create only the HTTPS listener rather than running global quick configuration.
Verify effective hostname/thumbprint/port and service listening state.
Capture the listener configuration change and previous artifacts.
System changes
- Creates or replaces the host's WinRM HTTPS listener on TCP/5986.
Syntax explained
Transport HTTPS- Configures TLS-protected WS-Management listener on the standard port 5986.
Address *- Listens on host addresses; firewall/source scope remains mandatory.
CertificateThumbPrint- Binds the listener to one exact validated machine certificate.
Values stay on this page and are never sent or saved.
New-Item -Path WSMan:\localhost\Listener -Transport HTTPS -Address * -HostName {{serverFqdn}} -CertificateThumbPrint {{certificateThumbprint}} -Force; Get-ChildItem WSMan:\localhost\Listener | Format-List Keys,CertificateThumbprint,Port,EnabledKeys : {Transport=HTTPS, Address=*}
Address : *
Transport : HTTPS
Port : 5986
Hostname : print01.corp.example
CertificateThumbprint : 8A2F9B77D8E158D41EECFC89A8E0D9FE72263701
Enabled : trueCheckpoint: The listener exposes the expected TLS identity on 5986
Get-ChildItem WSMan:\localhost\Listener | Where-Object { $_.Keys -contains 'Transport=HTTPS' }; Get-NetTCPConnection -State Listen -LocalPort 5986Continue whenOne owned HTTPS listener with exact hostname/thumbprint and a WinRM-owned listening socket.
Stop whenA listener is overwritten unexpectedly, thumbprint/hostname differs, port is owned by another service, or private key access fails.
If this step fails
Listener creation says certificate is inappropriate.
Likely causeSAN/EKU/private key/store/validity requirements are not met.
Repeat exact certificate validation and inspect WinRM event detail.
ResolutionEnroll a suitable certificate; do not use a self-signed or invalid fallback.
5986 is not listening.
Likely causeWinRM service, listener or private-key access failed.
Inspect WinRM service/config and Operational log.
ResolutionRestore prior listener artifact if needed and correct the exact service/key issue.
Security notes
- A listener on all addresses requires strict host and upstream firewall scope.
Alternatives
- Bind through centrally managed WinRM policy when the organization owns listener lifecycle in GPO and can test certificate selection.
Stop conditions
- A listener is overwritten unexpectedly, thumbprint/hostname differs, port is owned by another service, or private key access fails.
config
Restrict TCP/5986 and enforce secure WinRM authentication settings
Create a dedicated Domain-profile inbound firewall rule limited to the approved management subnet. Explicitly keep service/client unencrypted traffic and Basic authentication disabled, and verify wildcard TrustedHosts is absent.
Why this step matters
TLS and authentication do not justify internet- or LAN-wide management reachability. Limit TCP/5986 to specific hardened management networks at the host and upstream boundary. Domain profile avoids accidental exposure when the network category changes, but alert if the server leaves the expected profile. `AllowUnencrypted=false` and Basic disabled on both required sides prevent fallback to weak patterns; passwords and credentials are never supplied in command arguments. TrustedHosts changes client trust behavior and wildcard use can permit authentication attempts to unverified hosts, so keep it empty in this domain/FQDN design. Existing 5985 rules are migrated only after dependency review, not deleted automatically.
What to understand
Create a uniquely owned firewall rule for TCP/5986 and exact remote prefix.
Validate current network profile and upstream ACL/routing.
Keep service/client AllowUnencrypted false and Basic disabled.
Verify TrustedHosts is empty or contains only separately approved legacy entries—never wildcard.
Test allowed and disallowed source addresses before changing existing listener access.
System changes
- Adds a source-restricted firewall rule and enforces secure WinRM authentication/encryption settings.
Syntax explained
RemoteAddress- Restricts network reachability to the approved management source prefix.
Profile Domain- Applies the rule only while Windows identifies the domain network profile.
AllowUnencrypted false- Refuses unencrypted WinRM traffic; no fallback is allowed.
Values stay on this page and are never sent or saved.
New-NetFirewallRule -DisplayName 'OneLiners WinRM HTTPS from management' -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5986 -RemoteAddress {{managementSubnet}} -Profile Domain; Set-Item WSMan:\localhost\Service\AllowUnencrypted -Value $false; Set-Item WSMan:\localhost\Service\Auth\Basic -Value $falseDisplayName : OneLiners WinRM HTTPS from management Enabled : True Profile : Domain Direction : Inbound Action : Allow RemoteAddress : 10.20.30.0/24 LocalPort : 5986 AllowUnencrypted : false Service Basic : false TrustedHosts : (empty)
Checkpoint: Only approved sources can reach secure WinRM
Get-NetFirewallRule -DisplayName 'OneLiners WinRM HTTPS from management' | Get-NetFirewallAddressFilter; Get-Item WSMan:\localhost\Service\AllowUnencrypted,WSMan:\localhost\Service\Auth\Basic,WSMan:\localhost\Client\TrustedHostsContinue whenExact source prefix/Domain profile, allowed-source connectivity, denied outside source, AllowUnencrypted/Basic false and no wildcard trust.
Stop whenRule uses Any source/profile, expected domain profile is absent, Basic/unencrypted is enabled, or wildcard TrustedHosts appears.
If this step fails
Allowed management host cannot connect.
Likely causeSource NAT/prefix, profile, routing or upstream ACL differs.
Observe actual source IP and each firewall hop without broadening scope.
ResolutionCorrect the specific prefix/path and retest from allowed and denied hosts.
An outside host can reach 5986.
Likely causeAnother broader firewall rule or upstream exposure allows it.
Enumerate effective firewall rules and test network ACLs.
ResolutionDisable conflicting broad exposure before endpoint registration.
Security notes
- Never solve connectivity by using Any/0.0.0.0 or disabling the firewall.
- Do not set TrustedHosts to `*`.
Alternatives
- Use an authenticated management VPN or jump network as an additional boundary, still retaining host source restriction.
Stop conditions
- Rule uses Any source/profile, expected domain profile is absent, Basic/unencrypted is enabled, or wildcard TrustedHosts appears.
config
Author a parameter-constrained JEA role capability
Create a versioned AllUsers PowerShell module with a `RoleCapabilities` directory and a `PrintOperator.psrc` file. Expose only `Get-Service` and `Restart-Service` with `Name` constrained to `Spooler`; expose no providers, scripts, external commands or language.
Why this step matters
The role capability is the authorization core. Exposing `Get-Service` or `Restart-Service` without parameter restrictions gives the operator access to every service and can become system administration through vulnerable service configurations. Restrict the `Name` parameter to one exact service and expose only `Force` where the operational contract needs it. Omitting providers, external commands and functions prevents filesystem/registry browsing or launching arbitrary binaries. A versioned module and manifest make discovery deterministic and changes reviewable. Inspect every available parameter set and test aliases/pipeline input; a cmdlet object parameter not listed should remain unavailable. The role file is privileged code even though it is a data file.
What to understand
Install under an AllUsers module path recognized by the endpoint's PowerShell runtime.
Use a versioned module and unique role-capability filename.
Restrict every visible cmdlet to exact parameter names and ValidateSet values.
Expose no providers, external commands, scripts, aliases or wildcard cmdlets.
Protect module files from operator writes and hash/sign them in deployment evidence.
System changes
- Installs a versioned JEA role capability module on the target server.
Syntax explained
VisibleCmdlets- Enumerates cmdlets exposed in the JEA session; parameter constraints narrow each surface.
ValidateSet = Spooler- Allows only the exact Print Spooler service name for the named parameter.
VisibleProviders = @()- Keeps filesystem, registry and other PowerShell providers unavailable.
C:\Program Files\PowerShell\Modules\OneLinersJEA\1.0.0\RoleCapabilities\PrintOperator.psrc@{
GUID = 'd70945bb-e719-4f48-b2a4-53e6b9cdab2e'
Author = 'OneLiners Operations'
Description = 'Inspect and restart only the Print Spooler service.'
VisibleCmdlets = @(
@{
Name = 'Get-Service'
Parameters = @{ Name = 'Name'; ValidateSet = 'Spooler' }
},
@{
Name = 'Restart-Service'
Parameters = @(
@{ Name = 'Name'; ValidateSet = 'Spooler' },
@{ Name = 'Force' }
)
}
)
VisibleFunctions = @()
VisibleExternalCommands = @()
VisibleProviders = @()
}Values stay on this page and are never sent or saved.
New-Item -ItemType Directory -Path '{{roleModulePath}}\RoleCapabilities' -Force | Out-Null; Copy-Item .\PrintOperator.psrc '{{roleModulePath}}\RoleCapabilities\PrintOperator.psrc'; Test-ModuleManifest '{{roleModulePath}}\OneLinersJEA.psd1'Module path : C:\Program Files\PowerShell\Modules\OneLinersJEA\1.0.0 Role capability : PrintOperator Visible cmdlets : Get-Service, Restart-Service Allowed service Name : Spooler Visible providers : none External commands : none Module manifest : valid
Checkpoint: The role cannot express general service or host administration
Get-Content '{{roleModulePath}}\RoleCapabilities\PrintOperator.psrc'; Get-FileHash '{{roleModulePath}}\RoleCapabilities\PrintOperator.psrc'Continue whenExact cmdlets/parameters/service, no wildcard/provider/executable/script surface, protected ACL and recorded hash.
Stop whenAny command or parameter is wildcarded, InputObject/script paths are available, module is operator-writable, or runtime cannot discover the role.
If this step fails
Role capability is not discovered.
Likely causeModule path, manifest, version or RoleCapabilities directory naming is wrong.
Check endpoint runtime PSModulePath and module discovery as SYSTEM/endpoint identity.
ResolutionInstall the versioned module in the correct AllUsers path and retest.
Restart-Service accepts another service.
Likely causeParameter restriction is malformed or another capability exposes a broader cmdlet.
Run Get-PSSessionCapability and negative tests for every mapped role.
ResolutionRemove endpoint from service, correct all role mappings and re-register.
Security notes
- Role capability files must be writable only by trusted deployment administrators.
- Do not expose command parameters that accept ScriptBlock, Path, InputObject or arbitrary names.
Alternatives
- Expose a reviewed no-argument proxy function when cmdlet parameter constraints cannot express the task safely.
Stop conditions
- Any command or parameter is wildcarded, InputObject/script paths are available, module is operator-writable, or runtime cannot discover the role.
config
Author a RestrictedRemoteServer session configuration
Create a versioned `.pssc` mapping only the operator group to `PrintOperator`, using a virtual account and protected transcript directory. Test its syntax before registration and preserve the exact file/hash for rollback.
Why this step matters
The `.pssc` connects authentication to capabilities. RestrictedRemoteServer provides NoLanguage and a minimal default command set; do not switch to Default merely to make a command work. RoleDefinitions should contain domain groups, not individual users or broad administrators. A virtual account lets approved commands obtain local rights without exposing credentials. It should not be granted arbitrary network access; remote resources need a separate reviewed identity design. The transcript directory must exist, have capacity and deny operator modification. Syntax testing catches structural errors but not role discovery or authorization flaws, so later capability tests remain mandatory. Keep the source file and hash even though registration stores the effective endpoint independently.
What to understand
Create the transcript directory on protected capacity and set strict ACLs.
Use RestrictedRemoteServer and RunAsVirtualAccount.
Map only one reviewed domain group to one narrow capability.
Avoid VisibleCmdlets in the PSSC that would apply to every role.
Syntax-test, hash and archive the PSSC with the role module revision.
System changes
- Creates protected transcript storage and stages a session configuration file; endpoint is not registered yet.
Syntax explained
SessionType RestrictedRemoteServer- Uses the minimal JEA command surface and NoLanguage mode.
RunAsVirtualAccount- Executes permitted local operations with a temporary virtual identity.
RoleDefinitions- Maps authenticated groups to named role capabilities.
C:\ProgramData\JEA\OneLiners.PrintOperator.v1.pssc@{
SchemaVersion = '2.0.0.0'
GUID = '3ca5c423-1581-4b35-9834-6d74a394d30b'
Author = 'OneLiners Operations'
SessionType = 'RestrictedRemoteServer'
RunAsVirtualAccount = $true
TranscriptDirectory = 'D:\JEA\Transcripts\PrintOperator'
RoleDefinitions = @{
'CORP\GG-JEA-PrintOperators' = @{
RoleCapabilities = 'PrintOperator'
}
}
}Values stay on this page and are never sent or saved.
New-Item -ItemType Directory -Path {{transcriptPath}} -Force | Out-Null; Test-PSSessionConfigurationFile -Path .\{{endpointName}}.pssc; Get-FileHash .\{{endpointName}}.psscTranscript directory : D:\JEA\Transcripts\PrintOperator SessionType : RestrictedRemoteServer RunAsVirtualAccount : True Role definition : CORP\GG-JEA-PrintOperators -> PrintOperator Syntax valid : True Configuration hash : SHA256 8B052D44...
Checkpoint: The session maps exactly one group to one narrow role
Test-PSSessionConfigurationFile -Path .\{{endpointName}}.pssc; Get-Acl {{transcriptPath}} | Format-ListContinue whenValid RestrictedRemoteServer PSSC, exact group/role, virtual account, protected transcript capacity and archived hash.
Stop whenPSSC uses Default session type, broad groups, operator-writable transcripts, shared credentials or unreviewed global commands.
If this step fails
Test-PSSessionConfigurationFile returns False.
Likely causePowerShell data syntax, schema or property value is invalid.
Parse the exact staged file on the target PowerShell runtime.
ResolutionCorrect offline; do not register with Force until validation is true.
Transcripts can be modified by operators.
Likely causeDirectory ACL inherits broad write access.
Inspect effective ACL and owner on parent and directory.
ResolutionMove to protected storage and grant service/admin write/read per policy only.
Security notes
- Never store passwords or credential objects in PSSC.
- A virtual account's effective rights make command constraints critical.
Alternatives
- Use a gMSA only when the permitted task must access remote resources and its rights are separately minimized.
Stop conditions
- PSSC uses Default session type, broad groups, operator-writable transcripts, shared credentials or unreviewed global commands.
verification
Preflight role discovery, endpoint ACL, and negative cases
Before registration, verify module discovery under the endpoint runtime, role syntax, operator and administrator group membership, transcript ACL/capacity, no overlapping role grants, and a test matrix for every allowed and forbidden command/parameter.
Why this step matters
Syntax-valid artifacts can still map the wrong people or combine capabilities unexpectedly. JEA unions role capabilities when a user belongs to multiple mapped groups, so nested membership can broaden the effective command surface. Enumerate effective members and overlapping role assignments, not only the group named in the file. Verify module discovery from the exact PowerShell runtime that will host the endpoint. Design negative tests before registration: another service, unrestricted Get-ChildItem, native executable, script block, provider path, alias and parameter not listed. Confirm transcript capacity and log forwarding. The endpoint ACL generated at registration should admit mapped groups, but its actual result must be audited afterward.
What to understand
Verify exact runtime sees one intended module version and role capability.
Expand nested operator memberships and detect other endpoint-role group overlap.
Confirm no account is mapped without an approved role.
Prepare allowed and forbidden command/parameter tests with expected errors.
Validate transcript ACL/capacity/forwarding and independent console recovery.
System changes
- None; validates staged artifacts, directory and identities.
Syntax explained
role union- A user in several mapped groups receives the combined capabilities, which can create unsafe composition.
negative matrix- Proves unavailable language, providers, executables, services and parameters—not just one happy path.
Values stay on this page and are never sent or saved.
Get-Module OneLinersJEA -ListAvailable | Select Name,Version,Path; Test-PSSessionConfigurationFile .\{{endpointName}}.pssc; Get-ADGroupMember {{operatorGroup}} | Select Name,ObjectClassModule Version Path OneLinersJEA 1.0.0 C:\Program Files\PowerShell\Modules\OneLinersJEA\1.0.0 PSSC syntax True Operator members 4 users Nested broad groups 0 Transcript free 148 GB Negative tests 9 defined
Checkpoint: No hidden identity or capability expansion remains
.\tests\Test-JEAArtifact.ps1 -Pssc .\{{endpointName}}.pssc -ModulePath {{roleModulePath}}Continue whenExact module/runtime, reviewed membership, no broad overlap, protected logs, complete test matrix and independent recovery.
Stop whenNested membership is unexplained, multiple roles compose broadly, runtime selects another module version, or negative tests/logging/recovery are incomplete.
If this step fails
Two module versions are discoverable.
Likely causePSModulePath contains stale role artifacts.
Resolve module discovery order under the endpoint runtime.
ResolutionRemove/quarantine stale version through deployment control and pin reviewed layout.
Operator is also in a broader JEA group.
Likely causeNested role membership unions capabilities.
Enumerate transitive groups and all RoleDefinitions.
ResolutionSeparate groups/endpoints or remove overlap before registration.
Security notes
- Group membership is privileged authorization data and should be monitored.
Alternatives
- Use separate endpoints for roles whose combination would create unsafe capabilities.
Stop conditions
- Nested membership is unexplained, multiple roles compose broadly, runtime selects another module version, or negative tests/logging/recovery are incomplete.
config
Register the JEA endpoint in a maintenance window
Drain or notify active remoting/DSC dependencies, preserve existing endpoint state, register the validated PSSC under the versioned endpoint name, then inspect the effective session configuration and permission. Registration may restart WinRM and terminate sessions.
Why this step matters
Registration publishes the authorization endpoint and can restart the WinRM service, interrupting active PowerShell remoting, WMI management and DSC operations. Perform it during a maintenance window with the recovery path already tested. Use a versioned endpoint name so clients can migrate explicitly and the previous endpoint can remain available until validation completes. After registration, inspect the effective permission and compare it with RoleDefinitions; do not assume the generated ACL is correct. Confirm HTTPS listener, firewall and secure authentication settings remained unchanged after the service restart. The staged PSSC can later be archived, but its exact source and hash must remain in configuration management.
What to understand
Enumerate and drain active sessions/automation or obtain interruption approval.
Archive prior endpoint configuration and role module hashes.
Register under a new versioned name rather than silently replacing a working endpoint.
Inspect effective endpoint Permission and registration details.
Recheck WinRM service, HTTPS listener, firewall and security settings after restart.
System changes
- Registers a new JEA endpoint and may restart WinRM, terminating active management sessions.
Syntax explained
Name- Client-visible configuration name used with `-ConfigurationName`.
-Force- Confirms registration/service restart behavior; not permission to overwrite an unowned endpoint.
Values stay on this page and are never sent or saved.
Register-PSSessionConfiguration -Name {{endpointName}} -Path .\{{endpointName}}.pssc -Force; Get-PSSessionConfiguration -Name {{endpointName}} | Select Name,Permission,ConfigFilePathWARNING: Registering the session configuration restarts WinRM. Name : OneLiners.PrintOperator.v1 Permission : CORP\GG-JEA-PrintOperators AccessAllowed ConfigFilePath : C:\Windows\System32\PowerShell\... WinRM : Running HTTPS listener : unchanged
Checkpoint: The registered endpoint and transport match reviewed artifacts
Get-PSSessionConfiguration -Name {{endpointName}} | Format-List *; Get-ChildItem WSMan:\localhost\ListenerContinue whenExact versioned endpoint, intended AccessAllowed group, running WinRM and unchanged validated HTTPS/firewall/security settings.
Stop whenActive critical sessions were interrupted unexpectedly, ACL differs, endpoint name collides, WinRM fails, or transport/security settings drift.
If this step fails
Registration restarts WinRM and automation fails.
Likely causeDependencies were not drained or retry-aware.
Preserve failure evidence and identify affected sessions/jobs.
ResolutionRollback or complete registration via console, then reschedule after dependency coordination.
Permission includes an unexpected principal.
Likely causeRoleDefinitions, prior endpoint ACL or registration behavior broadened access.
Inspect full PSSC, effective ACL and group mappings.
ResolutionDisable/unregister the new endpoint during the window and correct artifacts.
Security notes
- Never change endpoint ACL to Everyone or broad Administrators to fix a connection error.
Alternatives
- Deploy JEA consistently through a reviewed configuration-management/DSC resource for larger fleets after canary validation.
Stop conditions
- Active critical sessions were interrupted unexpectedly, ACL differs, endpoint name collides, WinRM fails, or transport/security settings drift.
verification
Test TLS identity, allowed-source connectivity, and authentication
From an approved management host, resolve and connect by the canonical FQDN with `Test-WSMan -UseSSL`, then create a PowerShell session specifying the JEA configuration. Use an interactive credential prompt or current domain identity; never put a password in arguments.
Why this step matters
Test the transport and authorization separately. `Test-WSMan -UseSSL` verifies that WS-Management responds through the TLS path, while a named `New-PSSession` proves authentication and endpoint ACL admission. Always use the canonical FQDN that appears in SAN; IP addresses or aliases require their own certificate identity and can change Kerberos behavior. `Get-Credential` keeps the password out of argv, shell history and tutorial output; integrated current identity may be preferable on a hardened domain management host. Do not use `SkipCACheck`, `SkipCNCheck`, `SkipRevocationCheck`, Basic, unencrypted or TrustedHosts wildcard to make a test pass. Repeat from a deliberately disallowed source and expect network denial.
What to understand
Resolve canonical FQDN and verify connection reaches the intended server.
Run Test-WSMan with UseSSL and default certificate validation.
Open the exact named endpoint using current domain identity or interactive credential object.
Record server/configuration/transport state without credential data.
Confirm an outside-source host cannot reach TCP/5986.
System changes
- Creates a temporary authenticated JEA session and corresponding audit/transcript evidence.
Syntax explained
-UseSSL- Uses HTTPS/5986 and validates the server certificate through normal client policy.
-ConfigurationName- Selects the registered JEA endpoint rather than a default full PowerShell endpoint.
Get-Credential- Prompts securely and keeps the password out of command arguments/output.
Values stay on this page and are never sent or saved.
$credential=Get-Credential -Message 'JEA operator'; Test-WSMan -ComputerName {{serverFqdn}} -UseSSL; $session=New-PSSession -ComputerName {{serverFqdn}} -UseSSL -ConfigurationName {{endpointName}} -Credential $credential; $session | Format-List ComputerName,ConfigurationName,StateProtocolVersion : 2.3 ProductVendor : Microsoft Corporation ProductVersion : OS: 10.0.26100 SP: 0.0 Stack: 3.0 ComputerName : print01.corp.example ConfigurationName : OneLiners.PrintOperator.v1 State : Opened Transport : HTTPS Certificate errors : 0
Checkpoint: The approved client reaches only the validated named endpoint
Invoke-Command -Session $session -ScriptBlock { Get-Command | Select-Object -ExpandProperty Name }Continue whenTLS validation succeeds by FQDN, JEA session opens for operator, no fallback/bypass, denied source cannot connect.
Stop whenAny certificate warning is bypassed, HTTP/Basic/unencrypted fallback occurs, wrong endpoint opens, or unapproved source reaches 5986.
If this step fails
Kerberos reports an SPN or authentication problem.
Likely causeName resolution, domain trust, time or service identity is wrong.
Validate FQDN, domain DNS/time, client/server identity and Kerberos events.
ResolutionRepair domain identity; do not add wildcard TrustedHosts or switch to Basic.
Certificate chain is untrusted on client only.
Likely causeClient trust/revocation path differs from server validation.
Inspect client chain engine and issuer/CRL availability.
ResolutionDeploy the correct enterprise trust and revocation reachability; never skip CA checks.
Security notes
- Never place passwords in `-Credential` construction from plaintext or command arguments.
Alternatives
- Use the current Kerberos identity without prompting when the hardened management session already runs as the approved operator.
Stop conditions
- Any certificate warning is bypassed, HTTP/Basic/unencrypted fallback occurs, wrong endpoint opens, or unapproved source reaches 5986.
verification
Prove permitted action and every forbidden capability
Inside the HTTPS JEA session, list commands, inspect and restart only Spooler, then attempt another service, filesystem/registry providers, native executable, arbitrary expression, script and hidden parameters. Capture expected errors and verify the service and host state.
Why this step matters
A successful allowed command is only half the authorization proof. Enumerate `Get-Command` and test every plausible escape surface: another service name, alternate parameter set, pipeline object, filesystem/registry provider, native executable, script path, expression/language construct and alias. RestrictedRemoteServer should remain NoLanguage and expose no providers. Validate the real system effect: Spooler restarts and no other service/configuration changes. A command error is acceptable only when it is the expected authorization/validation failure, not a hidden role-discovery defect. Repeat tests as an authorized operator, an authenticated but unmapped user and an outside-network user.
What to understand
List all visible commands and inspect help/syntax from the JEA session.
Run Get/Restart only for Spooler and verify service recovery.
Attempt another service and every unlisted provider/executable/language path.
Test authorized, unmapped and network-denied identities/locations.
Compare resulting transcripts/events and verify no unrelated system change.
System changes
- Restarts the Print Spooler fixture service and generates positive/negative audit evidence.
Syntax explained
ValidateSet- Rejects any service name other than the explicitly approved `Spooler`.
NoLanguage- Prevents arbitrary PowerShell language/script execution in RestrictedRemoteServer sessions.
Invoke-Command -Session $session -ScriptBlock { Get-Service -Name Spooler; Restart-Service -Name Spooler; Get-Service -Name Spooler }Status Name DisplayName ------ ---- ----------- Running Spooler Print Spooler Running Spooler Print Spooler Negative: Get-Service -Name WinRM Cannot validate argument on parameter 'Name'. WinRM does not belong to the set 'Spooler'. Negative: Get-ChildItem C:\ The term 'Get-ChildItem' is not recognized as a name of a cmdlet.
Checkpoint: The endpoint performs one task and nothing more
.\tests\Test-JEAEndpoint.ps1 -ComputerName {{serverFqdn}} -UseSSL -ConfigurationName {{endpointName}}Continue whenAllowed service inspection/restart passes; all other service, parameter, provider, executable and language tests fail as designed.
Stop whenAny unlisted command/provider/service/parameter works, unmapped user connects, or Spooler/host fails to recover.
If this step fails
Get-Service WinRM succeeds.
Likely causeParameter restriction or combined role capability is broader than reviewed.
Run Get-PSSessionCapability for the user and inspect all mapped roles.
ResolutionTake endpoint out of service, correct overlap/PSRC and re-register.
Spooler restart fails but Get-Service works.
Likely causeVirtual account rights, service dependencies/state or role parameter set is insufficient.
Inspect service dependencies/events and exact permitted cmdlet error.
ResolutionFix the bounded service operation or choose a safer wrapper; do not expose general admin.
Security notes
- Negative authorization tests are release gates and must run after every role/module update.
Alternatives
- Expose a single audited wrapper function with no caller-controlled service name when cmdlet restriction remains ambiguous.
Stop conditions
- Any unlisted command/provider/service/parameter works, unmapped user connects, or Spooler/host fails to recover.
verification
Verify protected transcripts, events, and identity attribution
Locate the session transcript and correlate it with PowerShell Operational, WinRM Operational and security log events. Verify caller identity, endpoint, command and time are present, raw logs are protected/forwarded, and operators cannot modify evidence.
Why this step matters
JEA attribution depends on preserving the connecting identity separately from the virtual account that performs the local action. Transcripts show interactive commands/output, while PowerShell and WinRM events supply endpoint/session context; security events and service logs show resulting access/action. None alone is complete, and a local administrator can tamper with local evidence. Restrict transcript ACLs, monitor capacity and forward relevant events to a separately controlled collector. Review privacy because commands and errors may include paths, object names or user data. Test log failure as a stop condition rather than silently continuing privileged access without evidence.
What to understand
Find the exact transcript for positive and negative test sessions.
Correlate caller, endpoint, command, time and service event across logs.
Verify operators cannot read/write beyond approved policy and cannot delete transcripts.
Confirm forwarding latency, retention, disk capacity and alert delivery.
Document limits: transcripts do not prove every transitive native/API action.
System changes
- None; reads protected local and forwarded evidence.
Syntax explained
TranscriptDirectory- Stores session command/output transcripts at the configured protected location.
Operational logs- Provide WinRM/PowerShell processing context that complements transcripts.
Values stay on this page and are never sent or saved.
Get-ChildItem {{transcriptPath}} -Recurse | Sort LastWriteTime -Descending | Select -First 3 FullName,Length,LastWriteTime; Get-WinEvent -LogName 'Microsoft-Windows-PowerShell/Operational' -MaxEvents 40 | Select TimeCreated,Id,MessageTranscript : D:\JEA\Transcripts\PrintOperator\20260728\PowerShell_transcript.PRINT01... Caller : CORP\alice.operator Endpoint : OneLiners.PrintOperator.v1 Command : Restart-Service -Name Spooler WinRM event correlation : present Forwarder delivery : 4.2 seconds Operator write access : denied
Checkpoint: Privileged JEA actions are attributable and retained
Get-Acl {{transcriptPath}} | Format-List; Get-ChildItem {{transcriptPath}} -Recurse | Measure-Object -Property Length -SumContinue whenCaller-to-action correlation, protected non-operator-writable transcripts, healthy capacity/forwarding and defined privacy retention.
Stop whenCaller cannot be attributed, transcript/event is missing, operator can alter evidence, forwarding gaps or capacity/retention is unsafe.
If this step fails
Transcript identifies only the virtual account.
Likely causeCorrelation with connecting user/session events is incomplete.
Inspect PSSC, PowerShell/WinRM events and transcript header/session IDs.
ResolutionRepair correlated logging before production use and declare the gap.
Transcript storage fills.
Likely causeRetention/forwarding/capacity does not match session volume.
Measure rate, free space, rotation/retention and collector delivery.
ResolutionExpand protected capacity or correct retention with evidence owners; do not delete incident data casually.
Security notes
- Transcripts may contain sensitive object names and output; enforce least-privilege access and retention.
Alternatives
- Add purpose-built structured application events for the allowed action, correlated with JEA session evidence.
Stop conditions
- Caller cannot be attributed, transcript/event is missing, operator can alter evidence, forwarding gaps or capacity/retention is unsafe.
decision
Rehearse certificate renewal and endpoint rollback
On a canary, validate a renewed certificate, rebind the HTTPS listener to its new thumbprint, retest TLS/JEA and retire the old certificate only afterward. Rehearse disabling/unregistering the new endpoint and restoring the prior version without losing all management access.
Why this step matters
The listener pins a certificate thumbprint, so certificate autoenrollment alone may leave WinRM bound to an expiring certificate. Renewal must validate the new SAN/EKU/chain/revocation/private key, update the listener through a controlled change and rerun allowed/denied source plus JEA tests before removing the old certificate. Endpoint rollback similarly requires maintenance because unregister/register can restart WinRM. Prefer deploying a new versioned endpoint, migrating clients and only later unregistering the old one. If the new endpoint is unsafe, remove its network exposure or unregister it via console while retaining the known-good endpoint. Never delete every listener or endpoint before recovery is proven.
What to understand
Alert well before certificate expiry and enroll a new approved certificate.
Validate new certificate completely before changing listener thumbprint.
Rebind on a canary and repeat TLS, authentication, allow/deny and evidence tests.
Retire old certificate only after all clients use the new binding.
Rehearse endpoint removal/previous artifact registration through independent access.
System changes
- During rehearsal, changes listener certificate binding and may register/unregister endpoint versions, restarting WinRM.
Syntax explained
versioned endpoint- Allows explicit client migration and keeps the previous authorization surface available during validation.
thumbprint rebind- Updates the listener to the newly validated certificate; renewal does not happen merely because the cert exists.
Values stay on this page and are never sent or saved.
Get-PSSessionConfiguration -Name {{endpointName}} | Format-List; Get-ChildItem WSMan:\localhost\Listener | Format-List Keys,Hostname,CertificateThumbprint; Test-WSMan -ComputerName {{serverFqdn}} -UseSSLRenewal rehearsal New certificate validation : PASS Listener rebind : PASS TLS/JEA positive tests : PASS Negative tests : PASS Old certificate retired : after validation Endpoint rollback : PASS Independent console : PASS
Checkpoint: Identity and authorization lifecycle can change without lockout or bypass
Test-WSMan -ComputerName {{serverFqdn}} -UseSSL; .\tests\Test-JEAEndpoint.ps1 -ComputerName {{serverFqdn}} -UseSSL -ConfigurationName {{endpointName}}Continue whenNew certificate valid/bound, old retired only after success, endpoint rollback proven and no management/certificate-validation gap.
Stop whenRenewed certificate fails any validation, listener cannot rebind, clients use bypass, old endpoint is only recovery path, or tests/logging fail.
If this step fails
Listener still presents the old certificate.
Likely causeThumbprint rebind failed, another listener owns address or service did not reload.
Compare effective listener and client-observed certificate.
ResolutionKeep old cert valid, correct ownership/rebind and retest; do not delete it.
Unregistering endpoint interrupts rollback session.
Likely causeRollback depended on the same WinRM service restart/path.
Use out-of-band console or separate known-good endpoint.
ResolutionRestore previous artifacts from independent access and redesign the rehearsal.
Security notes
- Never disable certificate validation to bridge renewal problems.
- Preserve old certificate/private key according to PKI policy only until validated cutover and incident requirements permit retirement.
Alternatives
- Automate monitored certificate selection/rebinding through signed configuration management after the manual canary lifecycle passes.
Stop conditions
- Renewed certificate fails any validation, listener cannot rebind, clients use bypass, old endpoint is only recovery path, or tests/logging fail.
Finish line
Verification checklist
Test-Certificate -Cert (Get-Item Cert:\LocalMachine\My\{{certificateThumbprint}}) -Policy SSL -DNSName {{serverFqdn}}; Test-WSMan -ComputerName {{serverFqdn}} -UseSSLCertificate and HTTPS WS-Management validate without bypass.Get-Item WSMan:\localhost\Service\AllowUnencrypted,WSMan:\localhost\Service\Auth\Basic,WSMan:\localhost\Client\TrustedHostsUnencrypted and Basic are false; wildcard TrustedHosts absent..\tests\Test-JEAEndpoint.ps1 -ComputerName {{serverFqdn}} -UseSSL -ConfigurationName {{endpointName}}Only Spooler inspection/restart succeeds; all other commands/parameters/providers fail.Get-PSSessionConfiguration -Name {{endpointName}} | Select Name,Permission; Get-NetFirewallRule -DisplayName 'OneLiners WinRM HTTPS from management' | Get-NetFirewallAddressFilterOnly reviewed group and management subnet reach the endpoint.Get-ChildItem {{transcriptPath}} -Recurse | Select -First 3; Get-WinEvent -LogName 'Microsoft-Windows-PowerShell/Operational' -MaxEvents 20Caller/action evidence is protected/forwarded and renewal/rollback rehearsal passes.Recovery guidance
Common problems and safe checks
Test-WSMan -UseSSL reports a certificate name error.
Likely causeThe client used an IP/alias absent from SAN or the listener bound the wrong certificate.
Compare requested FQDN, listener hostname/thumbprint and certificate SAN.
ResolutionUse the canonical FQDN and reissue/rebind a valid certificate; never bypass validation.
TCP/5986 times out.
Likely causeListener, service, source-restricted firewall, routing or network ACL is blocking the path.
Test DNS, route, listener, service and firewall from an approved source.
ResolutionRepair the exact network/listener boundary without opening all sources.
Authentication succeeds but endpoint access is denied.
Likely causeEndpoint ACL or RoleDefinitions does not include the caller's current group token.
Inspect configuration permission, role mappings and caller group token.
ResolutionCorrect group-based mapping/ACL and refresh token; do not add Everyone/Administrators broadly.
A permitted command is not visible.
Likely causeThe role capability is not discovered, module/version/path differs or parameter definition is invalid.
Run Test-PSSessionConfigurationFile and Get-PSSessionCapability for the exact user.
ResolutionFix and version the role module, then re-register during maintenance.
An operator can affect another service.
Likely causeVisibleCmdlets or wrapper function accepts unrestricted Name/InputObject/script input.
Enumerate Get-Command syntax and run negative service/parameter tests.
ResolutionTake endpoint out of service and narrow exact parameters before re-registration.
No transcript appears.
Likely causePath ACL, capacity, session configuration or transcription failed.
Inspect PSSC, directory ACL/free space and PowerShell/WinRM events.
ResolutionRestore protected logging and treat the session window as an evidence gap.
Recovery
Rollback
Use the independent console or known-good management endpoint. Block or unregister only the new JEA endpoint during a maintenance window, restore the previous versioned role module/PSSC and endpoint registration, and restore the prior HTTPS listener/firewall binding only if the new transport change caused the failure. Keep Basic and unencrypted disabled and never introduce wildcard TrustedHosts or certificate bypass.
- Stop new connections through the new endpoint/firewall rule and preserve WinRM, PowerShell, transcript and certificate evidence.
- Use out-of-band console or a separately tested known-good endpoint; do not rely on the endpoint being removed.
- Identify whether failure is certificate, listener, firewall, authentication, endpoint ACL, role capability or logging.
- If authorization is unsafe, unregister the new versioned endpoint during the approved interruption window.
- Restore the prior protected module/PSSC and registration artifacts with exact hashes.
- If listener change failed, rebind the previously valid nonexpired certificate and restore the prior narrow firewall rule.
- Verify Basic and AllowUnencrypted remain false and wildcard TrustedHosts is absent.
- Repeat TLS identity, allowed/denied source, operator/unmapped user, capability and transcript tests.
- Retire failed artifacts only after evidence retention and root-cause review.
Evidence