Repository: ansible/ansible
Pull request: Update user module documentation to include MacOS password change behavior
##### SUMMARY
<!--- Describe the change below, including rationale and design decisions -->
[User Module] Include MacOS password change behaviour in documentation

<!--- HINT: Include "Fixes #nnn" if you are fixing an existing issue -->
Fixes https://github.com/ansible/ansible/issues/80884
##### ISSUE TYPE
<!--- Pick one below and delete the rest -->
- Docs Pull Request

##### COMPONENT NAME
<!--- Write the short name of the module, plugin, task or feature below -->
User module 
##### ADDITIONAL INFORMATION
<!--- Include additional information to help people understand the change here -->
<!--- A step-by-step reproduction of the problem is helpful if there is no related issue -->

<!--- Paste verbatim command output below, e.g. before and after your change -->

This pull request adds information to the user module documentation regarding the behavior of password changes on MacOS. Specifically, it highlights the fact that MacOS will always enforce the setting of a password, regardless of the input provided. Even if an empty or null password is specified, MacOS will automatically assign a password and return a status of changed: true.

This addition is important to ensure that users are aware of the specific behavior when using the user module on MacOS, as it may differ from other operating systems.

This Pull request fixes the issue mentioned in #80884 

Please review and consider merging this pull request to provide comprehensive and accurate documentation for users working with the user module on MacOS.



```


Problem statement:
Add an user in macOS with idempotent 
### Summary

User module is not idempotent when update_password: always parameter set in the playbook for macOS 

Result is always showing changed if use already present and no changes in the password . 



### Issue Type

Bug Report

### Component Name

user

### Ansible Version

```console
ansible 2.9.21
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/navarihtak/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/navarihtak/.local/lib/python3.8/site-packages/ansible
  executable location = /home/navarihtak/.local/bin/ansible
  python version = 3.8.10 (default, Nov 14 2022, 12:59:47) [GCC 9.4.0]
```


### Configuration

```console
# if using a version older than ansible-core 2.12 you should omit the '-t all'
$ ansible-config dump --only-changed -t all
$ ansible-config dump --only-changed
DEFAULT_VAULT_PASSWORD_FILE(env: ANSIBLE_VAULT_PASSWORD_FILE) = /home/navarihtak/.ansible/.vault_pass
HOST_KEY_CHECKING(env: ANSIBLE_HOST_KEY_CHECKING) = False
$
```


### OS / Environment

All MacOS version 

### Steps to Reproduce

```yaml
      - name: Add user for Darwin
        user:
          name: "{{ username }}"
          comment: "{{ username }}"
          shell: "/bin/bash"
          group: "{{ user_group }}"
          password: "{{ user_pass }}"
          update_password: always
          state: present
        when: ansible_os_family == 'Darwin'
        become: yes
```

### Expected Results

It should be idempotent. Result status should shows ok if user is already exist and password is not changed. 

### Actual Results

```console
Always shows result status is changed if user is already exist and password is not changed.
```


### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct

Hints from issue discussion:
Files identified in the description:
* [`lib/ansible/modules/user.py`](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/user.py)

If these files are incorrect, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/devel/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
Since MacOS no longer provides access to the hashed passwords, the only way we're aware of to tell if the password is stale is to attempt a login, which ... no. Probably just needs to be documented.
Hello @nitzmahone , can I please work on this request? 
@cNeha what, augmenting the module docs to mention that MacOS will always set the password and return `changed: true` ? Go for it...

Commit message: Update user module documentation to include MacOS password change behavior

Patch to review:
diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py
index dc2a2f6de5b091..5dcf985ba8bdbc 100644
--- a/lib/ansible/modules/user.py
+++ b/lib/ansible/modules/user.py
@@ -93,6 +93,8 @@
             - To create an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
             - To create an account with a locked/disabled password on OpenBSD, set this to C('*************').
             - B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions.
+            - On macOS, when using the `user` module, the password specified in the `password` option will always be set, regardless of whether the user account already exists or not.
+            - When the password is set or changed, the `user` module will always return `changed: true` for macOS systems.
         type: str
     state:
         description:


Code review comments:
diff_hunk: @@ -93,6 +93,8 @@
             - To create an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
             - To create an account with a locked/disabled password on OpenBSD, set this to C('*************').
             - B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions.
+            - On macOS, the password specified in the `password` option will always be set, regardless of whether the user account already exists or not.
+            - When the password is set or changed, the `user` module will always return `changed: true` for macOS systems.
path: lib/ansible/modules/user.py
text: @user1:
s/is set or changed/is passed as an argument/

diff_hunk: @@ -93,6 +93,8 @@
             - To create an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
             - To create an account with a locked/disabled password on OpenBSD, set this to C('*************').
             - B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions.
+            - On macOS, the password specified in the `password` option will always be set, regardless of whether the user account already exists or not.
path: lib/ansible/modules/user.py
text: @user1:
```suggestion
            - On macOS, the password specified in the C(password) option will always be set,
               regardless of whether the user account already exists or not.
               Since macOS no longer provides access to the hashed passwords directly.
```

diff_hunk: @@ -93,6 +93,8 @@
             - To create an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
             - To create an account with a locked/disabled password on OpenBSD, set this to C('*************').
             - B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions.
+            - On macOS, the password specified in the `password` option will always be set, regardless of whether the user account already exists or not.
+            - When the password is set or changed, the `user` module will always return `changed: true` for macOS systems.
path: lib/ansible/modules/user.py
text: @user1:
```suggestion
            - When the password is passed as an argument, the module will always return C(changed: true) for macOS systems.
```