Scripts/Reskit9/All Resources/xPSDesiredStateConfiguration/DSCResources/MSFT_xGroupResource/MSFT_xGroupResource.psm1
|
# A global variable that contains localized messages. data LocalizedData { # culture="en-US" ConvertFrom-StringData @' GroupWithName=Group: {0} RemoveOperation=Remove AddOperation=Add SetOperation=Set ConfigurationStarted=Configuration of group {0} started. ConfigurationCompleted=Configuration of group {0} completed successfully. GroupCreated=Group {0} created successfully. GroupUpdated=Group {0} properties updated successfully. GroupRemoved=Group {0} removed successfully. NoConfigurationRequired=Group {0} exists on this node with the desired properties. No action required. NoConfigurationRequiredGroupDoesNotExist=Group {0} does not exist on this node. No action required. CouldNotFindPrincipal=Could not find a principal with the provided name [{0}] MembersAndIncludeExcludeConflict=The {0} and {1} and/or {2} parameters conflict. The {0} parameter should not be used in any combination with the {1} and {2} parameters. MembersIsNull=The Members parameter value is null. The {0} parameter must be provided if neither {1} nor {2} is provided. IncludeAndExcludeConflict=The principal {0} is included in both {1} and {2} parameter values. The same principal must not be included in both {1} and {2} parameter values. InvalidGroupName=The name {0} cannot be used. Names may not consist entirely of periods and/or spaces, or contain these characters: {1} GroupExists=A group with the name {0} exists. GroupDoesNotExist=A group with the name {0} does not exist. PropertyMismatch=The value of the {0} property is expected to be {1} but it is {2}. MembersNumberMismatch=Property {0}. The number of provided unique group members {1} is different from the number of actual group members {2}. MembersMemberMismatch=At least one member {0} of the provided {1} parameter does not have a match in the existing group {2}. MemberToExcludeMatch=At least one member {0} of the provided {1} parameter has a match in the existing group {2}. ResolvingLocalAccount=Resolving {0} as a local account. RedirectDomain=Redirecting to domain {0} for account {1}. ResolvingDomainAccount=Resolving {0} in the {1} domain. ResolvingUser=Resolving {0} as a user. ResolvingGroup=Resolving {0} as a group. ResolvingComputer=Resolving {0} as a computer. DomainCredentialsRequired=Credentials are required to resolve the domain account {0}. '@ } Add-Type -AssemblyName 'System.DirectoryServices.AccountManagement' Import-LocalizedData LocalizedData -FileName MSFT_xGroupResource.strings.psd1 <# .Synopsis The Get-TargetResource cmdlet. #> function Get-TargetResource { [OutputType([System.Collections.Hashtable])] param ( [parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [System.String] $GroupName ) Set-StrictMode -Version Latest ValidateGroupName -GroupName $GroupName # Try to find a group by its name. $principalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList ([System.DirectoryServices.AccountManagement.ContextType]::Machine) $group = $null try { $group = [System.DirectoryServices.AccountManagement.GroupPrincipal]::FindByIdentity($principalContext, $GroupName); if($group -ne $null) { # The group is found. Enumerate all group members. $members = [String[]]@(EnumerateMembers -Group $group) # Return all group properties and Ensure="Present". $returnValue = @{ GroupName = $group.Name; Ensure = "Present"; Description = $group.Description; Members = [System.String[]] $members; } return $returnValue; } # The group is not found. Return Ensure=Absent. return @{ GroupName = $GroupName; Ensure = "Absent"; } } finally { if($group -ne $null) { $group.Dispose(); } $principalContext.Dispose(); } } <# .Synopsis The Set-TargetResource cmdlet. #> function Set-TargetResource { [CmdletBinding(SupportsShouldProcess=$true)] param ( [parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [System.String] $GroupName, [ValidateSet("Present", "Absent")] [System.String] $Ensure = "Present", [System.String] $Description, [System.String[]] $Members, [System.String[]] $MembersToInclude, [System.String[]] $MembersToExclude, [ValidateNotNullOrEmpty()] [System.Management.Automation.PSCredential] $Credential ) Set-StrictMode -Version Latest ValidateGroupName -GroupName $GroupName # store disposable objects in a list for cleanup later. # This is needed for the case where domain redirection is required # to resolve an account. Since the lifetime of the resolved # principal is the same as the PrincipalContext, we need to # ensure the PrincipalContext remains live until we're done. $disposables = New-Object System.Collections.ArrayList try { # PrincipalContext for domain account resolution $credentialPrincipalContext = $null # PrincipalContext for local account resolution $localPrincipalContext = $null $group = $null [System.Net.NetworkCredential] $networkCredential = $null if($PSBoundParameters.ContainsKey('Credential')) { $networkCredential = $Credential.GetNetworkCredential(); $credentialPrincipalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList ([System.DirectoryServices.AccountManagement.ContextType]::Domain, $networkCredential.Domain, $networkCredential.UserName, $networkCredential.Password) $disposables.Add($credentialPrincipalContext) | out-null } # Create local machine context. $localPrincipalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList ([System.DirectoryServices.AccountManagement.ContextType]::Machine) $disposables.Add($localPrincipalContext) | out-null # Try to find a group by its name. $group = [System.DirectoryServices.AccountManagement.GroupPrincipal]::FindByIdentity($localPrincipalContext, $GroupName); $disposables.Add($group) | out-null if($Ensure -eq "Present") { # Ensure is set to "Present". [bool] $whatIfShouldProcess = $true; [bool] $groupExists = $false; [bool] $saveChanges = $false; if($group -eq $null) { # A group does not exist. Check WhatIf for adding a group. $whatIfShouldProcess = $pscmdlet.ShouldProcess($LocalizedData.GroupWithName -f $GroupName, $LocalizedData.AddOperation); } else { # A group exists. $groupExists = $true; # Check WhatIf for setting a group. $whatIfShouldProcess = $pscmdlet.ShouldProcess($LocalizedData.GroupWithName -f $GroupName, $LocalizedData.SetOperation); } if($whatIfShouldProcess) { if(-not $groupExists) { # The group with the provided name does not exist. Add a new group. $group = New-Object System.DirectoryServices.AccountManagement.GroupPrincipal -ArgumentList $localPrincipalContext $group.Name = $GroupName; $group.Save(); } # Set group properties. if($PSBoundParameters.ContainsKey('Description') -and (-not $groupExists -or $Description -ne $group.Description)) { $group.Description = $Description; $saveChanges = $true; } if($PSBoundParameters.ContainsKey('Members')) { if($PSBoundParameters.ContainsKey('MembersToInclude') -or $PSBoundParameters.ContainsKey('MembersToExclude')) { # If Members are provided, Include and Exclude are not allowed. ThrowInvalidArgumentError -ErrorId "GroupTestCmdlet_MembersPlusIncludeOrExcludeConflict" -ErrorMessage ($LocalizedData.MembersAndIncludeExcludeConflict -f "Members","MembersToInclude","MembersToExclude") } if($Members -eq $null) { ThrowInvalidArgumentError -ErrorId "GroupTestCmdlet_MembersIsNull" -ErrorMessage ($LocalizedData.MembersIsNull -f "Members","MembersToInclude","MembersToExclude") } # Remove duplicate names as strings. $Members = [String[]]@(RemoveDuplicates -Members $Members); # Resolve the names to actual principal objects. [System.DirectoryServices.AccountManagement.Principal[]]$membersPrincipals = ResolveNamesToPrincipals -LocalPrincipalContext $localPrincipalContext -CredentialPrincipalContext $credentialPrincipalContext -ObjectNames $Members -NetworkCredential $networkCredential -Disposables $disposables # Remove all possible duplicates. [System.DirectoryServices.AccountManagement.Principal[]]$membersPrincipals = RemoveDuplicatePrincipals -Members $membersPrincipals # Find what group members must be deleted. $objectsToRemove = @(); foreach($groupMember in $group.Members) { $groupMemberFound = $false; for($m = 0; $m -lt $membersPrincipals.Count; $m++) { if($groupMember -eq $membersPrincipals[$m]) { $groupMemberFound = $true; break; } } if(-not $groupMemberFound) { # Select this group for deletion. $objectsToRemove += $groupMember; } } # Find what group members must be added. $objectsToAdd = @(); for($m = 0; $m -lt $membersPrincipals.Count; $m++) { $membersFound = $false; foreach($groupMember in $group.Members) { if($groupMember -eq $membersPrincipals[$m]) { $membersFound = $true; break; } } if(-not $membersFound) { # Select this group for addition. $objectsToAdd += $membersPrincipals[$m]; } } if($objectsToAdd.Length -gt 0) { # Make changes to the group. AddGroupMembers -Group $group -Principals $objectsToAdd $saveChanges = $true; } if($objectsToRemove.Length -gt 0) { # Make changes to the group. RemoveGroupMembers -Group $group -Principals $objectsToRemove $saveChanges = $true; } } else { [System.DirectoryServices.AccountManagement.Principal[]]$membersToIncludePrincipals = $null; [System.DirectoryServices.AccountManagement.Principal[]]$membersToExcludePrincipals = $null; if($PSBoundParameters.ContainsKey('MembersToInclude')) { $MembersToInclude = [String[]]@(RemoveDuplicates -Members $MembersToInclude); # Resolve the names to actual principal objects. $membersToIncludePrincipals = ResolveNamesToPrincipals -LocalPrincipalContext $localPrincipalContext -CredentialPrincipalContext $credentialPrincipalContext -ObjectNames $MembersToInclude -NetworkCredential $networkCredential -Disposables $disposables # Remove all possible duplicates. [System.DirectoryServices.AccountManagement.Principal[]]$membersToIncludePrincipals = RemoveDuplicatePrincipals -Members $membersToIncludePrincipals } if($PSBoundParameters.ContainsKey('MembersToExclude')) { $MembersToExclude = [String[]]@(RemoveDuplicates -Members $MembersToExclude); # Resolve the names to actual principal objects. $membersToExcludePrincipals = ResolveNamesToPrincipals -LocalPrincipalContext $localPrincipalContext -CredentialPrincipalContext $credentialPrincipalContext -ObjectNames $MembersToExclude -NetworkCredential $networkCredential -Disposables $disposables # Remove all possible duplicates. [System.DirectoryServices.AccountManagement.Principal[]]$membersToExcludePrincipals = RemoveDuplicatePrincipals -Members $membersToExcludePrincipals } if($membersToIncludePrincipals -ne $null -and $membersToExcludePrincipals -ne $null) { # Both MembersToInclude and MembersToExlude were provided. Check if they have common principals. foreach($includePrincipal in $membersToIncludePrincipals) { foreach($excludePrincipal in $membersToExcludePrincipals) { if($includePrincipal -eq $excludePrincipal) { ThrowInvalidArgumentError -ErrorId "GroupSetCmdlet_IncludeAndExcludeConflict" -ErrorMessage ($LocalizedData.IncludeAndExcludeConflict -f $includePrincipal.SamAccountName,"MembersToInclude", "MembersToExclude") } } } } if($membersToIncludePrincipals -ne $null) { # Find what group members must be added. $objectsToAdd = @(); for($m = 0; $m -lt $membersToIncludePrincipals.Count; $m++) { $membersFound = $false; foreach($groupMember in $group.Members) { if($groupMember -eq $membersToIncludePrincipals[$m]) { $membersFound = $true; break; } } if(-not $membersFound) { # Select this group for addition. $objectsToAdd += $membersToIncludePrincipals[$m]; } } if($objectsToAdd.Length -gt 0) { # Make changes to the group. AddGroupMembers -Group $group -Principals $objectsToAdd $saveChanges = $true; } } if($membersToExcludePrincipals -ne $null) { # Find what group members must be deleted. $objectsToRemove = @(); for($m = 0; $m -lt $membersToExcludePrincipals.Count; $m++) { $groupMemberFound = $false; foreach($groupMember in $group.Members) { if($membersToExcludePrincipals[$m] -eq $groupMember) { # Select this group for deletion. $objectsToRemove += $groupMember; break; } } } if($objectsToRemove.Length -gt 0) { # Make changes to the group. RemoveGroupMembers -Group $group -Principals $objectsToRemove $saveChanges = $true; } } } if($saveChanges) { $group.Save(); # Send an operation success verbose message. if($groupExists) { Write-Verbose -Message ($LocalizedData.GroupUpdated -f $GroupName) } else { Write-Verbose -Message ($LocalizedData.GroupCreated -f $GroupName) } } else { Write-Verbose -Message ($LocalizedData.NoConfigurationRequired -f $GroupName) } } } else { # Ensure is set to "Absent". if($group -ne $null) { # The group exists. if($pscmdlet.ShouldProcess($LocalizedData.GroupWithName -f $GroupName, $LocalizedData.RemoveOperation)) { # Remove the group by the provided name. $group.Delete(); } Write-Verbose -Message ($LocalizedData.GroupRemoved -f $GroupName) } else { Write-Verbose -Message ($LocalizedData.NoConfigurationRequiredGroupDoesNotExist -f $GroupName) } } } finally { foreach ($disposable in $disposables) { $disposable.Dispose() } } } <# .Synopsis The Test-TargetResource cmdlet is used to validate if the resource is in a state as expected in the instance document. #> function Test-TargetResource { [OutputType([System.Boolean])] param ( [parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [System.String] $GroupName, [ValidateSet("Present", "Absent")] [System.String] $Ensure = "Present", [System.String] $Description, [System.String[]] $Members, [System.String[]] $MembersToInclude, [System.String[]] $MembersToExclude, [ValidateNotNullOrEmpty()] [System.Management.Automation.PSCredential] $Credential ) Set-StrictMode -Version Latest ValidateGroupName -GroupName $GroupName # store disposable objects in a list for cleanup later. # This is needed for the case where domain redirection is required # to resolve an account. Since the lifetime of the resolved # principal is the same as the PrincipalContext, we need to # ensure the PrincipalContext remains live until we're done. $disposables = New-Object System.Collections.ArrayList try { # PrincipalContext for domain account resolution $credentialPrincipalContext = $null # PrincipalContext for local account resolution $localPrincipalContext = $null $group = $null [System.Net.NetworkCredential] $networkCredential = $null if($PSBoundParameters.ContainsKey('Credential')) { $networkCredential = $Credential.GetNetworkCredential(); $credentialPrincipalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList ([System.DirectoryServices.AccountManagement.ContextType]::Domain, $networkCredential.Domain, $networkCredential.UserName, $networkCredential.Password) $disposables.Add($credentialPrincipalContext) | out-null } # Create local machine context. $localPrincipalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList ([System.DirectoryServices.AccountManagement.ContextType]::Machine) $disposables.Add($localPrincipalContext) | out-null $group = [System.DirectoryServices.AccountManagement.GroupPrincipal]::FindByIdentity($localPrincipalContext, $GroupName); if($group -eq $null) { # A group with the provided name does not exist. Write-Log -Message ($LocalizedData.GroupDoesNotExist -f $GroupName) if($Ensure -eq "Absent") { return $true } else { return $false } } $disposables.Add($group) | out-null # A group with the provided name exists. Write-Log -Message ($LocalizedData.GroupExists -f $GroupName) # Validate separate properties. if($Ensure -eq "Absent") { Write-Log -Message ($LocalizedData.PropertyMismatch -f "Ensure", "Absent", "Present") return $false; # The Ensure property does not match. Return $false; } if($PSBoundParameters.ContainsKey('GroupName') -and $GroupName -ne $group.SamAccountName -and $GroupName -ne $group.Sid.Value) { return $false; # The Name property does not match. Return $false; } if($PSBoundParameters.ContainsKey('Description') -and $Description -ne $group.Description) { Write-Log -Message ($LocalizedData.PropertyMismatch -f "Description", $Description, $group.Description) return $false; # The Description property does not match. Return $false; } if($PSBoundParameters.ContainsKey('Members')) { if($PSBoundParameters.ContainsKey('MembersToInclude') -or $PSBoundParameters.ContainsKey('MembersToExclude')) { # If Members are provided, Include and Exclude are not allowed. ThrowInvalidArgumentError -ErrorId "GroupTestCmdlet_MembersPlusIncludeOrExcludeConflict" -ErrorMessage ($LocalizedData.MembersAndIncludeExcludeConflict -f "Members","MembersToInclude","MembersToExclude") } if($Members -eq $null) { ThrowInvalidArgumentError -ErrorId "GroupTestCmdlet_MembersIsNull" -ErrorMessage ($LocalizedData.MembersIsNull -f "Members","MembersToInclude","MembersToExclude") } # Remove duplicate names as strings. $Members = [String[]]@(RemoveDuplicates -Members $Members); # Resolve the names to actual principal objects. $membersPrincipals = ResolveNamesToPrincipals -LocalPrincipalContext $localPrincipalContext -CredentialPrincipalContext $credentialPrincipalContext -ObjectNames $Members -Credentials $Credential -Disposables $disposables # Remove all possible duplicates. [System.DirectoryServices.AccountManagement.Principal[]]$membersPrincipals = RemoveDuplicatePrincipals -Members $membersPrincipals if($membersPrincipals.Count -ne $group.Members.Count) { Write-Log -Message ($LocalizedData.MembersNumberMismatch -f "Members", $membersPrincipals.Count, $group.Members.Count) return $false; # The number of provided unique group members is different from the number of actual group members. Return $false. } # Compare two members lists. for($m = 0; $m -lt $membersPrincipals.Count; $m++) { $matchFound = $false; foreach($groupMember in $group.Members) { if($membersPrincipals[$m] -eq $groupMember) { $matchFound = $true; break; } } if(!$matchFound) { Write-Log -Message ($LocalizedData.MembersMemberMismatch -f $membersPrincipals[$m].SamAccountName, "Members", $group.SamAccountName) return $false; # At least one element does not have a match. Return $false; } } } else { if($PSBoundParameters.ContainsKey('MembersToInclude')) { $MembersToInclude = [String[]]@(RemoveDuplicates -Members $MembersToInclude); # Resolve the names to actual principal objects. $membersToIncludePrincipals = ResolveNamesToPrincipals -LocalPrincipalContext $localPrincipalContext -CredentialPrincipalContext $credentialPrincipalContext -ObjectNames $MembersToInclude -NetworkCredential $networkCredential -Disposables $disposables # Remove all possible duplicates. [System.DirectoryServices.AccountManagement.Principal[]]$membersToIncludePrincipals = RemoveDuplicatePrincipals -Members $membersToIncludePrincipals # Check if every element in $membersToIncludePrincipals has a match in $group.Members. for($m = 0; $m -lt $membersToIncludePrincipals.Count; $m++) { $matchFound = $false; foreach($groupMember in $group.Members) { if($membersToIncludePrincipals[$m] -eq $groupMember) { $matchFound = $true; break; } } if(!$matchFound) { Write-Log -Message ($LocalizedData.MembersMemberMismatch -f $membersToIncludePrincipals[$m].SamAccountName, "MembersToInclude", $group.SamAccountName) return $false; # At least one element from $MembersToInclude does not have a match. Return $false; } } } if($PSBoundParameters.ContainsKey('MembersToExclude')) { $MembersToExclude = [String[]]@(RemoveDuplicates -Members $MembersToExclude); # Resolve the names to actual principal objects. $membersToExcludePrincipals = ResolveNamesToPrincipals -LocalPrincipalContext $localPrincipalContext -CredentialPrincipalContext $credentialPrincipalContext -ObjectNames $MembersToExclude -NetworkCredential $networkCredential -Disposables $disposables # Remove all possible duplicates. [System.DirectoryServices.AccountManagement.Principal[]]$membersToExcludePrincipals = RemoveDuplicatePrincipals -Members $membersToExcludePrincipals # Check if any element in $membersToExcludePrincipals has a match in $group.Members. for($m = 0; $m -lt $membersToExcludePrincipals.Count; $m++) { foreach($groupMember in $group.Members) { if($membersToExcludePrincipals[$m] -eq $groupMember) { Write-Log -Message ($LocalizedData.MemberToExcludeMatch -f $membersToExcludePrincipals[$m].SamAccountName, "MembersToExclude", $group.SamAccountName) return $false; # At least one element from $MembersToExclude has a match. Return $false; } } } } } } finally { foreach ($disposable in $disposables) { $disposable.Dispose() } } # All properties match. Return $true. return $true; } function RemoveDuplicates { param ( [System.String[]] $Members ) Set-StrictMode -Version Latest $destIndex = 0; for([int] $sourceIndex = 0 ; $sourceIndex -lt $Members.Count; $sourceIndex++) { $matchFound = $false; for([int] $matchIndex = 0; $matchIndex -lt $destIndex; $matchIndex++) { if($Members[$sourceIndex] -eq $Members[$matchIndex]) { # A duplicate is found. Discard the duplicate. $matchFound = $true; continue; } } if(!$matchFound) { $Members[$destIndex++] = $Members[$sourceIndex].ToLowerInvariant(); } } # Create the output array. $destination = New-Object System.String[] -ArgumentList $destIndex # Copy only distinct elements from the original array to the destination array. [System.Array]::Copy($Members, $destination, $destIndex); return $destination; } function RemoveDuplicatePrincipals { param ( [System.DirectoryServices.AccountManagement.Principal[]] $Members ) Set-StrictMode -Version Latest $destIndex = 0; for([int] $sourceIndex = 0 ; $sourceIndex -lt $Members.Count; $sourceIndex++) { $matchFound = $false; for([int] $matchIndex = 0; $matchIndex -lt $destIndex; $matchIndex++) { if($Members[$sourceIndex].ContextType -eq $Members[$matchIndex].ContextType -and $Members[$sourceIndex].SamAccountName -eq $Members[$matchIndex].SamAccountName) { # A duplicate is found. Discard the duplicate. $matchFound = $true; continue; } } if(!$matchFound) { $Members[$destIndex++] = $Members[$sourceIndex]; } } # Create the output array. $destination = New-Object System.DirectoryServices.AccountManagement.Principal[] -ArgumentList $destIndex # Copy only distinct elements from the original array to the destination array. [System.Array]::Copy($Members, $destination, $destIndex); if($destination -ne $null) { return [System.DirectoryServices.AccountManagement.Principal[]]$destination; } # Return an empty array. return ,@($destination) } function EnumerateMembers { param ( [System.DirectoryServices.AccountManagement.GroupPrincipal] $Group ) Set-StrictMode -Version Latest # Create the output array. $members = @(); foreach($member in $group.Members) { if($member.ContextType -eq "Domain") { # Select only the first part of the full domain name. [String]$domainName = $member.Context.Name; $domainName = $domainName.Substring(0, $domainName.IndexOf('.')); if($member.StructuralObjectClass -eq "computer") { $members += ($domainName+'\'+$member.Name); } else { $members += ($domainName+'\'+$member.SamAccountName); } } else { $members += $member.Name; } } return $members; } function IsSameDomain { [OutputType([bool])] param ( [ValidateNotNullOrEmpty()] [System.DirectoryServices.AccountManagement.PrincipalContext] $PrincipalContext, [ValidateNotNull()] [String] $Domain ) # Compare against Name of $principalContext - typically the undecorated domain name [bool] $isSameDomain = [System.String]::Compare($Domain, $PrincipalContext.Name, [System.StringComparison]::OrdinalIgnoreCase) -eq 0 if ($isSameDomain -eq $false) { $dotIndex = $PrincipalContext.ConnectedServer.IndexOf(".") if ($dotIndex -ne -1) { $principalDomain = $PrincipalContext.ConnectedServer.Substring($dotIndex + 1) $isSameDomain = [System.String]::Compare($Domain, $principalDomain, [System.StringComparison]::OrdinalIgnoreCase) -eq 0 } } return $isSameDomain } function ResolveNamesToPrincipals { param ( [ValidateNotNullOrEmpty()] [System.DirectoryServices.AccountManagement.PrincipalContext] $LocalPrincipalContext, [System.DirectoryServices.AccountManagement.PrincipalContext] $CredentialPrincipalContext, [ValidateNotNull()] [String[]] $ObjectNames, [ValidateNotNull()] [System.Collections.ArrayList] $Disposables, [System.Net.NetworkCredential] $NetworkCredential ) Set-StrictMode -Version Latest $principals = New-Object System.Collections.ArrayList foreach($objectName in $ObjectNames) { # true if the name was qualified relative to the local machine # or no scope was provided (e.g., a simple name) $isLocalMachineQualified = $true # the user name parsed from a scoped name. # default to the passed in value. $userName = $objectName # The qualifier for the name in the form of scope\name or name@domain... $scope = $null # Check for machine\name or domain\name $separatorIndex = $objectName.IndexOfAny('\') if ($separatorIndex -ne -1) { $scope = $objectName.Substring(0, $separatorIndex) $userName = $userName = $objectName.Substring($separatorIndex+1) $isLocalMachineQualified = $objectName.StartsWith('.\') -or [System.String]::Compare($scope, [Environment]::MachineName, [System.StringComparison]::OrdinalIgnoreCase) -eq 0 } # Check for UPN (name@domain) else { $separatorIndex = $objectName.IndexOfAny("@") if ($separatorIndex -ne -1) { $scope = $objectName.Substring($separatorIndex+1) $userName = $userName = $objectName.Substring(0, $separatorIndex) $isLocalMachineQualified = $false } } # The account is either qualified to the local machine or is unqualified. if ($isLocalMachineQualified -eq $true) { Write-Verbose -Message ($LocalizedData.ResolvingLocalAccount -f $objectName) # Resolve against the local context and fail if not resolved. $principal = ResolveNameToPrincipal -PrincipalContext $LocalPrincipalContext -ObjectName $userName if($principal -ne $null) { $null = $principals.Add($principal) continue } # The provided name does not match any local User, Group, or Computer. Throw an exception. ThrowInvalidArgumentError -ErrorId "PrincipalNotFound_LocalMachine" -ErrorMessage ($LocalizedData.CouldNotFindPrincipal -f $objectName) } # The account has a qualifier that is not the local machine. # Attempt to resolve it relative to a domain. # NOTE: If no credentials are provided, an InvalidArgument error is reported. if ($CredentialPrincipalContext -ne $null) { # The PrincipalContext created when the account domain doesn't match the credential's domain. [System.DirectoryServices.AccountManagement.PrincipalContext] $redirectPrincipalContext = $null # The PrincipalContext to use to resolve the account [System.DirectoryServices.AccountManagement.PrincipalContext] $domainPrincipalcontext = $CredentialPrincipalContext # If the account is in a domain that does not match the domain in the passed credentials, attempt to connect to the # account's domain using the passed in credentials. This means the passed in credentials must have # rights in the other domain to resolve the principal. if ((IsSameDomain -PrincipalContext $CredentialPrincipalContext -Domain $scope) -eq $false) { Write-Verbose -Message ($LocalizedData.RedirectDomain -f $scope, $ObjectName) $networkUser = [System.String]::Format("{0}\{1}", $NetworkCredential.Domain, $NetworkCredential.UserName) # Use the new PrincipalContext for the resolve call. $domainPrincipalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList ([System.DirectoryServices.AccountManagement.ContextType]::Domain, $scope, $networkUser, $NetworkCredential.Password) # the caller will dispose the PrincipalContext when it is done with the resolved principal instance. $disposables.Add($domainPrincipalContext) | out-null } Write-Verbose -Message ($LocalizedData.ResolvingDomainAccount -f $objectName,$domainPrincipalcontext.Name) $principal = ResolveNameToPrincipal -PrincipalContext $domainPrincipalcontext -ObjectName $userName if ($principal -ne $null) { $null = $principals.Add($principal) continue } # The provided name does not match any User, Group, or Computer in the defined scope. ThrowInvalidArgumentError -ErrorId "PrincipalNotFound_ProvidedCredential" -ErrorMessage ($LocalizedData.CouldNotFindPrincipal -f $objectName) } # The provided name is not scoped to the local machine and no credentials were provided. # This is an unsupported use case since we're running as SYSTEM and credentials are required to resolve off-box. ThrowInvalidArgumentError -ErrorId "PrincipalNotFoundNoCredential" -ErrorMessage ($LocalizedData.DomainCredentialsRequired -f $objectName) } if($principals -ne $null) { return $principals } # Return an empty array. return ,@($principals) } function ResolveNameToPrincipal { param ( [ValidateNotNullOrEmpty()] [System.DirectoryServices.AccountManagement.PrincipalContext] $PrincipalContext, [ValidateNotNull()] [String] $ObjectName ) Set-StrictMode -Version Latest Write-Verbose -Message ($LocalizedData.ResolvingUser -f $ObjectName) # Try to find a matching user principal. $principal = [System.DirectoryServices.AccountManagement.UserPrincipal]::FindByIdentity($PrincipalContext, $ObjectName) if($principal -ne $null) { return $principal } Write-Verbose -Message ($LocalizedData.ResolvingGroup -f $ObjectName) # Try to find a matching group principal. $principal = [System.DirectoryServices.AccountManagement.GroupPrincipal]::FindByIdentity($PrincipalContext, $ObjectName) if($principal -ne $null) { return $principal } Write-Verbose -Message ($LocalizedData.ResolvingComputer -f $ObjectName) # Try to find a matching machine principal. $principal = [System.DirectoryServices.AccountManagement.ComputerPrincipal]::FindByIdentity($PrincipalContext, $ObjectName) [bool] $isDomain = $PrincipalContext.ContextType -eq [System.DirectoryServices.AccountManagement.ContextType]::Domain if ($isDomain -eq $false) { try { $principal = [System.DirectoryServices.AccountManagement.ComputerPrincipal]::FindByIdentity($PrincipalContext, $ObjectName); } catch [Exception] { # This method can throw with a particular error code if a computer is not found. if($_.Exception.ErrorCode -ne -2147467259) { throw $_.Exception } else { $principal = $null # Failure to find a computer principal. } } } else { $principal = [System.DirectoryServices.AccountManagement.ComputerPrincipal]::FindByIdentity($PrincipalContext, $ObjectName) } if($principal -ne $null) { return $principal } return $null } function AddGroupMembers { param ( [System.DirectoryServices.AccountManagement.GroupPrincipal] $Group, [System.DirectoryServices.AccountManagement.Principal[]] $Principals ) Set-StrictMode -Version Latest # Make changes to the group. foreach($principal in $Principals) { $group.Members.Add($principal); } } function RemoveGroupMembers { param ( [System.DirectoryServices.AccountManagement.GroupPrincipal] $Group, [System.DirectoryServices.AccountManagement.Principal[]] $Principals ) Set-StrictMode -Version Latest # Make changes to the group. foreach($principal in $Principals) { $null = $group.Members.Remove($principal); } } <# .Synopsis Validates the Group name for invalid characters. #> function ValidateGroupName { param ( [parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [System.String] $GroupName ) # Check if the name consists of only periods and/or white spaces. [bool] $wrongName = $true; for($i = 0; $i -lt $GroupName.Length; $i++) { if(-not [Char]::IsWhiteSpace($GroupName, $i) -and $GroupName[$i] -ne '.') { $wrongName = $false; break; } } $invalidChars = @('\','/','"','[',']',':','|','<','>','+','=',';',',','?','*','@') if($wrongName) { ThrowInvalidArgumentError -ErrorId "GroupNameHasOnlyWhiteSpacesAndDots" -ErrorMessage ($LocalizedData.InvalidGroupName -f $GroupName, [string]::Join(" ", $invalidChars)) } if($GroupName.IndexOfAny($invalidChars) -ne -1) { ThrowInvalidArgumentError -ErrorId "GroupNameHasInvalidCharachter" -ErrorMessage ($LocalizedData.InvalidGroupName -f $GroupName, [string]::Join(" ", $invalidChars)) } } <# .Synopsis Throws an argument error. #> function ThrowInvalidArgumentError { [CmdletBinding()] param ( [parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [System.String] $ErrorId, [parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [System.String] $ErrorMessage ) $errorCategory=[System.Management.Automation.ErrorCategory]::InvalidArgument $exception = New-Object System.ArgumentException $ErrorMessage; $errorRecord = New-Object System.Management.Automation.ErrorRecord $exception, $ErrorId, $errorCategory, $null throw $errorRecord } <# .Synopsis Writes either to Verbose or ShouldProcess channel. #> function Write-Log { [CmdletBinding(SupportsShouldProcess=$true)] param ( [parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [System.String] $Message ) if ($PSCmdlet.ShouldProcess($Message, $null, $null)) { Write-Verbose $Message } } Export-ModuleMember -function Get-TargetResource, Set-TargetResource, Test-TargetResource |