-
-
Notifications
You must be signed in to change notification settings - Fork 173
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
✨ Adds AboutFiltering topic to the ActiveDirectory module (#343)
* Building AD koans * Defining format * Adds AD filter koans * Fixes path. Adds index entry. * Fixes typo * Update PSKoans/Koans/Modules/ActiveDirectory/Introduction/AboutFiltering.Koans.ps1 Co-Authored-By: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com> * Update PSKoans/Koans/Modules/ActiveDirectory/Introduction/AboutFiltering.Koans.ps1 Co-Authored-By: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com> * Update PSKoans/Koans/Modules/ActiveDirectory/Introduction/AboutFiltering.Koans.ps1 Co-Authored-By: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com> * Update PSKoans/Koans/Modules/ActiveDirectory/Introduction/AboutFiltering.Koans.ps1 Co-Authored-By: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com> * Update PSKoans/Koans/Modules/ActiveDirectory/Introduction/AboutFiltering.Koans.ps1 Co-Authored-By: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com> * Fixes typo * Adds Requires directive * Update PSKoans/Koans/Modules/ActiveDirectory/Introduction/AboutFiltering.Koans.ps1 Co-Authored-By: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com> Co-authored-by: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com>
- Loading branch information
1 parent
a1f0830
commit 59fb800
Showing
2 changed files
with
169 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
161 changes: 161 additions & 0 deletions
161
PSKoans/Koans/Modules/ActiveDirectory/Introduction/AboutFiltering.Koans.ps1
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,161 @@ | ||
#Requires -Modules ActiveDirectory | ||
using module PSKoans | ||
[Koan(Position = 101, Module = 'ActiveDirectory')] | ||
param() | ||
<# | ||
About Filtering | ||
The ActiveDirectory module offers support for two different styles of filtering via two different parameters. | ||
The Filter parameter supports a PowerShell-style expression as the filter. The expression is converted into | ||
an LDAP filter by the ActiveDirectory module before being sent to the AD web services gateway. | ||
It is possible, although not easy, to run the filter converter independently. The function in the following | ||
gist does so: | ||
https://gist.github.com/indented-automation/66e07bc76fdb6cf0be6743ed0b24575c | ||
PowerShell-style filters have a number of quirks and occasionally do not behave as they should. Any failures | ||
are assumed to be problems caused when converting the filter. | ||
#> | ||
Describe 'About Filtering' { | ||
|
||
Context 'PowerShell-style filtering' { | ||
<# | ||
The Filter parameter expects a string. Several of the examples use a ScriptBlock to write the filter. | ||
Get-ADUser -Filter { name -eq "Dave" } | ||
The filter above can also be written using single quotes, a literal or non-expanding string. The two filters | ||
are identical except in appearance | ||
Get-ADUser -Filter 'name -eq "Dave"' | ||
Using a script block can be misleading. It implies support for more complex expressions which is not present. | ||
#> | ||
|
||
It 'often uses script blocks in examples' { | ||
# Fill in your username to show that both filters return the same result. | ||
|
||
Get-ADUser -Filter { samAccountName -eq '____' } | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $env:USERNAME | ||
|
||
Get-ADUser -Filter 'samAccountName -eq "____"' | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $env:USERNAME | ||
} | ||
|
||
It 'expands variables in literal strings' { | ||
<# | ||
Variable expansion in filters is a feature of the ActiveDirectory module. | ||
Sub-expressions are not supported. Values from providers, such as the Environment provider, for example | ||
$env:USERNAME, are not supported. | ||
The variable below is in single quotes. PowerShell will not expand this variable, the ActiveDirectory | ||
module will. | ||
#> | ||
|
||
$username = '____' | ||
Get-ADUser -Filter 'samAccountName -eq $username' | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $env:USERNAME | ||
} | ||
|
||
It 'is often useful to let the Active Directory module expand a variable' { | ||
<# | ||
The AD module uses a mixture of hard-coded data and information from the AD schema to figure out the | ||
format an attribute expects in a filter. | ||
For example, if a filter is written based on a SID the ActiveDirectory module will happily convert the | ||
SID into an appropriate format. The author of the query no longer needs to care about exactly | ||
how the filter should be written. | ||
The same approach can be used for dates, GUIDs, byte arrays, and so on. | ||
#> | ||
|
||
$username = '____' | ||
# The statement below will only work on Windows | ||
$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User | ||
Get-ADUser -Filter 'objectSID -eq $sid' | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $username | ||
|
||
<# | ||
The SID will be converted into an appropriate format for an LDAP filter. Similar to the example below: | ||
(objectSid=\01\05\00\00\00\00\00\05\15\00\00\00\11\22\33\44\55\66\77\88\99\AA\BB\CC\DD\EE\FF\00) | ||
#> | ||
} | ||
|
||
It 'can expand properties of objects from variables' { | ||
<# | ||
Filters do not support sub-expressions but the Filter parameter does support property expansion. | ||
The catch is that the ActiveDirectory module can only expand properties of .NET types. It cannot read | ||
NoteProperty values from PSCustomObject, it cannot read NoteProperty members added by Add-Member. | ||
Get-Item will return a System.IO.DirectoryInfo object if the path is a directory. The DirectoryInfo | ||
object has a Name property which can be expanded. | ||
#> | ||
|
||
$homeDirectory = Get-Item -Path '____' | ||
Get-ADUser -Filter 'samAccountName -eq $homeDirectory.Name' | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $env:USERNAME | ||
} | ||
|
||
It 'can sometimes be better to let PowerShell expand variables' { | ||
<# | ||
In some cases it can be better to treat the filter as a string and let PowerShell expand any | ||
variable values. | ||
If PowerShell is expanding values, quotes must be added around the value in the filter. | ||
#> | ||
|
||
$username = '____' | ||
Get-ADUser -Filter "samAccountName -eq '$username'" | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $env:USERNAME | ||
} | ||
|
||
It 'has aliases for certain attributes' { | ||
<# | ||
The ActiveDirectory module provides aliases for a large number of attributes. In some cases this is | ||
just convenient. In others, it is used to hide complexity. | ||
Enabled is a commonly used alias which masks a query against the userAccountControl attribute. | ||
#> | ||
|
||
$username = '____' | ||
Get-ADUser -Filter 'samAccountName -eq $username -and Enabled -eq $true' | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $env:USERNAME | ||
|
||
<# | ||
Whether or not an account is enabled is described by a single flag in the userAccountControl attribute. | ||
The query used above can also be written as shown below. | ||
#> | ||
|
||
|
||
Get-ADUser -Filter 'samAccountName -eq $username -and -not userAccountControl -band 2' | | ||
Select-Object -ExpandProperty SamAccountName | | ||
Should -Be $env:USERNAME | ||
|
||
<# | ||
In both cases, the filter is converted to the following LDAP filter. | ||
(&(samAccountName=<Username>)(!(userAccountControl:1.2.840.113556.1.4.803:=2))) | ||
Other common aliases include LastLogonDate, an alias for lastLogonTimestamp. | ||
The possible aliases can be read from the ActiveDirectory module although they are not easily | ||
available. The function in in the gist below does so: | ||
https://gist.github.com/indented-automation/629a00167a74e9cb3329eabd6662bc0c | ||
#> | ||
} | ||
} | ||
} |