# Copyright: (c) 2023, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION:
  module: group
  short_description: Manage Active Directory group objects
  description:
    - Manages Active Directory group objects and their attributes.
  options:
    category:
      description:
        - The category of the group.
        - If a new group is created then C(security) will be used by default.
        - A C(security) group can be associated with access control lists
          whereas C(distribution) groups are typically associated with mailing
          distribution lists.
        - This is the value set on the C(groupType) LDAP attributes.
      choices:
        - distribution
        - security
      type: str
    homepage:
      description:
        - The homepage of the group.
        - This is the value set on the C(wWWHomePage) LDAP attribute.
      type: str
    managed_by:
      description:
        - The user or group that manages the group.
        - The value can be in the form of a C(distinguishedName), C(objectGUID),
          C(objectSid), C(sAMAccountName), or C(userPrincipalName) string or a
          dictionary with the I(name) and optional I(server) key.
        - This is the value set on the C(managedBy) LDAP attribute.
        - See
          R(DN Lookup Attributes,ansible_collections.microsoft.ad.docsite.guide_attributes.dn_lookup_attributes)
          for more information on how DN lookups work.
      type: raw
    members:
      description:
        - The members of the group to set.
        - The value is a dictionary that contains 3 keys, I(add), I(remove), and
          I(set).
        - Each subkey value is a list of values in the form of a
          C(distinguishedName), C(objectGUID), C(objectSid), C(sAMAccountName),
          or C(userPrincipalName) string or a dictionary with the I(name) and
          optional I(server) key.
        - The value for each subkey can either be specified as a string or a
          dictionary with the I(name) and optional I(server) key. The I(name) is
          the identity to lookup and I(server) is an optional key to override
          what AD server to lookup the identity on.
        - See
          R(DN Lookup Attributes,ansible_collections.microsoft.ad.docsite.guide_attributes.dn_lookup_attributes)
          for more information.
      type: dict
      suboptions:
        add:
          description:
            - Adds the principals specified as members of the group, keeping the
              existing membership if they are not specified.
          type: list
          elements: raw
        lookup_failure_action:
          description:
            - Control the action to take when the lookup fails to find the DN.
            - C(fail) will cause the task to fail.
            - C(ignore) will ignore the value and continue.
            - C(warn) will ignore the value and display a warning.
          choices: ['fail', 'ignore', 'warn']
          default: fail
          type: str
        remove:
          description:
            - Removes the principals specified as members of the group, keeping
              the existing membership if they are not specified.
          type: list
          elements: raw
        set:
          description:
            - Sets only the principals specified as members of the group.
            - Any other existing member will be removed from the group
              membership if not specified in this list.
            - Set this to an empty list to remove all members from a group.
          type: list
          elements: raw
    sam_account_name:
      description:
        - The C(sAMAccountName) value to set for the group.
        - If omitted, the I(name) value is used when creating a new group.
      type: str
    scope:
      description:
        - The scope of the group.
        - This is required when I(state=present) and the group does not already
          exist.
        - See
          L(Group scope,https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc755692%28v=ws.10%29)
          for more information on the various domain group scopes.
        - This is the value set on the C(groupType) LDAP attributes.
      choices:
        - domainlocal
        - global
        - universal
      type: str
  notes:
    - See R(win_group migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_group)
      for help on migrating from M(community.windows.win_domain_group) to this
      module.
    - This module must be run on a Windows target host with the
      C(ActiveDirectory) module installed.
  extends_documentation_fragment:
    - microsoft.ad.ad_object
    - ansible.builtin.action_common_attributes
  attributes:
    check_mode:
      support: full
    diff_mode:
      support: full
    platform:
      platforms:
        - windows
  seealso:
    - module: microsoft.ad.domain
    - module: microsoft.ad.domain_controller
    - module: microsoft.ad.membership
    - module: microsoft.ad.object_info
    - module: microsoft.ad.object
    - module: microsoft.ad.user
    - ref: Migration guide <ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_group>
      description: This module replaces C(community.windows.win_domain_group). See the migration guide for details.
    - module: community.windows.win_domain_group
  author:
    - Jordan Borean (@jborean93)

EXAMPLES: |
  - name: Ensure a group exists
    microsoft.ad.group:
      identity: Cow
      scope: global

  - name: Remove a group
    microsoft.ad.group:
      identity: Cow
      state: absent

  - name: Create a group in a custom path
    microsoft.ad.group:
      name: Cow
      scope: global
      path: OU=groups,DC=ansible,DC=local
      state: present

  - name: Remove a group in a custom path
    microsoft.ad.group:
      name: Cow
      path: OU=groups,DC=ansible,DC=local
      state: absent

  - name: Create group with delete protection enabled and custom attributes
    microsoft.ad.group:
      name: Ansible Users
      scope: domainlocal
      category: security
      homepage: www.ansible.com
      attributes:
        set:
          mail: helpdesk@ansible.com
      protect_from_deletion: true

  - name: Change the path of a group
    microsoft.ad.group:
      name: MyGroup
      scope: global
      identity: S-1-5-21-2171456218-3732823212-122182344-1189
      path: OU=groups,DC=ansible,DC=local

  - name: Add managed_by user
    microsoft.ad.group:
      name: Group Name Here
      scope: global
      managed_by: Domain Admins

  - name: Add group and specify the AD domain services to use for the create
    microsoft.ad.group:
      name: Test Group
      domain_username: user@CORP.ANSIBLE.COM
      domain_password: Password01!
      domain_server: corp-DC12.corp.ansible.com
      scope: domainlocal

  - name: Add members to the group, preserving existing membership
    microsoft.ad.group:
      name: Test Group
      scope: domainlocal
      members:
        add:
          - Domain Admins
          - Domain Users

  - name: Remove members from the group, preserving existing membership
    microsoft.ad.group:
      name: Test Group
      scope: domainlocal
      members:
        remove:
          - Domain Admins
          - Domain Users

  - name: Replace entire membership of group
    microsoft.ad.group:
      name: Test Group
      scope: domainlocal
      members:
        set:
          - Domain Admins
          - Domain Users
          - name: UserInOtherDomain
            server: OtherDomain
      domain_credentials:
        - name: OtherDomain
          username: OtherDomainUser
          password: '{{ other_domain_password }}'

RETURN:
  object_guid:
    description:
      - The C(objectGUID) of the AD object that was created, removed, or edited.
      - If a new object was created in check mode, a GUID of 0s will be
        returned.
    returned: always
    type: str
    sample: d84a141f-2b99-4f08-9da0-ed2d26864ba1
  distinguished_name:
    description:
      - The C(distinguishedName) of the AD object that was created, removed, or
        edited.
    returned: always
    type: str
    sample: CN=MyGroup,CN=Users,,DC=domain,DC=test
  sid:
    description:
      - The Security Identifier (SID) of the group managed.
      - If a new group was created in check mode, the SID will be C(S-1-5-0000).
    returned: always
    type: str
    sample: S-1-5-21-4151808797-3430561092-2843464588-1104
