1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2020, Ansible Project 5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 6 7DOCUMENTATION = r''' 8--- 9module: win_domain_object_info 10short_description: Gather information an Active Directory object 11description: 12- Gather information about multiple Active Directory object(s). 13options: 14 domain_password: 15 description: 16 - The password for C(domain_username). 17 type: str 18 domain_server: 19 description: 20 - Specified the Active Directory Domain Services instance to connect to. 21 - Can be in the form of an FQDN or NetBIOS name. 22 - If not specified then the value is based on the default domain of the computer running PowerShell. 23 type: str 24 domain_username: 25 description: 26 - The username to use when interacting with AD. 27 - If this is not set then the user that is used for authentication will be the connection user. 28 - Ansible will be unable to use the connection user unless auth is Kerberos with credential delegation or CredSSP, 29 or become is used on the task. 30 type: str 31 filter: 32 description: 33 - Specifies a query string using the PowerShell Expression Language syntax. 34 - This follows the same rules and formatting as the C(-Filter) parameter for the PowerShell AD cmdlets exception 35 there is no variable substitutions. 36 - This is mutually exclusive with I(identity) and I(ldap_filter). 37 type: str 38 identity: 39 description: 40 - Specifies a single Active Directory object by its distinguished name or its object GUID. 41 - This is mutually exclusive with I(filter) and I(ldap_filter). 42 - This cannot be used with either the I(search_base) or I(search_scope) options. 43 type: str 44 include_deleted: 45 description: 46 - Also search for deleted Active Directory objects. 47 default: no 48 type: bool 49 ldap_filter: 50 description: 51 - Like I(filter) but this is a tradiitional LDAP query string to filter the objects to return. 52 - This is mutually exclusive with I(filter) and I(identity). 53 type: str 54 properties: 55 description: 56 - A list of properties to return. 57 - If a property is C(*), all properties that have a set value on the AD object will be returned. 58 - If a property is valid on the object but not set, it is only returned if defined explicitly in this option list. 59 - The properties C(DistinguishedName), C(Name), C(ObjectClass), and C(ObjectGUID) are always returned. 60 - Specifying multiple properties can have a performance impact, it is best to only return what is needed. 61 - If an invalid property is specified then the module will display a warning for each object it is invalid on. 62 type: list 63 elements: str 64 search_base: 65 description: 66 - Specify the Active Directory path to search for objects in. 67 - This cannot be set with I(identity). 68 - By default the search base is the default naming context of the target AD instance which is the DN returned by 69 "(Get-ADRootDSE).defaultNamingContext". 70 type: str 71 search_scope: 72 description: 73 - Specify the scope of when searching for an object in the C(search_base). 74 - C(base) will limit the search to the base object so the maximum number of objects returned is always one. This 75 will not search any objects inside a container.. 76 - C(one_level) will search the current path and any immediate objects in that path. 77 - C(subtree) will search the current path and all objects of that path recursively. 78 - This cannot be set with I(identity). 79 choices: 80 - base 81 - one_level 82 - subtree 83 type: str 84notes: 85- The C(sAMAccountType_AnsibleFlags) and C(userAccountControl_AnsibleFlags) return property is something set by the 86 module itself as an easy way to view what those flags represent. These properties cannot be used as part of the 87 I(filter) or I(ldap_filter) and are automatically added if those properties were requested. 88author: 89- Jordan Borean (@jborean93) 90''' 91 92EXAMPLES = r''' 93- name: Get all properties for the specified account using its DistinguishedName 94 community.windows.win_domain_object_info: 95 identity: CN=Username,CN=Users,DC=domain,DC=com 96 properties: '*' 97 98- name: Get the SID for all user accounts as a filter 99 community.windows.win_domain_object_info: 100 filter: ObjectClass -eq 'user' -and objectCategory -eq 'Person' 101 properties: 102 - objectSid 103 104- name: Get the SID for all user accounts as a LDAP filter 105 community.windows.win_domain_object_info: 106 ldap_filter: (&(objectClass=user)(objectCategory=Person)) 107 properties: 108 - objectSid 109 110- name: Search all computer accounts in a specific path that were added after February 1st 111 community.windows.win_domain_object_info: 112 filter: objectClass -eq 'computer' -and whenCreated -gt '20200201000000.0Z' 113 properties: '*' 114 search_scope: one_level 115 search_base: CN=Computers,DC=domain,DC=com 116''' 117 118RETURN = r''' 119objects: 120 description: 121 - A list of dictionaries that are the Active Directory objects found and the properties requested. 122 - The dict's keys are the property name and the value is the value for the property. 123 - All date properties are return in the ISO 8601 format in the UTC timezone. 124 - All SID properties are returned as a dict with the keys C(Sid) as the SID string and C(Name) as the translated SID 125 account name. 126 - All byte properties are returned as a base64 string. 127 - All security descriptor properties are returned as the SDDL string of that descriptor. 128 - The properties C(DistinguishedName), C(Name), C(ObjectClass), and C(ObjectGUID) are always returned. 129 returned: always 130 type: list 131 elements: dict 132 sample: | 133 [{ 134 "accountExpires": 0, 135 "adminCount": 1, 136 "CanonicalName": "domain.com/Users/Administrator", 137 "CN": "Administrator", 138 "Created": "2020-01-13T09:03:22.0000000Z", 139 "Description": "Built-in account for administering computer/domain", 140 "DisplayName": null, 141 "DistinguishedName": "CN=Administrator,CN=Users,DC=domain,DC=com", 142 "memberOf": [ 143 "CN=Group Policy Creator Owners,CN=Users,DC=domain,DC=com", 144 "CN=Domain Admins",CN=Users,DC=domain,DC=com" 145 ], 146 "Name": "Administrator", 147 "nTSecurityDescriptor": "O:DAG:DAD:PAI(A;;LCRPLORC;;;AU)(A;;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;SY)(A;;CCDCLCSWRPWPLOCRSDRCWDWO;;;BA)", 148 "ObjectCategory": "CN=Person,CN=Schema,CN=Configuration,DC=domain,DC=com", 149 "ObjectClass": "user", 150 "ObjectGUID": "c8c6569e-4688-4f3c-8462-afc4ff60817b", 151 "objectSid": { 152 "Sid": "S-1-5-21-2959096244-3298113601-420842770-500", 153 "Name": "DOMAIN\Administrator" 154 }, 155 "sAMAccountName": "Administrator", 156 }] 157''' 158