microsoft.ad.kds_root_key module – Manages a KDS root key in a domain

Note

This module is part of the microsoft.ad collection (version 1.11.0).

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.

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

New in microsoft.ad 1.11.0

Synopsis

  • Ensure that a KDS root key is present or absent, performing changes only when necessary.

Parameters

Parameter

Comments

effective_time_hours

integer

The number of hours to wait before the key is effective.

This is recommended to be set to a value greater than 0, so that the key can be replicated to all domain controllers. Using a key before it has been replicated will result in an error.

If set to 0, the key will be effective immediately.

Default: 10

key_id

string

The ID of the key that should be removed when state is absent.

The ID of the key that should be matched when state is present and match_by is key_id. Pay attention that the created key will not have the specified ID, the key_id is used for matching existing keys only.

match_by

string

The method used to find key for idempotency check when state=present.

When any, a key will only be created when no key exists.

When key_id, key_id must be set and will create the key if one with that id does not already exist. The newly created key will not have the specified ID.

When never, the key will always be created.

Choices:

  • "any" ← (default)

  • "key_id"

  • "never"

state

string

Whether to ensure a key is present or absent.

Note that Microsoft warns against removing KDS root keys, since it can lead to failed services and accounts.

Choices:

  • "present" ← (default)

  • "absent"

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

  • This module must be run on a Windows target host.

  • This module requires the Domain Administrator or Enterprise Administrator role to manage KDS keys.

Examples

- name: Create a new KDS root key with an effective time of 10 hours, if one does not already exist
  microsoft.ad.kds_root_key:
    effective_time_hours: 10
    match_by: any

- name: Create a new KDS root key immediately, even if one already exists
  microsoft.ad.kds_root_key:
    effective_time_hours: 0
    match_by: never

- name: Create a new KDS root key immediately, if a key with the specified ID does not already exist
  microsoft.ad.kds_root_key:
    effective_time_hours: 0
    match_by: key_id
    key_id: 2ad622aa-39f0-0583-9cd7-cc8fc85bd2f5

- name: Remove a KDS root key with the specified ID, if it exists
  microsoft.ad.kds_root_key:
    state: absent
    key_id: 2ad622aa-39f0-0583-9cd7-cc8fc85bd2f5

Return Values

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

Key

Description

key_id

string

The ID of the newly created or removed KDS root key.

Returned: always

Sample: "12345678-1234-1234-1234-123456789012"

Authors

  • Mike Morency (@mikemorency)