Carbon.Accounts

1.0.0-rc2

Carbon.Accounts.psm1

# Copyright WebMD Health Services
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License

using namespace System.ComponentModel
using namespace System.Runtime.InteropServices
using namespace System.Security.Principal

#Requires -Version 5.1
Set-StrictMode -Version 'Latest'

# Functions should use $script:moduleRoot as the relative root from which to find
# things. A published module has its function appended to this file, while a
# module in development has its functions in the Functions directory.
$script:moduleRoot = $PSScriptRoot
$modulesroot = Join-Path -Path $script:moduleRoot -ChildPath 'Modules' -Resolve

Import-Module -Name (Join-Path -Path $modulesRoot -ChildPath 'PureInvoke' -Resolve)

class Carbon_Accounts_Principal
{
    Carbon_Accounts_Principal( [String] $Domain,
                               [String] $Name,
                               [SecurityIdentifier]$Sid,
                               $Type)
    {
        $this.Domain = $Domain;
        $this.Name = $Name;
        $this.Sid = $Sid;
        $this.Type = $Type;

        $this.FullName = $Name
        if ($Domain)
        {
            $this.FullName = "${Domain}\${Name}"
        }
    }

    [String] $Domain

    [String] $FullName

    [String] $Name

    [SecurityIdentifier] $Sid

    $Type

    [bool] Equals([Object] $obj)
    {
        if ($null -eq $obj -or $obj -isnot [Carbon_Accounts_Principal])
        {
            return $false;
        }

        return $this.Sid.Equals($obj.Sid);
    }

}

# Store each of your module's functions in its own file in the Functions
# directory. On the build server, your module's functions will be appended to
# this file, so only dot-source files that exist on the file system. This allows
# developers to work on a module without having to build it first. Grab all the
# functions that are in their own files.
$functionsPath = Join-Path -Path $script:moduleRoot -ChildPath 'Functions\*.ps1'
if( (Test-Path -Path $functionsPath) )
{
    foreach( $functionPath in (Get-Item $functionsPath) )
    {
        . $functionPath.FullName
    }
}



function ConvertTo-CSecurityIdentifier
{
    <#
    .SYNOPSIS
    Converts a string or byte array security identifier into a `System.Security.Principal.SecurityIdentifier` object.
 
    .DESCRIPTION
    `ConvertTo-CSecurityIdentifier` converts a SID in SDDL form (as a string), in binary form (as a byte array) into a
    `System.Security.Principal.SecurityIdentifier` object. It also accepts
    `System.Security.Principal.SecurityIdentifier` objects, and returns them back to you.
 
    If the string or byte array don't represent a SID, an error is written and nothing is returned.
 
    .LINK
    Resolve-CPrincipal
 
    .LINK
    Resolve-CPrincipalName
 
    .EXAMPLE
    ConvertTo-CSecurityIdentifier -SID 'S-1-5-21-2678556459-1010642102-471947008-1017'
 
    Demonstrates how to convert a a SID in SDDL into a `System.Security.Principal.SecurityIdentifier` object.
 
    .EXAMPLE
    ConvertTo-CSecurityIdentifier -SID (New-Object 'Security.Principal.SecurityIdentifier' 'S-1-5-21-2678556459-1010642102-471947008-1017')
 
    Demonstrates that you can pass a `SecurityIdentifier` object as the value of the SID parameter. The SID you passed
    in will be returned to you unchanged.
 
    .EXAMPLE
    ConvertTo-CSecurityIdentifier -SID $sidBytes
 
    Demonstrates that you can use a byte array that represents a SID as the value of the `SID` parameter.
    #>
    [CmdletBinding()]
    param(
        # The SID to convert to a `System.Security.Principal.SecurityIdentifier`. Accepts a SID in SDDL form as a
        # `string`, a `System.Security.Principal.SecurityIdentifier` object, or a SID in binary form as an array of
        # bytes.
        [Parameter(Mandatory)]
        $SID
    )

    Set-StrictMode -Version 'Latest'
    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    try
    {
        if ( $SID -is [string])
        {
            New-Object 'Security.Principal.SecurityIdentifier' $SID
        }
        elseif ($SID -is [byte[]])
        {
            New-Object 'Security.Principal.SecurityIdentifier' $SID,0
        }
        elseif ($SID -is [Security.Principal.SecurityIdentifier])
        {
            $SID
        }
        else
        {
            $msg = "Invalid SID parameter value [$($SID.GetType().FullName)]${SID}. Only " +
                   '[System.Security.Principal.SecurityIdentifier] objects, SIDs in SDDL form as a [String], or SIDs ' +
                   'in binary form as a byte array are allowed.'
            return
        }
    }
    catch
    {
        $sidDisplayMsg = ''
        if ($SID -is [String])
        {
            $sidDisplayMsg = " ""${SID}"""
        }
        elseif ($SID -is [byte[]])
        {
            $sidDisplayMsg = " [$($SID -join ', ')]"
        }
        $msg = "Exception converting SID${sidDisplayMsg} to a [System.Security.Principal.SecurityIdentifier] " +
               'object. This usually means you passed an invalid SID in SDDL form (as a string) or an invalid SID ' +
               "in binary form (as a byte array): ${_}"
        Write-Error $msg -ErrorAction $ErrorActionPreference
        return
    }
}



function Resolve-CPrincipal
{
    <#
    .SYNOPSIS
    Gets domain, name, type, and SID information about a user or group.
 
    .DESCRIPTION
    The `Resolve-CPrincipal` function takes an identity name or security identifier (SID) and gets its canonical
    representation. It returns a `Carbon.Identity` object, which contains the following information about the identity:
 
     * Domain - the domain the user was found in
     * FullName - the users full name, e.g. Domain\Name
     * Name - the user's username or the group's name
     * Type - the Sid type.
     * Sid - the account's security identifier as a `System.Security.Principal.SecurityIdentifier` object.
 
    The common name for an account is not always the canonical name used by the operating system. For example, the
    local Administrators group is actually called BUILTIN\Administrators. This function uses the `LookupAccountName`
    and `LookupAccountSid` Windows functions to resolve an account name or security identifier into its domain, name,
    full name, SID, and SID type.
 
    You may pass a `System.Security.Principal.SecurityIdentifer`, a SID in SDDL form (as a string), or a SID in binary
    form (a byte array) as the value to the `SID` parameter. You'll get an error and nothing returned if the SDDL or
    byte array SID are invalid.
 
    If the name or security identifier doesn't represent an actual user or group, an error is written and nothing is
    returned.
 
    .LINK
    Test-CPrincipal
 
    .LINK
    Resolve-CPrincipalName
 
    .LINK
    http://msdn.microsoft.com/en-us/library/system.security.principal.securityidentifier.aspx
 
    .LINK
    http://msdn.microsoft.com/en-us/library/windows/desktop/aa379601.aspx
 
    .LINK
    ConvertTo-CSecurityIdentifier
 
    .LINK
    Resolve-CPrincipalName
 
    .LINK
    Test-CIdentity
 
    .OUTPUTS
    Carbon_Accounts_Principal.
 
    .EXAMPLE
    Resolve-CPrincipal -Name 'Administrators'
 
    Returns an object representing the `Administrators` group.
 
    .EXAMPLE
    Resolve-CPrincipal -SID 'S-1-5-21-2678556459-1010642102-471947008-1017'
 
    Demonstrates how to use a SID in SDDL form to convert a SID into an identity.
 
    .EXAMPLE
    Resolve-CPrincipal -SID ([Security.Principal.SecurityIdentifier]::New()'S-1-5-21-2678556459-1010642102-471947008-1017')
 
    Demonstrates that you can pass a `SecurityIdentifier` object as the value of the SID parameter.
 
    .EXAMPLE
    Resolve-CPrincipal -SID $sidBytes
 
    Demonstrates that you can use a byte array that represents a SID as the value of the `SID` parameter.
    #>
    [CmdletBinding()]
    param(
        # The name of the principal to return.
        [Parameter(Mandatory, ParameterSetName='ByName', Position=0)]
        [string] $Name,

        # The SID of the principal to return. Accepts a SID in SDDL form as a `string`, a
        # `System.Security.Principal.SecurityIdentifier` object, or a SID in binary form as an array of bytes.
        [Parameter(Mandatory , ParameterSetName='BySid')]
        [Object] $SID

    )

    Set-StrictMode -Version 'Latest'
    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    if ($PSCmdlet.ParameterSetName -eq 'BySid')
    {
        $SID = ConvertTo-CSecurityIdentifier -SID $SID
        if (-not $SID)
        {
            return
        }

        $sidBytes = [byte[]]::New($SID.BinaryLength)
        $SID.GetBinaryForm($sidBytes, 0)
        $account = Invoke-AdvapiLookupAccountSid -Sid $sidBytes
        if (-not $account)
        {
            Write-Error -Message "SID ""${SID}"" not found." -ErrorAction $ErrorActionPreference
            return
        }
        return [Carbon_Accounts_Principal]::New($account.ReferencedDomainName, $account.Name, $SID, $account.Use)
    }

    if ($Name.StartsWith('.\'))
    {
        $username = $Name.Substring(2)
        $Name = "$([Environment]::MachineName)\${username}"
        $identity = Resolve-CPrincipal -Name $Name
        if (-not $identity)
        {
            $Name = "BUILTIN\${username}"
            $identity = Resolve-CPrincipal -Name $Name
        }
        return $identity
    }

    if ($Name.Equals("LocalSystem", [StringComparison]::InvariantCultureIgnoreCase))
    {
        $Name = "NT AUTHORITY\SYSTEM"
    }

    $account = Invoke-AdvapiLookupAccountName -AccountName $Name
    if (-not $account)
    {
        Write-Error -Message "Principal ""${Name}"" not found." -ErrorAction $ErrorActionPreference
        return
    }

    $sid = [SecurityIdentifier]::New($account.Sid, 0)
    $ntAccount = $sid.Translate([NTAccount])
    $domainName,$accountName = $ntAccount.Value.Split('\', 2)
    if (-not $accountName)
    {
        $accountName = $domainName
        $domainName = ''
    }
    return [Carbon_Accounts_Principal]::New($domainName, $accountName, $sid, $account.Use)

}


function Resolve-CPrincipalName
{
    <#
    .SYNOPSIS
    Determines the full, NT principal name for a user or group.
 
    .DESCRIPTION
    `Resolve-CPrincipalName` resolves a user/group name into its full, canonical name, used by the operating system. For
    example, the local Administrators group is actually called BUILTIN\Administrators. With a canonical username, you
    can unambiguously compare principals on objects that contain user/group information.
 
    If unable to resolve a name into an principal, `Resolve-CPrincipalName` returns nothing.
 
    If you want to get full principal information (domain, type, sid, etc.), use `Resolve-CPrincipal`.
 
    In Carbon 2.0, you can also resolve a SID into its principal name. The `SID` parameter accepts a SID in SDDL form as
    a `string`, a `System.Security.Principal.SecurityIdentifier` object, or a SID in binary form as an array of bytes.
    If the SID no longer maps to an active account, you'll get the original SID in SDDL form (as a string) returned to
    you.
 
    .LINK
    ConvertTo-CSecurityIdentifier
 
    .LINK
    Resolve-CPrincipal
 
    .LINK
    Test-CIdentity
 
    .LINK
    http://msdn.microsoft.com/en-us/library/system.security.principal.securityidentifier.aspx
 
    .LINK
    http://msdn.microsoft.com/en-us/library/windows/desktop/aa379601.aspx
 
    .OUTPUTS
    string
 
    .EXAMPLE
    Resolve-CPrincipalName -Name 'Administrators'
 
    Returns `BUILTIN\Administrators`, the canonical name for the local Administrators group.
    #>
    [CmdletBinding(DefaultParameterSetName='ByName')]
    [OutputType([String])]
    param(
        # The name of the identity to return.
        [Parameter(Mandatory, ParameterSetName='ByName', Position=0)]
        [String] $Name,

        # Get an identity's name from its SID. Accepts a SID in SDDL form as a `string`, a
        # `System.Security.Principal.SecurityIdentifier` object, or a SID in binary form as an array of bytes.
        #
        # This parameter is new in Carbon 2.0.
        [Parameter(Mandatory, ParameterSetName='BySid')]
        $SID
    )

    Set-StrictMode -Version 'Latest'
    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    if ($PSCmdlet.ParameterSetName -eq 'ByName')
    {
        return Resolve-CPrincipal -Name $Name -ErrorAction Ignore | Select-Object -ExpandProperty 'FullName'
    }

    $id = Resolve-CPrincipal -Sid $SID -ErrorAction Ignore
    if ($id)
    {
        return $id.FullName
    }

    return $SID.ToString()
}




function Test-CPrincipal
{
    <#
    .SYNOPSIS
    Tests that a name is a valid Windows local or domain user/group.
 
    .DESCRIPTION
    Uses the Windows `LookupAccountName` function to find a principal. If it can't be found, returns `$false`.
    Otherwise, it returns `$true`.
 
    Use the `PassThru` switch to return a `Carbon.Identity` object (instead of `$true` if the identity exists.
 
    .LINK
    Resolve-CPrincipal
 
    .LINK
    Resolve-CPrincipalName
 
    .EXAMPLE
    Test-CPrincipal -Name 'Administrators
 
    Tests that a user or group called `Administrators` exists on the local computer.
 
    .EXAMPLE
    Test-CPrincipal -Name 'CARBON\Testers'
 
    Tests that a group called `Testers` exists in the `CARBON` domain.
 
    .EXAMPLE
    Test-CPrincipal -Name 'Tester' -PassThru
 
    Tests that a user or group named `Tester` exists and returns a `System.Security.Principal.SecurityIdentifier` object
    if it does.
    #>
    [CmdletBinding()]
    param(
        # The name of the identity to test.
        [Parameter(Mandatory)]
        [string] $Name,

        # Returns a `Carbon.Identity` object if the identity exists.
        [switch] $PassThru
    )

    Set-StrictMode -Version 'Latest'
    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    $principal = Resolve-CPrincipal -Name $Name -ErrorAction Ignore
    if (-not $principal)
    {
        return $false
    }

    if ($PassThru)
    {
        return $principal
    }
    return $true
}




function Use-CallerPreference
{
    <#
    .SYNOPSIS
    Sets the PowerShell preference variables in a module's function based on the callers preferences.
 
    .DESCRIPTION
    Script module functions do not automatically inherit their caller's variables, including preferences set by common
    parameters. This means if you call a script with switches like `-Verbose` or `-WhatIf`, those that parameter don't
    get passed into any function that belongs to a module.
 
    When used in a module function, `Use-CallerPreference` will grab the value of these common parameters used by the
    function's caller:
 
     * ErrorAction
     * Debug
     * Confirm
     * InformationAction
     * Verbose
     * WarningAction
     * WhatIf
     
    This function should be used in a module's function to grab the caller's preference variables so the caller doesn't
    have to explicitly pass common parameters to the module function.
 
    This function is adapted from the [`Get-CallerPreference` function written by David Wyatt](https://gallery.technet.microsoft.com/scriptcenter/Inherit-Preference-82343b9d).
 
    There is currently a [bug in PowerShell](https://connect.microsoft.com/PowerShell/Feedback/Details/763621) that
    causes an error when `ErrorAction` is implicitly set to `Ignore`. If you use this function, you'll need to add
    explicit `-ErrorAction $ErrorActionPreference` to every `Write-Error` call. Please vote up this issue so it can get
    fixed.
 
    .LINK
    about_Preference_Variables
 
    .LINK
    about_CommonParameters
 
    .LINK
    https://gallery.technet.microsoft.com/scriptcenter/Inherit-Preference-82343b9d
 
    .LINK
    http://powershell.org/wp/2014/01/13/getting-your-script-module-functions-to-inherit-preference-variables-from-the-caller/
 
    .EXAMPLE
    Use-CallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
 
    Demonstrates how to set the caller's common parameter preference variables in a module function.
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        #[Management.Automation.PSScriptCmdlet]
        # The module function's `$PSCmdlet` object. Requires the function be decorated with the `[CmdletBinding()]`
        # attribute.
        $Cmdlet,

        [Parameter(Mandatory)]
        # The module function's `$ExecutionContext.SessionState` object. Requires the function be decorated with the
        # `[CmdletBinding()]` attribute.
        #
        # Used to set variables in its callers' scope, even if that caller is in a different script module.
        [Management.Automation.SessionState]$SessionState
    )

    Set-StrictMode -Version 'Latest'

    # List of preference variables taken from the about_Preference_Variables and their common parameter name (taken
    # from about_CommonParameters).
    $commonPreferences = @{
                              'ErrorActionPreference' = 'ErrorAction';
                              'DebugPreference' = 'Debug';
                              'ConfirmPreference' = 'Confirm';
                              'InformationPreference' = 'InformationAction';
                              'VerbosePreference' = 'Verbose';
                              'WarningPreference' = 'WarningAction';
                              'WhatIfPreference' = 'WhatIf';
                          }

    foreach( $prefName in $commonPreferences.Keys )
    {
        $parameterName = $commonPreferences[$prefName]

        # Don't do anything if the parameter was passed in.
        if( $Cmdlet.MyInvocation.BoundParameters.ContainsKey($parameterName) )
        {
            continue
        }

        $variable = $Cmdlet.SessionState.PSVariable.Get($prefName)
        # Don't do anything if caller didn't use a common parameter.
        if( -not $variable )
        {
            continue
        }

        if( $SessionState -eq $ExecutionContext.SessionState )
        {
            Set-Variable -Scope 1 -Name $variable.Name -Value $variable.Value -Force -Confirm:$false -WhatIf:$false
        }
        else
        {
            $SessionState.PSVariable.Set($variable.Name, $variable.Value)
        }
    }
}