When using AD objects, a user expects to use the more human readable
form, like "user@ad.domain", but this impose some dificulties on
evaluating which object is being referenced as AD has several forms to
refer to the same object.

Each object is AD is identified uniquely by its SID, and this is the
identifier that IPA stores in its database. When managing AD objects,
IPA finds its SID and works with that value.

ansible-freeipa tried to process these objects using the human readable
values, and it cause idempontence error when ensuring the values were
present or modified, and, at least in some cases, prevented the objects
to be made absent, as the object list created didn't match the SID to
the value used as module parameter.

By using SID to process the AD objects in ipagroup, the addition or
removal of members works and idempotence of these members is ensured.

The only issue with thils approach is that it only works no server
nodes. In client nodes, the conversion to SID is not available and the
same issues that existed before will still be present.

Tests were updated to reflect these changes, a new test, specific to
idempotence issues of AD objects was added:

   tests/group/test_group_ad_users.yml

Resolves: https://issues.redhat.com/browse/RHEL-70023

When creating the lists of external members, the attribute
'ipaexternalmember' also needs to be added to the list of external
members that are part of the group object for external groups.

A test to verify the correct behavior was added and the test suite for
group external members have been cleaned up with 'yes' values changed to
'true' and the use of module_defaults.

New versions of pylint ignore Python 2 functions and types, evaluating
'unicode' as "undefined". ansible-freeipa will always define 'unicode'
when running under Python 3, and it is always defined under Python 2.

This patch fixes these false positives.

The use of the batch command is enabled for execute_ipa_commands.

Additionally keeponly is set to [] as nothing is used from the data returned
from the commands.

Some attributes for ipagroup objects are stored using lower case letters
and should be converted upon retrieving parameter data.

This patch adds the missing conversion and provides a new test playbook:

    tests/group/test_group_case_insensitive.yml

FreeIPA suports renaming groupobjects with the CLI parameter "rename",
and this parameter was missing in ansible-freeipa ipagroup module.

This patch adds support for a new state 'renamed' and the 'rename'
parameter.

Tests were updated to cope with the changes.

Ensuring (adding) several groups with mixed types external, nonposix
and posix require to have a fix in IPA:

    FreeIPA issue: https://pagure.io/freeipa/issue/9349
    FreeIPA fix: https://github.com/freeipa/freeipa/pull/6741

The simple solution is to switch to client context for ensuring several
groups simply if the user was not explicitly asking for the server context
no matter if mixed types are used.

Adding an option `groups` to create multiple groups in one operation.
Adding tests (present/absent/external/nonposix) with server and
client context.
Simple example of `groups` option:
```
tasks:
- name: Ensure 2 groups are present
  ipagroup:
    ipaadmin_password: SomeADMINpassword
    groups:
    - name: group1
    - name: group2
```

Signed-off-by: Denis Karpelevich <dkarpele@redhat.com>

Due to an API misbehaviour in FreeIPA, ipaexternalmembers need to be
treated differently than other group members parameters. Even an empty
array triggers all tests for external members, including the check for
installed dcerpc bindings.

Therefore ipagroup module has been changed to not set ipaexternalmember
to an empty list if there are no external members to be added or
removed.

ansible-test with ansible-2.14 is adding a lot of new tests to ensure
that the documentation section and the agument spec is complete. Needed
changes:

DOCUMENTATION section

- `type: str` needs to be set for string parameters
- `type: int` needs to be set for integer parameters
- `type: list` needs to be set for list parameters
- `elements: str` needs to be given for list of string parameters
- `required` tags need to be fixed according to the `argument_spec`
- `aliases` tag needs to match `argument_spec`
- `authors` needs to be given with the github user also: `Name (@user)`

argument_spec

- `elements="str"` needs to be added to all list of string parameters

The `copyright` date is extended with `-2022`.

Before "short description" was used in most plugins, modules and also
in the new module templates.

ansible-doc was therefore not showing the short description. To fix the
issue the flag was renamed to short_description instead.

Fixes: https://bugzilla.redhat.com/show_bug.cgi?id=2121362
       'ansible-doc' -l lists most idm modules as 'UNDOCUMENTED'

The group CLI option `idoverrideusers` was not supported by
ansible-freeipa, and this patch adds support to it.

Tests require an AD trust, and a user `aduser@ad.ipa.test` to exist, or
the user name must be provided (variable, CLI)  through `test_ad_user`.

A new test playbook was added:

    tests/group/test_group_idoverrideuser.yml

The services returned by group_find are of type
ipapython.kerberos.Principal. Addtionally the services are case
insensitive. Therefore services need to be converted to a lowercase
sting for proper comparison.

test_group.yml has been extended with service tests.

Currently, when adding an overlapping set of members causes playbook to
fail as the already existing members are added twice.

This patch refactors membership management by removing duplicate logic
and handling all changes to members in a single place. This change
removed code that was causing the execution failures.

These are indent issues, one item per line for argument_specs items
containing options dicts and missing or overflow spaces for comments
and dict delimiters.

This patch is needed to pass Automation Hub tests.

This patch is needed to pass Automation Hub tests.

Use the IPAAnsibleModule.params_fail_if_used method to validate
arguments provided by user.

The nonposix, posix and external parameters need to be mutually
exclusive. external was missing in this list. Only one of the three
parameters can be used.

external can not be set to no/false. This results in an error now.

if nonposix is used, posix is set as not nonposix. The nonposix
parameter is not used within the code anymore..

New tests have been added to tests the addition of users with for
nonposix and posix groups. The tests for the external group is not
active due to the need of an AD.

Fixes: #528 (Error creating nonposix group)

execute_ipa_commands replces the check mode exit, the loop over the
generated commands and also in the member failure handling for modules
with member support.

ipaadmin_variables are handled by IPAAnsibleModule,
ansible_module.params_get is used to get the parameters and
ansible_module.ipa_connect is used to simplify the module.

Use gen_add_list and gen_intersection_list for user, group, service,
externalmember, membermanager_user and membermanager_group member
handling.
The functions are used to reduce the add lists to the new entries
only and the delete lists to the entries that are in the user and
the show list result.

This enables to remove the ignores for "already a member" and
"not a member" errors..

In some places, disabling the warnings rather than fixing it required
less changes, without compromising readability.

Added code to the ipa* plugins to support Ansible's check_mode, by
means of a clean exit before the execution of the actual list of
commands that would otherwise create/update/delete IPA servers
and/or its resources.

This patch add support for adding external members to ipagroup which
have the `external` attribute set. It adds another attribute to the
module, `external_members`, which is a list of users or groups from
an external trust, to be added to the group.

This patch requires server-trust-ad to be tested, as such, the tests
have been guarded by a test block, for when such tests are available
in ansible-freeipa CI.

Fixes issue #418

This patch adds suport for the IPA CLI option `posix` when modifying
an existing group. Also, enhances verification of `external` and
`posix/non-posix` groups to avoid unneded API failures (e.g. when
no change to the posix/external status is needed).

A new test was added:

    tests/group/test_group_external_nonposix.yml

If a unknown membermanager user presence will be ensured, the unknown user
error was ignored. This has been fixed in ipagroup. The code for the error
handling in ipagroup and ipahostgroup has been adapted because of this.

New tests for tests/[host]group/test_[host]group_membermnager.yml have been
added.

A group membership manager is a user or a group that can add members to
a group or remove members from a group.

This is related to https://pagure.io/freeipa/issue/8114

New parameters have been added to the module:
- `membermanager_user`: List of member manager users assigned to this
  group. Only usable with IPA versions 4.8.4 and up.
- `membermanager_group`: List of member manager groups assigned to this
  group. Only usable with IPA versions 4.8.4 and up.

These parameters behave like member parameters.

A new test has been added:
- tests/group/test_group_membermanager.yml

group_remove_member is not able to handle services in old IPA releases.
In one case the check was missing and the removal of a user from a group
failed because of this with an older IPA version. The missing check has
been added.

Fixes #257 (ipagroup fails to remove user from group ipausers)

Because of a missing check member attributes (for use with action: member)
are cleared when a non-member attribute is changed. The fix simply adds a
check for None (parameter not set) to gen_add_del_lists in
ansible_freeipa_module to make sure that the parameter is only changed if
it should be changed.

All places where the add and removal lists have been generated manually
have been changed to also use gen_add_del_lists.

Resolves: #252 (The "Manager" attribute is removed when updating any user
                attribute)

Use SomeADMINpassword as the admin password also in the examples in the
management modules.

The changed flag returned by ipagroup calls have not been correct. This
change fixes this. Addtitionally new test cases have been added to make
sure that the changed flag is correct.

group_add_member is only supporting services in more recent IPA versions.
This is 4.7+. Code has been added to detect if services are supported by
the used IPA version and used in the parameters of the module. In this case
an error is printed.

Additionally all parameters will be get from the module using
module_params_get provided by ansible_freeipa_module. Additional to_text
conversions have been removed as they are not needed anymore with this.

The ipagroup module was not using the failed and completed items in the dict
that is returned with api_command. But it was creating add and remove
lists for users, groups and services. This is not needed if the failures
"already a member" and "not a member" in the result failures are ignored.
Only other failures are reported.

The states member_present and member_absent are not used and should also not
be used. This is a remain of the first try to ensure absence and presence
of users (members) in the group. This has been replaced with the setting
action: member.

For debug and error reporting it is needed to have the ansible module also
in the valid_creds function.

If members are added to or removed from a not existing group, an
error is printed.