Skip to main content

Windows

The Windows plugin(win_plugin) for the Baz system allows you to read different types of data from both Active Directory & Windows servers. The plugin internally uses LDAP protocol & PowerShell APIs over the Windows Remote Management (WinRM) service to gather requested data. The plugin gets installed with the BazCLI package.

The plugin runs as a systemd service listening on port 60986 for requests. It supports both Kerberos and NTLMv2 authentication over secure connections. However, we highly recommend that you use Kerberos instead of NTLMv2, considering the inherent weakness of the authentication algorithm.

For machines where Kerberos Ticket Granting Ticket(TGT) is already available, the plugin uses the TGT to request access tokens. When a TGT is unavailable, the plugin authenticates to Active Directory and sets up a temporary TGT on the machine for each instantiation of an actor. As the actor instance terminates, the ticket is destroyed to avoid the risk of misuse.

Prerequisite​

The plugin connects to servers in your environment over LDAP on port 636 and to WinRM service on port 5986.

Ensure LDAPS and WinRM secure are configured & running on servers. See LDAPS & WinRM configuration for details.

Ensure ports 636(LDAPS) & 5986(WinRM) are open through the firewall for -

  • Domain Network if the machine running the plugin is part of the domain.
  • Private Network if the machine is not part of the Active Directory domain but is part of the same network.

Ensure the user account configured for the plugin is -

  • Allowed to "Access this computer from the network" configured through group policies. See details here.
  • Allowed to access WMI services. Configure using winrm configSDDL default.
  • Allowed to execute Secedit.exe (default location - C:\Windows\System32).

Troubleshooting​

  1. DNS resolution errors - The plugin uses DNS resolution to communicate with Active Directory(AD) and Windows servers. If the machine running the plugin is not part of the domain or the DNS servers configured cannot resolve AD servers, the plugin operations will fail. To resolve the error, please add the Active Directory's DNS servers to the plugin machine. You can configure DNS servers on the plugin machine by adding the DNS server as a nameserver in /etc/resolve.conf.

  2. Error message - "config failed: Failed to configure plugin, error - automatic bind not successful - invalidCredentials". The user doesn't have permission to access the computer from the network.

  3. Error message - "Failed to get server properties, error - HTTPSConnectionPool(host='xxx.xxx.xxx.xxx', port=5986): Max retries exceeded with URL: /wsman" The WinRM port(5986) is not open, or the WinRM service is not listening. Verify the WinRM is configured and listening on 5986. A simple telnet request telnet server_dns_name 5986 will tell you if the port is open. You can use winrm enumerate winrm/config/listener command to verify if the listener is configured and running.

  4. Error message - "Failed to get server properties, error - Access is denied". The user doesn't have permission to access the WinRM service. Configure SDDL to grant the permissions.

  5. Error message - "Failed to get server RSoP, error - Error reading security policy". The user doesn't have permission to execute secedit on the server. Grant execute permissions for Secedit.exe.

Plugin Configuration​

The plugin is configured using the actor configuration for Baz plugins. Below is a sample configuration file for reference.

[win]
plugin = "win_plugin"
url = "localhost:60986"

[win.params]
domain = "corp.bazc.com"
username = "env://AD_SERVER_USER"                 #domain username
password = "secret://secret.ldap.ad-password"
ca_certs = "file:///home/freddy/shared/CA.pem"

[win.confparams]

Sections​

[win]​

The first section declares the actor for the plugin. The keyword win becomes a programmable object for the tests. This section doesn't require any further configuration from you.

Fields​

plugin - The name of the plugin this actor configuration file instantiates.

url - The URL of the plugin.

[win.params]​

This section contains the actor configuration used to connect, authenticate and request data from the plugin. The configuration parameters support secret, environment, and file tokens. For further details, please see the BazCLI tokens section.

Fields​

domain - Active Directory root domain of your deployment.

username - The domain-qualified username used for authentication and authorization. You can specify the username in either of the below two formats -

  1. NetBIOS format <NetBIOSName>\<sam_account_name> - example corp\freddy
  2. UPN format <sam_account_name>@<domain_name> - example freddy@corp.bazc.com

If you use the NetBIOSName format, the plugin authenticates to Active Directory using NTLMv2 to get the UPN format username for further Kerberos authentication.

password -The password to authenticate to Active Directory. If the machine has Kerberos TGT available before the instantiation of the actor, the password field can be removed or commented.

ca_certs - The public key certificate file in PEM format for your environment's Certificate Authority(CA). The certificate is used for secure connection through both LDAP and WinRM. You can export the certificate directly from the CA server in PEM(Base-64) format with the following command certutil -ca.cert ca_name.cer

[win.confparams]​

Test collecitons use this section for configurations specific to their collection. For example, the Active Directory collection supports test case filters through this section. Unless a test colleciton requests, no user configuration is required for this section.