ADFineGrainedPasswordPolicy: New resource proposal

[fl0p3k]

Description

New resource to support fine grained password policies for AD Principals.

Proposed properties

The new resource will be using the Active Directory module commands below:

Get-ADFineGrainedPasswordPolicy
Get-ADFineGrainedPasswordPolicySubject
New-ADFineGrainedPasswordPolicy
Set-ADFineGrainedPasswordPolicy
Remove-ADFineGrainedPasswordPolicy
Add-ADFineGrainedPasswordPolicySubject
Remove-ADFineGrainedPasswordPolicySubject

The resource will contain the following properties:

Parameter	Attribute	DataType	Description	Allowed Values
Name	Key	String	Specifies an Active Directory fine-grained password policy object name.
Precedence	Required	UInt32	Specifies a value that defines the precedence of a fine-grained password policy among all fine-grained password policies.
DisplayName	Write	String	Specifies the display name of the object.
Description	Write	String	Specifies a description for the object.
Subjects	Write	String Array	Specifies the ADPrincipal names the policy is to be applied to, overwrites all existing.
Ensure	Write	String	Specifies whether the fine-grained password policy should be present or absent. Default value is 'Present'.	"Present", "Absent"
ComplexityEnabled	Write	Boolean	Specifies whether password complexity is enabled for the password policy.
LockoutDuration	Write	String	Specifies the length of time that an account is locked after the number of failed login attempts exceeds the lockout threshold. The lockout duration must be greater than or equal to the lockout observation time for a password policy. The value must be a string representation of a TimeSpan value.
LockoutObservationWindow	Write	String	Specifies the maximum time interval between two unsuccessful login attempts before the number of unsuccessful login attempts is reset to 0. The lockout observation window must be smaller than or equal to the lockout duration for a password policy. The value must be a string representation of a TimeSpan value.
LockoutThreshold	Write	UInt32	Specifies the number of unsuccessful login attempts that are permitted before an account is locked out.
MinPasswordAge	Write	String	Specifies the minimum length of time before you can change a password. The value must be a string representation of a TimeSpan value.
MaxPasswordAge	Write	String	Specifies the maximum length of time that you can have the same password. The value must be a string representation of a TimeSpan value.
MinPasswordLength	Write	UInt32	Specifies the minimum number of characters that a password must contain.
PasswordHistoryCount	Write	UInt32	Specifies the number of previous passwords to save.
ReversibleEncryptionEnabled	Write	Boolean	Specifies whether the directory must store passwords using reversible encryption.
ProtectedFromAccidentalDeletion	Write	Boolean	Specifies whether to prevent the object from being deleted.
DomainController	Write	String	Specifies the Active Directory Domain Services instance to connect to.
Credential	Write	MSFT_Credential	Specifies the user account credentials to use to perform this task.

Special considerations or limitations

[X-Guardian]

Hi @fl0p3k, thanks very much for this!

To help create a high quality resource that follows the patterns used in this module, can you fill out the proposed properties in this issue description, and detail what Cmdlets the resource calls. We can then discuss here whether any changes are needed before you finalise your PR.

[johlju]

The property DisplayName is set to type qualifier Write and not Required, what is your thought here, that DisplayName is set to the Name if not provided in a configuration?

The property ComplexityEnabled says in the description ...is enabled for the default password policy, what default password policy is that? Is the description meant to say that it is enabling this make use of the default password policy? 🤔

Would it be possible to skip the Credential parameter and instead make use of the built-in PsDscRunAsCredential parameter? Less logic to test and maintain. 🤔

[X-Guardian]

Hi @fl0p3k , I've put the properties in a table to be easier to read.

Initial comments:

1. As this resource can be added and deleted, the resource needs to have an Ensure property, with allowed values of Present or Absent. It will therefore need to additionally use the Remove-ADFineGrainedPasswordPolicy cmdlet.
2. The resource should manage subjects that the policy applies to using the Add-ADFineGrainedPasswordPolicySubject and Remove-ADFineGrainedPasswordPolicySubject cmdlets. I would suggest the following additional properties for this: Subjects, SubjectsToInclude and SubjectsToExclude. Subjects should enforce the policy to only apply to the specified list of identities. SubjectsToInclude should apply the policy to the specified identities, but not remove any additional identities that the policy applies to. SubjectsToExclude should remove the policy from applying to the specified identities, but not change any other identities the policy applies to. This follows the model used in the ADGroup resource.
3. The LockoutDuration, LockoutObservationWindow, MaxPasswordAge and MinPasswordAge cmdlet parameters are actually TimeSpan objects. Can we use the model used in xWebAdministration where String representations of these are used, rather than using Uint32?
4. The Description parameter should be added to the resource.
5. Can the property descriptions be based on the text from the New-ADFineGrainedPasswordPolicy Cmdlet documentation.

[fl0p3k]

The property DisplayName is set to type qualifier Write and not Required, what is your thought here, that DisplayName is set to the Name if not provided in a configuration?

The property ComplexityEnabled says in the description ...is enabled for the default password policy, what default password policy is that? Is the description meant to say that it is enabling this make use of the default password policy? 🤔

Would it be possible to skip the Credential parameter and instead make use of the built-in PsDscRunAsCredential parameter? Less logic to test and maintain. 🤔

I am not sure DisplayName is required since the underlying ActiveDirectory cmdlet does not require it.

As for the complexity enabled option I simply had a typo in the context. Corrected.

Regarding the credentials, when I look at the syntax of the module, I do see it as PsDscRunAsCredential:

ADFineGrainedPasswordPolicy [String] #ResourceName { Name = [string] [ComplexityEnabled = [bool]] [Credential = [PSCredential]] [DependsOn = [string[]]] [DisplayName = [string]] [DomainController = [string]] [LockoutDuration = [UInt32]] [LockoutObservationWindow = [UInt32]] [LockoutThreshold = [UInt32]] [MaxPasswordAge = [UInt32]] [MinPasswordAge = [UInt32]] [MinPasswordLength = [UInt32]] [PasswordHistoryCount = [UInt32]] [Precedence = [UInt32]] [ProtectedFromAccidentalDeletion = [bool]] [PsDscRunAsCredential = [PSCredential]] [ReversibleEncryptionEnabled = [bool]] }

[fl0p3k]

Hi @fl0p3k , I've put the properties in a table to be easier to read.

Initial comments:

1. As this resource can be added and deleted, the resource needs to have an Ensure property, with allowed values of Present or Absent. It will therefore need to additionally use the Remove-ADFineGrainedPasswordPolicy cmdlet.
2. The resource should manage subjects that the policy applies to using the Add-ADFineGrainedPasswordPolicySubject and Remove-ADFineGrainedPasswordPolicySubject cmdlets. I would suggest the following additional properties for this: Subjects, SubjectsToInclude and SubjectsToExclude. Subjects should enforce the policy to only apply to the specified list of identities. SubjectsToInclude should apply the policy to the specified identities, but not remove any additional identities that the policy applies to. SubjectsToExclude should remove the policy from applying to the specified identities, but not change any other identities the policy applies to. This follows the model used in the ADGroup resource.
3. The LockoutDuration, LockoutObservationWindow, MaxPasswordAge and MinPasswordAge cmdlet parameters are actually TimeSpan objects. Can we use the model used in xWebAdministration where String representations of these are used, rather than using Uint32?
4. The Description parameter should be added to the resource.
5. Can the property descriptions be based on the text from the New-ADFineGrainedPasswordPolicy Cmdlet documentation.

Thanks for the feedback and comments. As for the time span parameters, this module was closely based off the existing ADDomainDefaultPasswordPolicy DscResource in this module. I'm not sure changing the parameter type would be good unless we change both to ensure consistency for the operator experience, plus any existing configuration dependence would break if we did.

ADDomainDefaultPasswordPolicy [String] #ResourceName
{
    DomainName = [string]
    [ComplexityEnabled = [bool]]
    [Credential = [PSCredential]]
    [DependsOn = [string[]]]
    [DomainController = [string]]
    [LockoutDuration = [UInt32]]
    [LockoutObservationWindow = [UInt32]]
    [LockoutThreshold = [UInt32]]
    [MaxPasswordAge = [UInt32]]
    [MinPasswordAge = [UInt32]]
    [MinPasswordLength = [UInt32]]
    [PasswordHistoryCount = [UInt32]]
    [PsDscRunAsCredential = [PSCredential]]
    [ReversibleEncryptionEnabled = [bool]]
}

ADFineGrainedPasswordPolicy [String] #ResourceName
{
    Name = [string]
    [ComplexityEnabled = [bool]]
    [Credential = [PSCredential]]
    [DependsOn = [string[]]]
    [DisplayName = [string]]
    [DomainController = [string]]
    [LockoutDuration = [UInt32]]
    [LockoutObservationWindow = [UInt32]]
    [LockoutThreshold = [UInt32]]
    [MaxPasswordAge = [UInt32]]
    [MinPasswordAge = [UInt32]]
    [MinPasswordLength = [UInt32]]
    [PasswordHistoryCount = [UInt32]]
    [Precedence = [UInt32]]
    [ProtectedFromAccidentalDeletion = [bool]]
    [PsDscRunAsCredential = [PSCredential]]
    [ReversibleEncryptionEnabled = [bool]]
}

[X-Guardian]

The ADDomainDefaultPasswordPolicy was written four years ago, and is on my list of resources needing a refactor. I've discussed the TimeSpan properties with @johlju, and we would prefer for them to be TimeSpan string representations, as implemented by xWebAdministration. We will raise a future breaking change PR to update the ADDomainDefaultPasswordPolicy resource to use the same type.

[X-Guardian]

@fl0p3k, can you please update the initial issue comment with the final list of cmdlets and properties.

[fl0p3k]

@fl0p3k, can you please update the initial issue comment with the final list of cmdlets and properties.

Issue updated

[X-Guardian]

Can you add Remove-ADFineGrainedPasswordPolicy to the cmdlet list and the Description parameter.

Please also update the property descriptions where applicable from the New-ADFineGrainedPasswordPolicy cmdlet documentation.

[fl0p3k]

Can you add Remove-ADFineGrainedPasswordPolicy to the cmdlet list and the Description parameter.

Please also update the property descriptions where applicable from the New-ADFineGrainedPasswordPolicy cmdlet documentation.

Thanks added. I also updated the descriptions

[X-Guardian]

Regarding the descriptions, can you check again? Lost of them still aren't correct.

• For the three Subjects, properties, base the description on the Subjects property in Add-ADFineGrainedPasswordPolicySubject.
• Remove the 'TimeSpan minutes/days' comments which are no longer valid.
• ComplexityEnabled description isn't correct.
• LockoutObservationWindow description isn't correct.
• MinPasswordAge description isn't correct.
• MinPasswordLength description isn't correct. etc.

[X-Guardian]

@fl0p3k, can you please add the Description property to the proposal, and your PR. The spelling of ADPrincipal is also not correct, so can you fix that too. Thanks.