DSCResources/MSFT_ADKDSKey/en-US/about_ADKDSKey.help.txt

.NAME
    ADKDSKey
 
.DESCRIPTION
    The ADKDSKey DSC resource will manage KDS Root Keys within Active Directory. The KDS root keys are used to begin generating Group Managed Service Account (gMSA) passwords.
 
    ## Requirements
 
    * Target machine must be running Windows Server 2008 R2 or later.
 
.PARAMETER EffectiveTime
    Key - String
    Specifies the Effective time when a KDS root key can be used. There is a 10 hour minimum from creation date to allow active directory to properly replicate across all domain controllers. For this reason, the date must be set in the future for creation. While this parameter accepts a string, it will be converted into a DateTime object. This will also try to take into account cultural settings. Example: '05/01/1999 13:00 using default or 'en-US' culture would be May 1st, but using 'de-DE' culture would be 5th of January. The culture is automatically pulled from the operating system and this can be checked using 'Get-Culture'.
 
.PARAMETER Ensure
    Write - String
    Allowed values: Present, Absent
    Specifies if this KDS Root Key should be present or absent. Default value is 'Present'.
 
.PARAMETER AllowUnsafeEffectiveTime
    Write - Boolean
    This option will allow you to create a KDS root key if EffectiveTime is set in the past. This may cause issues if you are creating a Group Managed Service Account right after you create the KDS Root Key. In order to get around this, you must create the KDS Root Key using a date in the past. This should be used at your own risk and should only be used in lab environments.
 
.PARAMETER ForceRemove
    Write - Boolean
    This option will allow you to remove a KDS root key if there is only one key left. It should not break your Group Managed Service Accounts (gMSA), but if the gMSA password expires and it needs to request a new password, it will not be able to generate a new password until a new KDS Root Key is installed and ready for use. Because of this, the last KDS Root Key will not be removed unless this option is specified.
 
.PARAMETER DistinguishedName
    Read - String
    Returns the Distinguished Name (DN) of the KDS root key. The KDS Root Key is stored in 'CN=Master Root Keys,CN=Group Key Distribution Service,CN=Services,CN=Configuration' at the Forest level. This is also why replication needs 10 hours to occur before using the KDS Root Key as a safety measure.
 
.PARAMETER CreationTime
    Read - DateTime
    Returns the Creation date and time of the KDS root key for informational purposes.
 
.PARAMETER KeyId
    Read - String
    Returns the KeyID of the KDS root key. This is the Common Name (CN) within Active Directory and is required to build the Distinguished Name.
 
.EXAMPLE 1
 
This configuration will create a KDS root key. If the date is set to a time
slightly ahead in the future, the key won't be usable for at least 10 hours
from the creation time.
 
Configuration ADKDSKey_CreateKDSRootKey_Config
{
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        ADKDSKey 'ExampleKDSRootKey'
        {
            Ensure = 'Present'
            EffectiveTime = '1/1/2030 13:00'
            # Date must be set to at time in the future
        }
    }
}
 
.EXAMPLE 2
 
This configuration will create a KDS root key in the past. This will allow
the key to be used right away, but if all the domain controllers haven't
replicated yet, there may be issues when retrieving the gMSA password.
Use with caution
 
Configuration ADKDSKey_CreateKDSRootKeyInPast_Config
{
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        ADKDSKey 'ExampleKDSRootKeyInPast'
        {
            Ensure = 'Present'
            EffectiveTime = '1/1/1999 13:00'
            AllowUnsafeEffectiveTime = $true # Use with caution
        }
    }
}
 
.EXAMPLE 3
 
This configuration will remove the last KDS root key. Use with caution.
If gMSAs are installed on the network, they will not be able to reset
their passwords and it may cause services to fail.
 
Configuration ADKDSKey_CreateKDSRootKeyRemoveLastKey_Config
{
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        ADKDSKey 'ExampleKDSRootKeyForceRemove'
        {
            Ensure = 'Absent'
            EffectiveTime = '1/1/2030 13:00'
            ForceRemove = $true # This will allow you to remove the key if it's the last one
        }
    }
}