microsoft.ad.ldap inventory – Inventory plugin for Active Directory
Note
This inventory plugin is part of the microsoft.ad collection (version 1.7.1).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install microsoft.ad
.
You need further requirements to be able to use this inventory plugin,
see Requirements for details.
To use it in a playbook, specify: microsoft.ad.ldap
.
New in microsoft.ad 1.1.0
Synopsis
Inventory plugin for Active Directory or other LDAP sources.
Uses a YAML configuration file that ends with
microsoft.ad.ldap.{yml|yaml}
.Each host that is added will set the
inventory_hostname
to thename
of the LDAP computer object andansible_host
to the value of thedNSHostName
LDAP attribute if set. If thedNSHostName
attribute is not set on the computer object thenansible_host
is not set. See LDAP inventory hostname for more information on how these values are set and how to adjust them.The host fact
microsoft_ad_distinguished_name
will also be set to the distinguished name of the host that was used to derive the host entry.Any other fact that is needed, needs to be defined in the attributes option.
Requirements
The below requirements are needed on the local controller node that executes this inventory.
dnspython - For option server lookup support
pyspnego >= 0.8.0
pyspnego[kerberos] - For Kerberos and server lookup support
sansldap
dpapi-ng - For LAPS decryption support
Parameters
Parameter |
Comments |
---|---|
The LDAP attributes to retrieve. The keys specified are the LDAP attributes requested and the values for each attribute is a dictionary that reflects what host var to set it to and how. Each key of the inner dictionary value is the host variable name to set and the value is the template to use to derive the value. If no value is explicitly set then it will use the coerced value as returned from the LDAP attribute. Attributes that are denoted as single value in the LDAP schema are returned as that single value, multi valued attributes are returned as a list of values. See LDAP inventory attributes for more information. Default: |
|
The authentication protocol to use when connecting to the LDAP host. Defaults to
Kerberos support requires the See LDAP authentication for more information. This option can be set using a Jinja2 template value. Choices:
Configuration:
|
|
Can be the path to a CA certificate PEM or DER file, directory of PEM certificates, or the CA certificate PEM string that is used for certificate validation. If omitted, the default CA store used for validation is dependent on the current Python settings. This option can be set using a Jinja2 template value. Configuration:
|
|
The certificate validation behaviour when using a TLS connection. This can be set to
See Certificate validation for more information. This option can be set using a Jinja2 template value. Choices:
Configuration:
|
|
The certificate or certificate with key bundle that is used for certificate authentication. The value can either be a path to a file containing the certificate or string of the PEM encoded certificate. If using a path to a certificate file, the file can be a PEM encoded certificate, a PEM encoded certificate and key bundle, a DER encoded certificate, or a PFX/PKCS12 encoded certificate and key bundle. Use certificate_key if the certificate specified does not contain the key. Use certificate_password if the key is encrypted with a password. This option can be set using a Jinja2 template value. Configuration:
|
|
The certificate key that is used for certificate authentication. The value can either be a path to a file containing the key in the PEM or DER encoded form, or it can be the string of a PEM encoded key. Use certificate_password if the key is encrypted with a password. This option can be set using a Jinja2 template value. Configuration:
|
|
The password used to decrypt the certificate key specified by certificate or certificate_key. This option can be set using a Jinja2 template value. Configuration:
|
|
Create vars from jinja2 expressions. Default: |
|
The timeout in seconds to wait until the connection is established before failing. This option can be set using a Jinja2 template value. Default: Configuration:
|
|
Whether encryption is required for the connection. Encryption can either be performed using the authentication protocol or through TLS. The auth_protocol If using This option can be set using a Jinja2 template value. Choices:
Configuration:
|
|
The LDAP filter string used to query the computer objects. By default, this will be combined with the filter “(objectCategory=computer)”. Use filter_without_computer to override this behavior and have filter be the only filter used. |
|
Will not combine the filter value with the default filter “(objectCategory=computer)”. In most cases this should be Choices:
|
|
Add hosts to group based on Jinja2 conditionals. Default: |
|
Add hosts to group based on the values of a variable. Default: |
|
The default value when the host variable’s value is an empty string. This option is mutually exclusive with |
|
The key from input dictionary used to generate groups |
|
parent group for keyed group |
|
A keyed group name will start with this prefix Default: |
|
separator used to build the keyed group name Default: |
|
Set this option to This option is mutually exclusive with Choices:
|
|
Use in conjunction with keyed_groups. By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. This is because the default prefix is “” and the default separator is “_”. Set this option to False to omit the leading underscore (or other separator) if no prefix is given. If the group name is derived from a mapping the separator is still used to concatenate the items. To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead. Choices:
|
|
The password to authenticate with. If auth_protocol is If auth_protocol is This option can be set using a Jinja2 template value. Configuration:
|
|
The LDAP port to use for the connection. Port 389 is used for LDAP and port 686 is used for LDAPS. Defaults to port This option can be set using a Jinja2 template value. Configuration:
|
|
The LDAP search base to find the computer objects in. Defaults to the If searching a larger Active Directory database, it is recommended to narrow the search base to speed up the queries. |
|
The scope of the LDAP search to perform.
Choices:
|
|
The domain controller/server to connect to. If not specified the server will be derived from the current krb5.conf See Server lookup for more information. This option can be set using a Jinja2 template value. Configuration:
|
|
If Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default. Choices:
|
|
The TLS operation to use. If an explicit port is set to
It is recommended to use This option can be set using a Jinja2 template value. Choices:
Configuration:
|
|
Merge extra vars into the available variables for composition (highest precedence). Choices:
Configuration:
|
|
The username to authenticate with. If auth_protocol is If auth_protocol is This option can be set using a Jinja2 template value. Configuration:
|
Notes
Note
See LDAP inventory for more details on how to use this inventory plugin.
See LAPS for more details on how this plugin can retrieve the LAPS password information.
This plugin is a tech preview and the module options are subject to change based on feedback received.
Unless specified otherwise in the option description, the value specified in the config file is used as is. Only the LDAP connection options allow using a Jinja2 template.
See LDAP connection help for more information about LDAP connections.
Examples
# Set in the file ending with microsoft.ad.ldap.yml or microsoft.ad.ldap.yaml
plugin: microsoft.ad.ldap
####################################################################
# Connection Options #
# #
# These options control how the plugin connects to the LDAP server #
####################################################################
# Connects to ldap://dc01.domain.com:389
server: dc01.domain.com
port: 389
# Connects to ldaps://dc01.domain.com:636
server: dc01.domain.com
tls_mode: ldaps
# Connects to the global catalog
# ldap://dc01.domain.com:3268
server: dc01.domain.com
port: 3268
# Provides explicit user, will use the current Kerberos ticket if no credential
# is provided.
username: [email protected]
password: Password123!
# Only allow Kerberos authentication.
auth_protocol: kerberos
# Verify LDAPS CA chain with custom CA chain.
tls_mode: ldaps
ca_cert: /home/user/certs/ldap.pem
# The username and password can be retrieved using a template with a lookup.
# Other connection options can also be set this way, the option description
# tells you whether it can be set to a template.
username: '{{ lookup("ansible.builtin.env", "LDAP_USERNAME") }}'
password: '{{ lookup("ansible.builtin.env", "LDAP_PASSWORD") }}'
##############################################
# Search Options #
# #
# These options control the searching rules #
##############################################
# Search for computer accounts in the Workshop OU.
search_base: OU=Workshop A,DC=domain,DC=com
# Filter the computer accounts returned for only ones with the dNSDomainName
# attribute set.
filter: (dNSDomainName=*)
# Filter computer accounts returned for ones starting with PROD and with the
# LAPS password set.
filter: (&(sAMAccountName=PROD*)(ms-Mcs-AdmPwd=*))
# See documentation for more details
attributes:
sAMAccountName:
sam_account_name:
objectSid:
computer_sid:
pwdLastSet:
password_last_set: this | microsoft.ad.as_datetime
comment:
host_comment
memberOf:
# Gets the value (1) of the first RDN (0) of each memberOf instance (this).
# For example 'CN=Domain Admins,CN=Users,DC=domain,DC=test'
# will be returned as just 'Domain Admins'
computer_membership: this | microsoft.ad.parse_dn | map(attribute="0.1")
location:
############################################################################
# LAPS Integration #
# #
# Examples on how to use the new Windows LAPS values as connection options #
############################################################################
attributes:
# msLAPS-Password is used if no encryption has been configured.
# Currently an encrypted LAPS password is not supported.
msLAPS-Password:
ansible_user: (this | from_json).n
ansible_password: (this | from_json).p
# msLAPS-EncryptedPassword is used if encryption has been configured.
# If the Python dpapi-ng library is installed the `this`` value will
# contain the entry `value` which is the decrypted value. The ``info``
# entry will contain the reason why the value could not be decrypted.
msLAPS-EncryptedPassword:
ansible_user: (this.value | from_json).n
ansible_password: (this.value | from_json).p
# ms-Mcs-AdmPwd is used for Legacy LAPS and stores just the password.
# The username needs to be hardcoded as a string value for this template.
ms-Mcs-AdmPwd:
ansible_user: '"Administrator"'
ansible_password: this
#####################################################################
# Constructed Options #
# #
# These options control the constructed values like vars and groups #
#####################################################################
# Build composed host variables. Requires attributes to be set in the
# attributes option to be referenced here.
compose:
host_var: computer_sid
# Conditionals that adds found hosts to the groups specified.
groups:
# Adds all hosts to the windows group
windows: true
# Uses the memberOf fact documented above to place the host in the production
# group if it's a member of that group
production: '"Production Group" in computer_membership'
# Adds the host to a group site_{{ location }} with the default group of
# site_unknown if the location isn't defined
keyed_groups:
- key: location | default(omit)
prefix: site
default_value: unknown