win_mapped_drive - refactor module and docs (#48642)

* win_mapped_drive - refactor module and docs

* Updated code to work with become and split tokens

* use win_credential_manager instead of cmdkey

* updated credential manager module name

* harden the system token impersonation process

test/integration/targets/win_mapped_drive/tasks/main.yml

@@ -2,6 +2,7 @@
 # test setup
 - name: gather facts required by the tests
   setup:
+    gather_subset: platform
 
 - name: ensure mapped drive is deleted before test
   win_mapped_drive:
@@ -31,12 +32,36 @@
   - { name: '{{test_win_mapped_drive_path}}', path: '{{test_win_mapped_drive_local_path}}' }
   - { name: '{{test_win_mapped_drive_path2}}', path: '{{test_win_mapped_drive_local_path2}}' }
 
+# This ensures we test out the split token/become behaviour
+- name: ensure builtin Administrator has a split token
+  win_regedit:
+    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System
+    name: FilterAdministratorToken
+    data: 1
+    type: dword
+  register: admin_uac
+
+- name: reboot to apply Admin approval mode setting
+  win_reboot:
+  when: admin_uac is changed
+
 - block:
   # tests
   - include_tasks: tests.yml
 
   # test cleanup
   always:
+  - name: remove stored credential
+    win_credential:
+      name: '{{ ansible_hostname }}'
+      type: domain_password
+      state: absent
+    vars:
+      ansible_become: yes
+      ansible_become_method: runas
+      ansible_become_user: '{{ ansible_user }}'
+      ansible_become_pass: '{{ ansible_password }}'
+
   - name: ensure mapped drive is deleted at the end of the test
     win_mapped_drive:
       letter: '{{test_win_mapped_drive_letter}}'
@@ -60,3 +85,15 @@
     win_user:
       name: '{{test_win_mapped_drive_temp_user}}'
       state: absent
+
+  - name: disable Admin approval mode if changed in test
+    win_regedit:
+      path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System
+      name: FilterAdministratorToken
+      data: 0
+      type: dword
+    when: admin_uac is changed
+
+  - name: reboot to apply Admin approval mode setting
+    win_reboot:
+    when: admin_uac is changed

test/integration/targets/win_mapped_drive/tasks/tests.yml

@@ -2,6 +2,7 @@
 - name: fail with invalid path
   win_mapped_drive:
     letter: invalid
+    state: absent
   register: fail_invalid_letter
   failed_when: "fail_invalid_letter.msg != 'letter must be a single letter from A-Z, was: invalid'"
 
@@ -10,7 +11,7 @@
     letter: '{{test_win_mapped_drive_letter}}'
     state: present
   register: fail_path_missing
-  failed_when: fail_path_missing.msg != 'path must be set when creating a mapped drive'
+  failed_when: "fail_path_missing.msg != 'state is present but all of the following are missing: path'"
 
 - name: fail when specifying letter with existing physical path
   win_mapped_drive:
@@ -210,7 +211,7 @@
     that:
     - map_with_credentials is changed
     - map_with_credentials_actual.rc == 0
-    - map_with_credential_actual_username.value == '{{ansible_hostname}}\\{{test_win_mapped_drive_temp_user}}'
+    - map_with_credential_actual_username.value == ''  # we explicitly remove the username part in the module
 
 - name: map drive with current credentials again
   win_mapped_drive:
@@ -224,7 +225,7 @@
 - name: assert map drive with current credentials again
   assert:
     that:
-    - map_with_credentials_again is changed # we expect a change as it will just delete and recreate if credentials are passed
+    - not map_with_credentials_again is changed
 
 - name: delete mapped drive without path check
   win_mapped_drive:
@@ -270,3 +271,74 @@
   assert:
     that:
     - delete_without_path_again is not changed
+
+- name: store credential for test network account
+  win_credential:
+    name: '{{ ansible_hostname }}'
+    type: domain_password
+    username: '{{ test_win_mapped_drive_temp_user }}'
+    secret: '{{ test_win_mapped_drive_temp_password }}'
+    state: present
+  vars: &become_vars
+    ansible_become: yes
+    ansible_become_method: runas
+    ansible_become_user: '{{ ansible_user }}'
+    ansible_become_pass: '{{ ansible_password }}'
+
+- name: map drive with stored cred (check mode)
+  win_mapped_drive:
+    letter: '{{test_win_mapped_drive_letter}}'
+    path: \\{{ansible_hostname}}\{{test_win_mapped_drive_path}}
+    state: present
+  check_mode: yes
+  vars: *become_vars
+  register: map_with_stored_cred_check
+
+- name: get actual of map drive with stored cred (check mode)
+  win_command: 'net use {{test_win_mapped_drive_letter}}:'
+  register: map_with_stored_cred_actual_check
+  failed_when: False
+
+- name: assert map drive with stored cred (check mode)
+  assert:
+    that:
+    - map_with_stored_cred_check is changed
+    - map_with_stored_cred_actual_check.rc == 2
+
+- name: map drive with stored cred
+  win_mapped_drive:
+    letter: '{{test_win_mapped_drive_letter}}'
+    path: \\{{ansible_hostname}}\{{test_win_mapped_drive_path}}
+    state: present
+  vars: *become_vars
+  register: map_with_stored_cred
+
+- name: get actual of map drive with stored cred
+  win_command: 'net use {{test_win_mapped_drive_letter}}:'
+  register: map_with_stored_cred_actual
+
+- name: get username of mapped network drive with stored cred
+  win_reg_stat:
+    path: HKCU:\Network\{{test_win_mapped_drive_letter}}
+    name: UserName
+  register: map_with_stored_cred_actual_username
+
+- name: assert map drive with stored cred
+  assert:
+    that:
+    - map_with_stored_cred is changed
+    - map_with_stored_cred_actual.rc == 0
+    - map_with_stored_cred_actual_username.value == ''
+
+- name: map drive with stored cred again
+  win_mapped_drive:
+    letter: '{{test_win_mapped_drive_letter}}'
+    path: \\{{ansible_hostname}}\{{test_win_mapped_drive_path}}
+    state: present
+  vars: *become_vars
+  register: map_with_stored_cred_again
+
+- name: assert map drive with stored cred again
+  assert:
+    that:
+    - not map_with_stored_cred_again is changed