From e357ec68f724aee9089403a8f608f52242d0322a Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Thu, 6 Oct 2016 08:46:12 +1000 Subject: [PATCH] Fix/windows documentation (#17851) * Updated Windows documentation for more clarity on particular features like NTLM auth. --- docsite/rst/intro_windows.rst | 179 ++++++++++++++++++++++++++++++---- 1 file changed, 160 insertions(+), 19 deletions(-) diff --git a/docsite/rst/intro_windows.rst b/docsite/rst/intro_windows.rst index ac7cf61f77..40450325b3 100644 --- a/docsite/rst/intro_windows.rst +++ b/docsite/rst/intro_windows.rst @@ -33,7 +33,15 @@ Note:: on distributions with multiple python versions, use pip2 or pip2.x, where Active Directory Support ++++++++++++++++++++++++ -If you wish to connect to domain accounts published through Active Directory (as opposed to local accounts created on the remote host), you will need to install the "python-kerberos" module on the Ansible control host (and the MIT krb5 libraries it depends on). The Ansible control host also requires a properly configured computer account in Active Directory. +Ansible supports both local accounts and domain accounts on Windows, to use domain accounts you can use either of these authentication method; + +- NTLM +- Kerberos + +NTLM authentication can be used on versions of pywinrm>=0.2.0 and does not need any special configuration on the Ansible control host. To use NTLM set ``ansible_winrm_transport=ntlm`` in the host_vars. + +To use Kerberos you will need to install the "python-kerberos" module on the Ansible control host (and the MIT krb5 libraries it depends on). The Ansible control host also requires a properly configured computer account in Active Directory. + Installing python-kerberos dependencies --------------------------------------- @@ -160,17 +168,65 @@ Ansible's windows support relies on a few standard variables to indicate the use .. include:: ../rst_common/ansible_ssh_changes_note.rst -In group_vars/windows.yml, define the following inventory variables:: +Examples +++++++++ - # it is suggested that these be encrypted with ansible-vault: - # ansible-vault edit group_vars/windows.yml +Below are some examples of how to set your inventory based on the auth method chosen. These should all be defined in the group_vars/windows.yml file. - ansible_user: Administrator - ansible_password: SecretPasswordGoesHere - ansible_port: 5986 - ansible_connection: winrm - # The following is necessary for Python 2.7.9+ when using default WinRM self-signed certificates: - ansible_winrm_server_cert_validation: ignore +Basic Auth +---------- + +Inventory setup for Basic auth:: + + ansible_user: USER + ansible_password: SecretPasswordGoesHere + ansible_port: 5986 + ansible_connection: winrm + +Certificate Auth +---------------- + +Inventory setup for Certificate auth:: + + ansible_port: 5986 + ansible_connection: winrm + ansible_transport: certificate + ansible_winrm_cert_pem: path to the client authentication certificate file path in PEM format + ansible_winrm_cert_key_pem: path to the client authentication certificate key file path in PEM format + + +Kerberos Auth +------------- + +Inventory setup for Kerberos auth, note: specifying ansible_password does not make any difference here, you need to have obtained a valid Kerberos ticket outside of Ansible for this to work:: + + ansible_user: USER@DOMAIN.COM + ansible_port: 5986 + ansible_connection: winrm + + +NTLM Auth +--------- + +Inventory setup for NTLM auth:: + + ansible_user: DOMAIN\USER + ansible_password: SecretPasswordGoesHere + ansible_port: 5986 + ansible_connection: winrm + ansible_transport: ntlm + +Other Options +------------- + +There are other inventory options you can set for additional configuration of the WinRM connections:: + +* ``ansible_winrm_scheme``: Specify the connection scheme (``http`` or ``https``) to use for the WinRM connection. Ansible uses ``https`` by default unless the port is 5985. +* ``ansible_winrm_path``: Specify an alternate path to the WinRM endpoint. Ansible uses ``/wsman`` by default. +* ``ansible_winrm_realm``: Specify the realm to use for Kerberos authentication. If the username contains ``@``, Ansible will use the part of the username after ``@`` by default. +* ``ansible_winrm_transport``: Specify one or more transports as a comma-separated list. When older versions of pywinrm <0.2.0, Ansible will use ``kerberos,plaintext`` if the ``kerberos`` module is installed and a realm is defined, otherwise ``plaintext``. +* ``ansible_winrm_server_cert_validation``: Specify the server certificate validation mode (``ignore`` or ``validate``). Ansible defaults to ``validate`` on Python 2.7.9 and higher, which will result in certificate validation errors against the Windows self-signed certificates. Unless verifiable certificates have been configured on the WinRM listeners, this should be set to ``ignore`` +* ``ansible_winrm_*``: Any additional keyword arguments supported by ``winrm.Protocol`` may be provided. Attention for the older style variables (``ansible_ssh_*``): ansible_ssh_password doesn't exist, should be ansible_ssh_pass. @@ -191,15 +247,6 @@ a version that is 3 or higher. You'll run this command again later though, to make sure everything is working. -Since 2.0, the following custom inventory variables are also supported for additional configuration of WinRM connections:: - -* ``ansible_winrm_scheme``: Specify the connection scheme (``http`` or ``https``) to use for the WinRM connection. Ansible uses ``https`` by default unless the port is 5985. -* ``ansible_winrm_path``: Specify an alternate path to the WinRM endpoint. Ansible uses ``/wsman`` by default. -* ``ansible_winrm_realm``: Specify the realm to use for Kerberos authentication. If the username contains ``@``, Ansible will use the part of the username after ``@`` by default. -* ``ansible_winrm_transport``: Specify one or more transports as a comma-separated list. By default, Ansible will use ``kerberos,plaintext`` if the ``kerberos`` module is installed and a realm is defined, otherwise ``plaintext``. -* ``ansible_winrm_server_cert_validation``: Specify the server certificate validation mode (``ignore`` or ``validate``). Ansible defaults to ``validate`` on Python 2.7.9 and higher, which will result in certificate validation errors against the Windows self-signed certificates. Unless verifiable certificates have been configured on the WinRM listeners, this should be set to ``ignore`` -* ``ansible_winrm_*``: Any additional keyword arguments supported by ``winrm.Protocol`` may be provided. - .. _windows_system_prep: Windows System Prep @@ -242,6 +289,100 @@ Looking at an Ansible checkout, copy the `examples/scripts/upgrade_to_ps3.ps1 winrm enumerate winrm/config/listener + + Listener + Address = * + Transport = HTTP + Port = 5985 + Hostname + Enabled = true + URLPrefix = wsman + CertificateThumbprint + ListeningOn = 127.0.0.1, ::1 + + Listener + Address = * + Transport = HTTPS + Port = 5986 + Hostname = WINDOWS-SERVER + Enabled = true + URLPrefix = wsman + CertificateThumbprint = 1234567890ABCDEF111213141516171819101A1B + ListeningOn = 127.0.0.1, ::1 + +In the above example we can see both a HTTP and HTTPS listener has been created and are listening on ports 5985 and 5986 respectively. + +Verify Service Settings ++++++++++++++++++++++++ + +Once you have verified that WinRM is setup and listening on a port you can use ``winrm get winrm/config/service`` to get the configuration of the WinRM service:: + + #!powershell + PS C:\> winrm get winrm/config/service + + Service + RootSDDL = O:NSG:BAD:P(A;;GA;;;BA)(A;;GR;;;IU)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD) + MaxConcurrentOperations = 4294967295 + MaxConcurrentOperationsPerUser = 1500 + EnumerationTimeoutms = 240000 + MaxConnections = 300 + MaxPacketRetrievalTimeSeconds = 120 + AllowUnencrypted = false + Auth + Basic = true + Kerberos = true + Negotiate = true + Certificate = false + CredSSP = false + CbtHardeningLevel = Relaxed + DefaultPorts + HTTP = 5985 + HTTPS = 5986 + IPv4Filter = * + IPv6Filter = * + EnableCompatibilityHttpListener = false + EnableCompatibilityHttpsListener = false + CertificateThumbprint + AllowRemoteAccess = true + +In the above example we are able to authenticate with the Windows host using: + +- Basic (local accounts only) +- Kerberos (domain accounts only) +- Negotiate [Kerberos/NTLM] (local and domain accounts) + +Because AllowUnencrypted is set to false we also have to use a HTTPS listener as pywinrm does not currently support encrypted WinRM messages over HTTP. + +The following section defines the purpose of each relevant value:: + +* ``AllowUnencrypted``: When set to ``true`` allows WinRM messages to be sent without encryption. +* ``Auth/Basic``: Allows basic authentication, only for local accounts +* ``Auth/Kerberos``: Allows Kerberos authentication, only for domain accounts +* ``Auth/Negotiate``: Leverages Windows SSPI for auth, used by NTLM and Kerberos +* ``Auth/Certificate``: Allows certificate authentication, only for local accounts +* ``Auth/CredSSP``: Allows CredSSP authentication for credential delegation (double-hop). Not currently supported by pywinrm +* ``Auth/CbtHardeningLevel``: Channel Binding Token is either mandatory (``Strict``) or optional (``Relaxed``, ``None``). ``Strict`` not currently supported by pywinrm + +.. note:: + It is highly recommended to not set AllowUnencrypted to true, please + use HTTPS endpoints wherever possible. + + Double-hop authentication is currently supported by pywinrm with + the Kerberos auth method. Please set ``ansible_winrm_kerberos_delegation=true`` + in host vars for this. + What modules are available ``````````````````````````