microsoft.ad.service_account module – Manage Active Directory service account objects

Note

This module 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 module, see Requirements for details.

To use it in a playbook, specify: microsoft.ad.service_account.

New in microsoft.ad 1.7.0

Synopsis

  • Manages Active Directory service account objects and their attributes.

  • Currently this module only supports group managed service accounts (gMSA).

  • Before creating a gMSA, the AD environment must have created a KDS root key. See KDS Key for more details. For the key to be effective immediately, set the effective time for 10 hours ago and do not use the -EffectiveImmediately parameter. See the examples for more details.

Requirements

The below requirements are needed on the host that executes this module.

  • ActiveDirectory PowerShell module

Parameters

Parameter

Comments

allowed_to_retrieve_password

dictionary

The principals that are allowed to retrieve the password for the service account to either add, remove, or set.

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

This value is built into a security descriptor by the ActiveDirectory cmdlet and set on the msDS-GroupMSAMembership LDAP attribute.

This corresponds to the -PrincipalsAllowedToRetrieveManagedPassword parameter on the AD cmdlets.

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=any

Adds the principals specified as principals allowed to retrieve the service account password.

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

lookup_failure_action

string

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 retrieve the service account password.

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

set

list / elements=any

Sets the principals specified as principals allowed to retrieve the service account password.

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

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

attributes

dictionary

The attributes to either add, remove, or set on the AD object.

The value of each attribute option should be a dictionary where the key is the LDAP attribute, e.g. firstName, comment and the value is the value, or list of values, to set for that attribute.

The attribute value(s) can either be the raw string, integer, or bool value to add, remove, or set on the attribute in question.

The value can also be a dictionary with the type key set to bytes, date_time, security_descriptor, or raw and the value for this entry under the value key.

The bytes type has a value that is a base64 encoded string of the raw bytes to set.

The date_time type has a value that is the ISO 8601 DateTime string of the DateTime to set. The DateTime will be set as the Microsoft FILETIME integer value which is the number of 100 nanoseconds since 1601-01-01 in UTC.

The security_descriptor type has a value that is the Security Descriptor SDDL string used for the nTSecurityDescriptor attribute.

The raw type is the int, string, or boolean value to set.

String attribute values are compared using a case sensitive match on the AD object being managed.

See LDAP attributes help for more information.

Default: {}

add

dictionary

A dictionary of all the attributes and their value(s) to add to the AD object being managed if they are not already present.

This is used for attributes that can contain multiple values, if the attribute only allows a single value, use set instead.

Default: {}

remove

dictionary

A dictionary of all the attributes and their value(s) to remove from the AD object being managed if they are present.

This is used for attributes that can contain multiple values, if the attribute only allows a single value, use set instead.

Default: {}

set

dictionary

A dictionary of all attributes and their value(s) to set on the AD object being managed.

This will replace any existing values if they do not match the ones being requested.

The order of attribute values are not checked only, only that the values requested are the only values on the object attribute.

Set this to null or an empty list to clear any values for the attribute.

Default: {}

delegates

aliases: principals_allowed_to_delegate

dictionary

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

This is also known as resource-based constrained delegation.

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 a service running as this managed account.

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=any

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.

lookup_failure_action

string

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=any

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

The description of the AD object to set.

This is the value set on the description LDAP attribute.

display_name

string

The display name of the AD object to set.

This is the value of the displayName LDAP attribute.

dns_hostname

string

Specifies the DNS name of the service account.

This is the value set on the dNSHostName LDAP attribute.

This cannot be set when outbound_auth_only=True, otherwise it must be defined.

do_not_append_dollar_to_sam

boolean

Do not automatically append $ to the sam_account_name value.

This only applies when sam_account_name is explicitly set and can be used to create a service account without the $ suffix.

Choices:

  • false ← (default)

  • true

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

yes will enable the service account.

no will disable the service account.

Choices:

  • false

  • true

identity

string

The identity of the AD object used to find the AD object to manage.

This must be specified if; name is not set, when trying to rename the object with a new name, or when trying to move the object into a different path.

The identity can be in the form of a GUID representing the objectGUID value, the userPrincipalName, sAMAccountName, objectSid, or distinguishedName.

If omitted, the AD object to manage is selected by the distinguishedName using the format CN={{ name }},{{ path }}. If path is not defined, the defaultNamingContext is used instead.

When using the microsoft.ad.computer module, the identity will automatically append $ to the end of the sAMAccountName if the provided value did not result in a match and did not already have a $ at the end.

kerberos_encryption_types

dictionary

Specifies the Kerberos encryption types supported the AD service account.

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

Avoid using rc4 or des as they are older an insecure encryption protocols.

To clear all encryption types, use set with an empty list.

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

add

list / elements=string

The encryption types to add to the existing set.

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

Choices:

  • "aes128"

  • "aes256"

  • "des"

  • "rc4"

remove

list / elements=string

The encryption types to remove from the existing set.

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

Choices:

  • "aes128"

  • "aes256"

  • "des"

  • "rc4"

set

list / elements=string

The encryption types to set as the only encryption types allowed by the AD service account.

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

Specify an empty list to remove all encryption types.

Choices:

  • "aes128"

  • "aes256"

  • "des"

  • "rc4"

name

string

The name of the AD object to manage, this is not the sAMAccountName of the object but the LDAP cn or name entry of the object in the path specified. Use identity to select an object to manage by its sAMAccountName.

If identity is specified, and the name of the object found by that identity does not match this value, the object will be renamed.

This must be specified if identity is not set.

outbound_auth_only

boolean

Marks the service account for use with client outbound authentication only.

When set the service account can only be used for client roles only. For example it can only be used for outbound authentication attempts and cannot be used as a target authentication service principal.

If set then dns_hostname cannot be set.

Choices:

  • false ← (default)

  • true

path

string

The path of the OU or the container where the new object should exist in.

If creating a new object, the new object will be created at the path specified. If no path is specified then the defaultNamingContext of the domain will be used as the path for most object types.

If managing an existing object found by identity, the path of the found object will be moved to the one specified by this option. If no path is specified, the object will not be moved.

The modules microsoft.ad.computer, microsoft.ad.user, and microsoft.ad.group have their own default path that is configured on the Active Directory domain controller.

This can be set to the literal value microsoft.ad.default_path which will equal the default value used when creating a new object.

protect_from_deletion

boolean

Marks the object as protected from accidental deletion.

This applies a deny access right from deleting the object normally and the protection needs to be removed before the object can be deleted through the GUI or any other tool outside Ansible.

Using state=absent will still delete the AD object even if it is marked as protected from deletion.

Choices:

  • false

  • true

sam_account_name

string

The sAMAccountName value to set for the service account.

It has a maximum of 256 characters, 15 is advised for older operating systems compatibility.

If ommitted the value is the same as name$ when the service account is created.

Note that service account sAMAccountName values typically end with a $.

By default if the $ suffix is omitted, it will be added to the end. If do_not_append_dollar_to_sam=True then the provided value will be used as is without adding $ to the end.

spn

aliases: spns

dictionary

Specifies the service principal name(s) for the account to add, remove or set.

This is the value set on the servicePrincipalName LDAP attribute.

To clear all service principal names, use set with an empty list.

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

add

list / elements=string

The SPNs to add to servicePrincipalName.

remove

list / elements=string

The SPNs to remove from servicePrincipalName.

set

list / elements=string

The SPNs to set as the only values in servicePrincipalName.

This will clear out any existing SPNs if not in the specified list.

Set to an empty list to clear all SPNs on the AD object.

state

string

Set to present to ensure the AD object exists.

Set to absent to remove the AD object if it exists.

The option name must be set when state=present.

Using absent will recursively remove the AD object and any child objects if it’s a container. It will also remove the AD object even if the object is marked as protected from accidental deletion.

Choices:

  • "absent"

  • "present" ← (default)

trusted_for_delegation

boolean

Specifies whether an account is trusted for Kerberos delegation.

This is also known as unconstrained Kerberos delegation.

This sets the ADS_UF_TRUSTED_FOR_DELEGATION flag in the userAccountControl LDAP attribute.

Choices:

  • false

  • true

upn

string

Configures the User Principal Name (UPN) for the account.

The format is <username>@<domain>.

This is the value set on the userPrincipalName LDAP attribute.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: windows

Target OS/families that can be operated against

Notes

Note

  • This module must be run on a Windows target host with the ActiveDirectory module installed.

  • When matching by identity with a sAMAccountName value, the value should endd with $. If the provided value does not end with $ the module will still attempt to find the service account with the provided value before attempting a fallback lookup with $ appended to the end.

  • Some LDAP attributes can have only a single value set while others can have multiple. Some attributes are also read only and cannot be changed. It is recommended to look at the schema metadata for an attribute where System-Only are read only values and Is-Single-Value are attributes with only 1 value.

  • Attempting to set multiple values to a Is-Single-Value attribute results in undefined behaviour.

  • If running on a server that is not a Domain Controller, credential delegation through CredSSP or Kerberos with delegation must be used or the domain_username, domain_password must be set.

See Also

See also

microsoft.ad.object_info

Gather information an Active Directory object.

microsoft.ad.object

Manage Active Directory objects.

Examples

# A gMSA requires a KDS root key to be created. This key must be valid for
# 10 hours before it can be used. This example creates the key and sets the
# time for 10 hours ago to let it be used immediately. If your environment
# uses multiple DCs you will still need to wait 10 hours for replication to
# occur or target the DC you created the key on. Required Domain Admin or
# Enterprise Admin privileges.
- name: Create KDS root key if not present
  ansible.windows.win_powershell:
    error_action: stop
    script: |
      $Ansible.Changed = $false
      if (-not (Get-KdsRootKey)) {
          Add-KdsRootKey -EffectiveTime ((Get-Date).AddHours(-10))
          $Ansible.Changed = $true
      }

- name: Create gMSA that allows Domain Admins to use
  microsoft.ad.service_account:
    identity: MyGMSA
    dns_hostname: MyGMSA.my_org.local
    description: GMSA for Domin Admins
    state: present
    allowed_to_retrieve_password:
      set:
        - Domain Admins

- name: create gMSA that allows the ITFarmHosts computer account to retrieve the pass
  microsoft.ad.service_account:
    identity: ITFarm1
    dns_hostname: ITFarm1.contoso.com
    allowed_to_retrieve_password:
      set:
        - ITFarmHosts$
    kerberos_encryption_types:
      set:
        - aes128
        - aes256
    spn:
      add:
        - http/ITFarm1.contoso.com/contoso.com
        - http/ITFarm1.contoso.com/contoso
        - http/ITFarm1.contoso.com
        - http/ITFarm1.contoso

- name: Remove gMSA by identity
  microsoft.ad.service_account:
    identity: ITFarm1$
    state: absent

- name: Add SPNs to service account
  microsoft.ad.service_account:
    identity: MySA$
    spn:
      add:
        - HOST/MySA
        - HOST/MySA.domain.test
        - HOST/MySA.domain.test:1234

- name: Remove SPNs on the service account
  microsoft.ad.service_account:
    identity: MySA$
    spn:
      remove:
        - HOST/MySA
        - HOST/MySA.domain.test
        - HOST/MySA.domain.test:1234

- name: Add gMSA with sAMAccountName without $ suffix
  microsoft.ad.service_account:
    identity: MySA
    dns_hostname: MySA.contoso.com
    sam_account_name: MySA
    do_not_append_dollar_to_sam: true

Authors

  • Jordan Borean (@jborean93)