Public/Find-TppIdentity.ps1

<#
.SYNOPSIS
Search for identity details

.DESCRIPTION
Returns information about individual identity, group identity, or distribution groups from a local or non-local provider such as Active Directory.
You can specify individual identity types to search for or all

.PARAMETER Name
The individual identity, group identity, or distribution group name to search for

.PARAMETER First
First how many items are returned, the default is 500, but is limited by the provider.

.PARAMETER IncludeUsers
Include user identity type in search

.PARAMETER IncludeSecurityGroups
Include security group identity type in search

.PARAMETER IncludeDistributionGroups
Include distribution group identity type in search

.PARAMETER Me
Returns the identity of the authenticated user and all associated identities. Will be deprecated in a future release, use Get-TppIdentity -Me instead.

.PARAMETER VenafiSession
Authentication for the function.
The value defaults to the script session object $VenafiSession created by New-VenafiSession.
A TPP token or VaaS key can also provided.
If providing a TPP token, an environment variable named TppServer must also be set.

.INPUTS
Name

.OUTPUTS
PSCustomObject with the following properties:
    Name
    ID
    Path

.EXAMPLE
Find-TppIdentity -Name 'greg' -IncludeUsers
Find only user identities with the name greg

.EXAMPLE
'greg', 'brownstein' | Find-TppIdentity
Find all identity types with the name greg and brownstein

.LINK
http://VenafiPS.readthedocs.io/en/latest/functions/Find-TppIdentity/

.LINK
https://github.com/Venafi/VenafiPS/blob/main/VenafiPS/Public/Find-TppIdentity.ps1

.LINK
https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Identity-Browse.php
#>

function Find-TppIdentity {

    [CmdletBinding(DefaultParameterSetName = 'Find')]
    param (
        [Parameter(Mandatory, ParameterSetName = 'Find', ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [String[]] $Name,

        [Parameter(ParameterSetName = 'Find')]
        [Alias('Limit')]
        [int] $First = 500,

        [Parameter(ParameterSetName = 'Find')]
        [Switch] $IncludeUsers,

        [Parameter(ParameterSetName = 'Find')]
        [Switch] $IncludeSecurityGroups,

        [Parameter(ParameterSetName = 'Find')]
        [Switch] $IncludeDistributionGroups,

        [Parameter(Mandatory, ParameterSetName = 'Me')]
        [Switch] $Me,

        [Parameter()]
        [psobject] $VenafiSession = $script:VenafiSession
    )

    begin {
        Test-VenafiSession -VenafiSession $VenafiSession -Platform 'TPP'

        $identityType = 0
        # determine settings to use
        if ( $PSBoundParameters.ContainsKey('IncludeUsers') ) {
            $identityType += [TppIdentityType]::User
        }
        if ( $PSBoundParameters.ContainsKey('IncludeSecurityGroups') ) {
            $identityType += [TppIdentityType]::SecurityGroups
        }
        if ( $PSBoundParameters.ContainsKey('IncludeDistributionGroups') ) {
            $identityType += [TppIdentityType]::DistributionGroups
        }

        # if no types to include were provided, include all
        if ( $identityType -eq 0 ) {
            $identityType = [TppIdentityType]::User + [TppIdentityType]::SecurityGroups + [TppIdentityType]::DistributionGroups
        }

        Switch ($PsCmdlet.ParameterSetName)    {
            'Find' {
                $params = @{
                    VenafiSession = $VenafiSession
                    Method     = 'Post'
                    UriLeaf    = 'Identity/Browse'
                    Body       = @{
                        Filter       = 'placeholder'
                        Limit        = $First
                        IdentityType = $identityType
                    }
                }
            }

            'Me' {
                Write-Warning 'The -Me parameter will be deprecated in a future release. Please update your code to use Get-TppIdentity -Me.'
                $params = @{
                    VenafiSession = $VenafiSession
                    Method     = 'Get'
                    UriLeaf    = 'Identity/Self'
                }
            }
        }
    }

    process {

        Switch ($PsCmdlet.ParameterSetName)    {
            'Find' {
                $response = $Name.ForEach{
                    $params.Body.Filter = $_
                    Invoke-VenafiRestMethod @params
                }
                $ids = $response.Identities
            }

            'Me' {
                $response = Invoke-VenafiRestMethod @params

                $ids = $response.Identities | Select-Object -First 1
            }
        }

        if ( $ids ) {
            $ids | ConvertTo-TppIdentity
        }
    }
}