microsoft.ad.offline_join module – Get the Offline Domain Join BLOB

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

Synopsis

  • Used to get the Offline Domain Join BLOB.

  • This BLOB is used to join computers to a domain without any network access.

Requirements

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

  • ActiveDirectory PowerShell module

Parameters

Parameter

Comments

blob_path

string

If set, will store the blob bytes into a file at this path.

This will not create the parent directory specified if it does not exist.

The existence of this file is also used as an idempotency check, if the file already exists the blob will not be regenerated.

If specified the module return value blob will be null.

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.

identity

string

The identity of the computer object used to generate the offline join blob for.

This is mutually exclusive with name and (path).

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

This option or name must be specified.

name

string

The name of the computer object used to generate the offline join blob for.

This is mutually exclusive with identity.

The name is combined with path to find the AD computer object that matches the DistinguishedName CN={{ name}},{{ path }}.

This option or identity must be specified.

path

string

The path where the computer object specified by name is stored.

By default the default computer path defined in AD is used, for example CN=Computers,DC=domain,DC=com.

provision_root_ca_certs

boolean

Adds all the root Certificate Authority certificates on the local machine and adds them to the blob.

Choices:

  • false ← (default)

  • true

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: none

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

  • For more information on Offline Domain Join see the step-by-step guide.

  • There is no way to specify specific credentials to communicate with the domain controller when creating the blob. Use become with net credentials if the current user cannot authenticate itself and bypass the double hop problem.

  • The data returned by this module is very sensitive. If not using blob_path then no_log=True should be used on the task to avoid the data being leaked.

  • This module will always report a change unless blob_path is specified. If the path is specified then then the existence of that path will act as the idempotency check.

  • Generating a new blob will reset the password of the computer object, take care that this isn’t called under a computer account that has already been joined.

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

See Also

See also

microsoft.ad.domain

Ensures the existence of a Windows domain.

microsoft.ad.membership

Manage domain/workgroup membership for a Windows host.

microsoft.ad.computer

Manage Active Directory computer objects.

Examples

- name: create computer object
  microsoft.ad.computer:
    name: MyComputer
    state: present
  register: computer_obj

- name: create offline blob
  microsoft.ad.offline_join:
    identity: '{{ computer_obj.object_guid }}'
  when: computer_obj is changed
  register: offline_blob
  no_log: true

- name: join host by offline blob
  microsoft.ad.membership:
    offline_join_blob: '{{ offline_blob.blob }}'
    state: domain
    reboot: true
  delegate_to: member-host

- name: create blob and store it in a file on the target host
  microsoft.ad.offline_join:
    name: MyComputer
    path: OU=Production,DC=domain,DC=com
    blob_path: C:\Windows\TEMP\offline_blob

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

blob

string

The blob as a base64 string.

This value is empty when running in check mode.

This value is null when blob_path is specified.

This value is highly sensitive as it contains the credentials and other authentication data needed for an offline join.

Returned: always

Sample: "ARAIAMzMzMygCAAAAAAAAAAAAgABAAAA"

Authors

  • Jordan Borean (@jborean93)