Add identity server lookup

ansible-collections / microsoft.ad

Ansible collection for Active Directory management

GNU General Public License v3.0

39 stars 22 forks source link

Add identity server lookup #117

Closed jborean93 closed 4 months ago

jborean93 commented 4 months ago

SUMMARY

Add a way to specify a custom server to lookup an AD identity on when using module options that accept a list of identities for an attribute. For example the microsoft.ad.group members option.

Also adds the domain_credentials option that is common to add AD based modules to specify credentials for the extra AD servers being contacted in case the default credentials do not work.

I need to find a good way to add a test for this, will most likely come under the tests done outside of CI as it will require multiple DC servers.

Fixes: https://github.com/ansible-collections/microsoft.ad/issues/56 Fixes: https://github.com/ansible-collections/microsoft.ad/issues/104

ISSUE TYPE

Feature Pull Request

COMPONENT NAME

microsoft.ad.*

github-actions[bot] commented 4 months ago

Docs Build 📝

Thank you for contribution!✨

The docsite for this PR is available for download as an artifact from this run: https://github.com/ansible-collections/microsoft.ad/actions/runs/9295601203

You can compare to the docs for the main branch here: https://ansible-collections.github.io/microsoft.ad/branch/main

File changes:

A collections/microsoft/ad/docsite/guide_ad_module_authentication.html

M collections/microsoft/ad/computer_module.html

M collections/microsoft/ad/docsite/guide_attributes.html

M collections/microsoft/ad/docsite/guide_ldap_connection.html

M collections/microsoft/ad/docsite/guide_migration.html

M collections/microsoft/ad/group_module.html

M collections/microsoft/ad/index.html

M collections/microsoft/ad/object_module.html

M collections/microsoft/ad/ou_module.html

M collections/microsoft/ad/user_module.html

Click to see the diff comparison.

**NOTE:** only file modifications are shown here. New and deleted files are excluded. See the file list and check the published docs to see those files. **The diff output was truncated because it exceeded the maximum size.** ```diff diff --git a/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/base/collections/microsoft/ad/computer_module.html b/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/head/collections/microsoft/ad/computer_module.html index df9668e..afde04b 100644 --- a/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/base/collections/microsoft/ad/computer_module.html +++ b/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/head/collections/microsoft/ad/computer_module.html @@ -232,42 +232,60 @@ see dictionary

The principal objects that the current AD object can trust for delegation to either add, remove or set.

The values for each sub option must be specified as a distinguished name CN=shenetworks,CN=Users,DC=ansible,DC=test

Each subkey value is a list of values in the form of a distinguishedName, objectGUID, objectSid, sAMAccountName, or userPrincipalName string or a dictionary with the name and optional server key.

This is the value set on the msDS-AllowedToActOnBehalfOfOtherIdentity LDAP attribute.

This is a highly sensitive attribute as it allows the principals specified to impersonate any account when authenticating with the AD computer object being managed.

To clear all principals, use set with an empty list.

See DN Lookup Attributes for more information on how DN lookups work.

See Setting list option values for more information on how to add/remove/set list options.

add

list / elements=string

list / elements=any

The AD objects by their DistinguishedName to add as a principal allowed to delegate.

Adds the principals specified as principals allowed to delegate to.

Any existing principals not specified by add will be untouched unless specified by remove or not in set.

remove

list / elements=string

lookup_failure_action

string

The AD objects by their DistinguishedName to remove as a principal allowed to delegate.

Any existing pricipals not specified by remove will be untouched unless set is defined.

Control the action to take when the lookup fails to find the DN.

fail will cause the task to fail.

ignore will ignore the value and continue.

warn will ignore the value and display a warning.

Choices:

"fail" ← (default)
"ignore"
"warn"

remove

list / elements=any

Removes the principals specified as principals allowed to delegate to.

Any existing pricipals not specified by remove will be untouched unless set is defined.

+ +

set

list / elements=string

list / elements=any

The AD objects by their DistinguishedName to set as the only principals allowed to delegate.

Sets the principals specified as principals allowed to delegate to.

This will remove any existing principals if not specified in this list.

Specify an empty list to remove all principals allowed to delegate.

description

string

@@ -275,7 +293,7 @@ see description LDAP attribute.

display_name

string

@@ -283,7 +301,7 @@ see displayName LDAP attribute.

dns_hostname

string

@@ -291,35 +309,72 @@ see dNSHostName LDAP attribute.

domain_credentials

list / elements=dictionary

Specifies the credentials that should be used when using the server specified by name.

To specify credentials for the default domain server, use an entry without the name key or use the domain_username and domain_password option.

This can be set under the play’s module defaults under the group/microsoft.ad.domain group.

See AD authentication in modules for more information.

Default: []

+ +

name

string

The name of the server these credentials are for.

This value should correspond to the value used in other options that specify a custom server to use, for example an option that references an AD identity located on a different AD server.

This key can be omitted in one entry to specify the default credentials to use when a server is not specified instead of using domain_username and domain_password.

+ +

password

string / required

The password to use when connecting to the server specified by name.

+ +

username

string / required

The username to use when connecting to the server specified by name.

+ +

domain_password

string

The password for domain_username.

The domain_credentials sub entry without a name key can also be used to specify the credentials for the default domain authentication.

This can be set under the play’s module defaults under the group/microsoft.ad.domain group.

domain_server

string

Specified the Active Directory Domain Services instance to connect to.

Can be in the form of an FQDN or NetBIOS name.

If not specified then the value is based on the default domain of the computer running PowerShell.

Custom credentials can be specified under a domain_credentials entry without a name key or through domain_username and domain_password.

This can be set under the play’s module defaults under the group/microsoft.ad.domain group.

domain_username

string

The username to use when interacting with AD.

If this is not set then the user that is used for authentication will be the connection user.

Ansible will be unable to use the connection user unless auth is Kerberos with credential delegation or CredSSP, or become is used on the task.

The domain_credentials sub entry without a name key can also be used to specify the credentials for the default domain authentication.

This can be set under the play’s module defaults under the group/microsoft.ad.domain group.

enabled

boolean

@@ -332,7 +387,7 @@ see

identity

string

@@ -342,7 +397,7 @@ see distinguishedName using the format CN={{ name }},{{ path }}. If path is not defined, the defaultNamingContext is used instead.

kerberos_encryption_types

dictionary

@@ -353,7 +408,7 @@ see Setting list option values for more information on how to add/remove/set list options.

add

list / elements=string

@@ -368,7 +423,7 @@ see

remove

list / elements=string

@@ -383,7 +438,7 @@ see

set

list / elements=string

@@ -399,7 +454,7 @@ see

location

string

@@ -407,16 +462,17 @@ see location LDAP attribute.

managed_by

string

any

The user or group that manages the object.

The value can be in the form of a distinguishedName, objectGUID, objectSid, or sAMAccountName).

The value can be in the form of a distinguishedName, objectGUID, objectSid, sAMAccountName, or userPrincipalName string or a dictionary with the name and optional server key.

This is the value set on the managedBy LDAP attribute.

See DN Lookup Attributes for more information on how DN lookups work.

name

string

@@ -425,7 +481,7 @@ see

path

string

@@ -436,7 +492,7 @@ see microsoft.ad.default_path which will equal the default value used when creating a new object.

protect_from_deletion

boolean

@@ -450,7 +506,7 @@ see

sam_account_name

string

@@ -462,7 +518,7 @@ see $ is omitted, it will be added to the end.

spn

aliases: spns

@@ -474,7 +530,7 @@ see Setting list option values for more information on how to add/remove/set list options.

add

list / elements=string

@@ -482,7 +538,7 @@ see

The SPNs to add to servicePrincipalName.

remove

list / elements=string

@@ -490,7 +546,7 @@ see

The SPNs to remove from servicePrincipalName.

set

list / elements=string

@@ -500,7 +556,7 @@ see

state

string

@@ -515,7 +571,7 @@ see

trusted_for_delegation

boolean

@@ -529,7 +585,7 @@ see

upn

string

@@ -658,7 +714,7 @@ see delegates: set: - CN=FileShare,OU=Computers,DC=domain,DC=test - - CN=DC,OU=Domain Controllers,DC=domain,DC=test + - OtherServer$ # Lookup by sAMAaccountName

diff --git a/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/base/collections/microsoft/ad/docsite/guide_attributes.html b/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/head/collections/microsoft/ad/docsite/guide_attributes.html index 665f3f1..7d38890 100644 --- a/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/base/collections/microsoft/ad/docsite/guide_attributes.html +++ b/home/runner/work/microsoft.ad/microsoft.ad/docsbuild/head/collections/microsoft/ad/docsite/guide_attributes.html @@ -24,7 +24,7 @@ - + @@ -138,6 +138,7 @@

@@ -405,6 +406,68 @@ The common types are:

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:

- 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.

- 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.

- 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.

- 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.

@@ -413,7 +476,7 @@ The common types are:

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/e141dffa884b44d99d7145330e714a0d

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 3m 50s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 12s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/850d782c0f9344379278c0ffc0bd38db

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 40s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 51s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/8a5bc257ffba4dcc880f48318201659e

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 10s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 19s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/ed49fc8572604ee5b089345af29fcb6c

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 5m 02s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 56s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/5d0e771263874f0ba33498d7c59e55dd

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 59s :heavy_check_mark: build-ansible-collection SUCCESS in 10m 19s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/e6737b85a8c7484b8909bfd4a39a9d1f

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 30s :heavy_check_mark: build-ansible-collection SUCCESS in 9m 36s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/d9dfb1fc437e4ee0b6c89ac945b1c86c

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 5m 07s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 54s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/bba5133e8e9d41f6a5ac3385cb8a1a64

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 23s :heavy_check_mark: build-ansible-collection SUCCESS in 9m 10s

ansible-collections / microsoft.ad

Add identity server lookup #117

SUMMARY

ISSUE TYPE

COMPONENT NAME

Docs Build 📝

DN Lookup Attributes

DN Lookup Attributes 