diff options
Diffstat (limited to 'ansible_collections/microsoft/ad/docs')
5 files changed, 220 insertions, 1 deletions
diff --git a/ansible_collections/microsoft/ad/docs/docsite/extra-docs.yml b/ansible_collections/microsoft/ad/docs/docsite/extra-docs.yml index 6a548ed38..a3b4f8ed0 100644 --- a/ansible_collections/microsoft/ad/docs/docsite/extra-docs.yml +++ b/ansible_collections/microsoft/ad/docs/docsite/extra-docs.yml @@ -6,6 +6,7 @@ sections: - title: Scenario Guides toctree: + - guide_ad_module_authentication - guide_attributes - guide_ldap_connection - guide_ldap_inventory diff --git a/ansible_collections/microsoft/ad/docs/docsite/rst/guide_ad_module_authentication.rst b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_ad_module_authentication.rst new file mode 100644 index 000000000..632c19515 --- /dev/null +++ b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_ad_module_authentication.rst @@ -0,0 +1,120 @@ +.. _ansible_collections.microsoft.ad.docsite.guide_ad_module_authentication: + +**************************** +AD Authentication in Modules +**************************** + +A key requirement of the modules used inside this collection is being able to authenticate a user to the domain controller when managing a resource. This guide will cover the different options available for this scenario. + +.. note:: + This guide covers authentication to a domain controller when using a module on a Windows host. See :ref:`LDAP Authentication <ansible_collections.microsoft.ad.docsite.guide_ldap_connection.authentication>` for information on how authentication is done when using plugins running on Linux. + +.. contents:: + :local: + :depth: 1 + +.. _ansible_collections.microsoft.ad.docsite.guide_ad_module_authentication.implicit_auth: + +Implicit Authentication +======================= + +The first and simplest option is to use the connection user's existing credentials during authentication. This avoids having to specify a username and password in the module's parameters, but it does require that the connection method used by Ansible supports credential delegation. For example using CredSSP authentication with the ``winrm`` and ``psrp`` connection plugin, or using Kerberos delegation. Other authentication options, like NTLM, do not support credential delegation and will not work with implicit authentication. + +The only way to test out if implicit authentication is available is to run the module and see if it works. If it does not work then the error will most likely contain the message ``Failed to contact the AD server``. + +.. _ansible_collections.microsoft.ad.docsite.guide_ad_module_authentication.become: + +Become +====== + +If implicit authentication is not available, the module can be run with ``become`` that specifies the username and password to use for authentication. + +.. code-block:: yaml + + - name: Use become with connection credentials + microsoft.ad.user: + name: MyUser + state: present + become: true + become_method: runas + become_flags: logon_type=new_credentials logon_flags=netcredentials_only + vars: + ansible_become_user: '{{ ansible_user }}' + ansible_become_pass: '{{ ansible_password }}' + +The ``runas`` method is used on Windows and the ``become_flags`` will specify that the credentials should be used for network authentication only. The ``ansible_become_user`` and ``ansible_become_pass`` variables specify the username and password to use for authentication. It is important that both of these variables are set to a valid username and password or else the authentication will fail. + +It is also possible to use the ``SYSTEM`` account for become. This will have the module use the AD computer account for that host when authenticating with the target DC rather than an explicit username and password. The AD computer account must still have the required rights to perform the operation requested. + +.. code-block:: yaml + + - name: Use machine account for authentication + microsoft.ad.user: + name: MyUser + state: present + become: true + become_method: runas + become_user: SYSTEM + +.. _ansible_collections.microsoft.ad.docsite.guide_ad_module_authentication.explicit_creds: + +Explicit Credentials +==================== + +The final option is to specify the username and password as module options. This can be done in two ways; with the ``domain_username`` and ``domain_password`` options, or with the ``domain_credentials`` option. An example of both methods is shown below. + +.. code-block:: yaml + + - name: Use domain_username and domain_password + microsoft.ad.user: + name: MyUser + state: present + domain_username: '{{ ansible_user }}' + domain_password: '{{ ansible_password }}' + + - name: Use domain_credentials + name: MyUser + state: present + domain_credentials: + - username: '{{ ansible_user }}' + password: '{{ ansible_password }}' + +.. note:: + The ``domain_credentials`` option was added in version 1.6.0 of this collection. + +The ``domain_credentials`` option without the ``name`` key, like in the above example, will be the credentials used for authentication with the default domain controller just like ``domain_username`` and ``domain_password``. Using both options together is not supported and will result in an error. + +The ``domain_credentials`` option can also be used to specify server specific credentials. For example when attempting to lookup the identity of an AD object: + +.. code-block:: yaml + + - name: Set member with lookup on different server + microsoft.ad.group: + name: MyGroup + state: present + members: + add: + - GroupOnDefaultDC + - name: GroupOnDefaultDC2 + - name: GroupOnOtherDC + server: OtherDC + - name: GroupOnThirdDC + server: ThirdDC + domain_credentials: + - username: UserForDefaultDC + password: PasswordForDefaultDC + - name: OtherDC + username: UserForOtherDC + password: PasswordForOtherDC + +In the case above there are three members being added to the group: + +* ``GroupOnDefaultDC`` - Will be looked up on the default domain controller using ``UserForDefaultDC`` and ``PasswordForDefaultDC`` +* ``GroupOnDefaultDC2`` - Same as the above just specified as a dictionary +* ``GroupOnOtherDC`` - Will be looked up on ``OtherDC`` using ``UserForOtherDC`` and ``PasswordForOtherDC`` +* ``GroupOnThirdDC`` - Will be looked up on ``ThirdDC`` using the implicit user authentication context + +The value for ``server`` must correspond to a ``name`` entry in ``domain_credentials``. If the server is not specified in ``domain_credentials``, the module will default to using the ``domain_username/domain_password`` or implicit user authentication. + +.. note:: + The default (no ``name`` key) entry in ``domain_credentials`` is only used for lookups without an explicit server set. The ``domain_username`` and ``domain_password`` credential will be used for all connections unless there is an explicit server entry in ``domain_credentials``. diff --git a/ansible_collections/microsoft/ad/docs/docsite/rst/guide_attributes.rst b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_attributes.rst index ee53dce64..7ed192ca2 100644 --- a/ansible_collections/microsoft/ad/docs/docsite/rst/guide_attributes.rst +++ b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_attributes.rst @@ -310,3 +310,77 @@ SDDL strings can be quite complex so building them manually is ill-advised. It i $dn = 'CN=ObjectName,DC=domain,DC=test' $obj = Get-ADObject -Identity $dn -Properties nTSecurityDescriptor $obj.nTSecurityDescriptor.GetSecurityDescriptorSddlForm('All') + +.. _ansible_collections.microsoft.ad.docsite.guide_attributes.dn_lookup_attributes: + +DN Lookup Attributes +==================== + +Some attributes in Active Directory are stored as a Distinguished Name (``DN``) value that references another AD object. Some modules expose a way to lookup the DN using a more human friendly value, such as ``managed_by``. These option values must either be a string or a dictionary with the key ``name`` and optional key ``server``. The string value or the value of ``name`` is the identity to lookup while ``server`` is the domain server to lookup the identity on. The lookup identity value can be specified as a ``distinguishedName``, ``objectGUID``, ``objectSid``, ``sAMAccountName``, or ``userPrincipalName``. The below is an example of how to lookup a DN using the ``sAMAccountName`` using a string value or in the dictionary form: + +.. code-block:: yaml + + - name: Find managed_by using string value + microsoft.ad.group: + name: My Group + scope: global + managed_by: Domain Admins + + - name: Find managed_by using dictionary value with a server + microsoft.ad.group: + name: My Group + scope: global + managed_by: + name: Domain Admins + server: OtherDC + +There are also module options that can set a list of DN values for an attribute. The list values for these options are the same as the single value attributes where each DN lookup is set as a string or a dictionary with the ``name`` and optional ``server`` key. + +.. code-block:: yaml + + - name: Specify a list of DNs to set + microsoft.ad.computer: + identity: TheComputer + delegates: + set: + - FileShare + - name: ServerA + server: OtherDC + +For list attributes with the ``add/remove/set`` subkey options, the ``lookup_failure_action`` option can also be set to ``fail`` (default), ``ignore``, or ``warn``. The ``fail`` option will fail the task if any of the lookups fail, ``ignore`` will ignore any invalid lookups, and ``warn`` will emit a warning but still continue on a lookup failure. + +.. code-block:: yaml + + - name: Specify a list of DNs to set - ignoring lookup failures + microsoft.ad.computer: + identity: TheComputer + delegates: + lookup_failure_action: ignore + set: + - FileShare + - MissingUser + +When a ``server`` key is provided, the lookup will be done using the server value specified. It is possible to also provide explicit credentials just for that server using the ``domain_credentials`` option. + +.. code-block:: yaml + + - name: Set member with lookup on different server + microsoft.ad.group: + name: MyGroup + state: present + members: + add: + - GroupOnDefaultDC + - name: GroupOnDefaultDC2 + - name: GroupOnOtherDC + server: OtherDC + domain_credentials: + - username: UserForDefaultDC + password: PasswordForDefaultDC + - name: OtherDC + username: UserForOtherDC + password: PasswordForOtherDC + +In the above, the ``GroupOnOtherDC`` will be done with ``OtherDC`` with the username ``UserForOtherDC``. + +The documentation for the module option will identify if the option supports the lookup behaviour or whether a DN value must be explicitly provided. diff --git a/ansible_collections/microsoft/ad/docs/docsite/rst/guide_ldap_connection.rst b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_ldap_connection.rst index 60755f00c..ed0b290fa 100644 --- a/ansible_collections/microsoft/ad/docs/docsite/rst/guide_ldap_connection.rst +++ b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_ldap_connection.rst @@ -7,7 +7,7 @@ LDAP Connection guide This guide covers information about communicating with an LDAP server, like Microsoft Active Directory, from the Ansible host. Unlike Windows hosts, there are no builtin mechanisms to communicate and authenticate with an LDAP server, so the plugins that run on the Ansible host require some extra configuration to get working. .. note:: - This guide covers LDAP communication from the Ansible host. This does not apply to the modules that run on the remote Windows hosts. + This guide covers LDAP communication from the Ansible host. This does not apply to the modules that run on the remote Windows hosts. See :ref:`AD Authentication in Modules <ansible_collections.microsoft.ad.docsite.guide_ad_module_authentication>` for information on how modules authentication can be configured. .. contents:: :local: diff --git a/ansible_collections/microsoft/ad/docs/docsite/rst/guide_migration.rst b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_migration.rst index c0b01ca5f..d3e3c2d26 100644 --- a/ansible_collections/microsoft/ad/docs/docsite/rst/guide_migration.rst +++ b/ansible_collections/microsoft/ad/docs/docsite/rst/guide_migration.rst @@ -129,6 +129,30 @@ Migrated to :ref:`microsoft.ad.group <ansible_collections.microsoft.ad.group_mod The functionality of this module has been merged with ``microsoft.ad.group``. Use the ``members`` option to ``add``, ``remove``, or ``set`` to add, remove, or set group members respectively. +One change is ``win_domain_group_membership`` could specify the server to lookup the member using the ``SERVER\member-name`` format. This member format is not supported in ``microsoft.ad.group`` but since v1.6.0 of this collection the same can be achieved by using a dictionary as the member value. For example: + +.. code-block:: yaml + + - name: Add a domain user/group from another Domain in the multi-domain forest to a domain group + community.windows.win_domain_group_membership: + name: GroupinDomainAAA + domain_server: DomainAAA.cloud + members: + - DomainBBB.cloud\UserInDomainBBB + state: present + + - name: Add a domain user/group from another Domain in the multi-domain forest to a domain group + microsoft.ad.group: + name: GroupinDomainAAA + domain_server: DomainAAA.cloud + members: + add: + - name: UserInDomainBBB + server: DomainBBB.cloud + state: present + +See :ref:`DN Lookup Attributes <ansible_collections.microsoft.ad.docsite.guide_attributes.dn_lookup_attributes>` for more information. + .. _ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_object_info: Module ``win_domain_object_info`` |