Connect-CaVault.ps1

function Connect-CaVault 
{
    <#
        .SYNOPSIS
            Establishes an authenticated REST connection to CyberArk.

        .DESCRIPTION
            Connect-CAVault establishes an authenticated connection to a given 
            CyberArk server. This connection can then be used to perform 
            additional tasks using the CyberArk REST API.

        .PARAMETER Server
            The IP address or hostname of the CyberArk PVWA server hosting the
            REST web services.

        .PARAMETER Credential
            A PowerShell credential representing the identity of the account 
            that will establish the REST connection. If no credential is 
            provided, you will be prompted to enter the username and password of
            an authorized account.

        .PARAMETER ConnectionNumber
            An optional parameter, ConnectionNumber can be specified when 
            working with multiple simultaneous connections.

        .INPUTS
            None. Connect-CAVault does not accept pipeline input.

        .OUTPUTS
            None. Connect-CAVault does not output information.

        .EXAMPLE
            Connect-CAVault -Server 10.10.10.10

            This command will attempt to authenticate to the REST services hosted 
            on server 10.10.10.10 after prompting for credentials.

        .EXAMPLE
            Connect-CAVault -Server 10.10.10.10 -ConnectionNumber 12

            This command will attempt to authenticate to the REST services hosted 
            on server 10.10.10.10 and create a new session numbered 12, after 
            prompting for credentials.

        .EXAMPLE
            $Credentials = Get-Credential
            Connect-CAVault 10.10.10.10 $Credentials

            This example uses the positional server and credential parameters.
    #>
    Param(
        [Parameter( Mandatory,
                    Position = 1 )]                    
        [string] $Server,

        [Parameter( Mandatory,
                    Position = 2 )]
        [PSCredential] $Credential,
        
        [int] $ConnectionNumber = 1,
        
        [switch] $UseRadiusAuth,

        [switch] $SAML
    )

    process {
        # Create the session settings object.
        $Script:CaSettings = [PSCustomObject] @{
            Server        = $Server
            BaseUri       = 'https://{0}/PasswordVault/WebServices/PIMServices.svc' -f $Server
            LogonUri      = 'https://{0}/PasswordVault/WebServices/auth/Cyberark/CyberArkAuthenticationService.svc/Logon' -f $Server
            LogoffUri     = 'https://{0}/PasswordVault/WebServices/auth/Cyberark/CyberArkAuthenticationService.svc/Logoff' -f $Server
            SamlLogonUri  = 'https://{0}/PasswordVault/WebServices/auth/SAML/SAMLAuthenticationService.svc/Logon' -f $Server
            SamlLogoffUri = 'https://{0}/PasswordVault/WebServices/auth/SAML/SAMLAuthenticationService.svc/Logoff' -f $Server
            AuthToken     = $null
            Header        = $null
        }
        
        # Initialize the POST BODY
        $RadiusAuth = if ($UseRadiusAuth) { $true } else { $false }
        $PostContent = @{
            username                = $Credential.GetNetworkCredential().UserName
            password                = $Credential.GetNetworkCredential().Password
            useRadiusAuthentication = $RadiusAuth
            connectionNumber        = $ConnectionNumber
        }

        # Make judicious use of splatting for pretty code.
        $RequestParams = @{
            Uri         = $Script:CaSettings.LogonUri
            Method      = 'POST'
            ContentType = 'application/json'
            Body        = (ConvertTo-Json -InputObject $PostContent)
        }
        
        if ($SAML) {
            $RequestParams.Uri = $Script:CaSettings.SamlLogonUri
        }

        # Commence authentication operations...
        try {
            $Response = Invoke-WebRequest @RequestParams -ErrorAction Stop
            $Content  = $Response.Content | ConvertFrom-Json

            Write-Verbose -Message ('Authentication returned with status code: {0}' -f $Response.StatusCode)

            if ($Response.StatusCode -eq 200) {
                Write-Verbose -Message ('Authentication successful.')
                $Script:CaSettings.AuthToken = $Content.CyberArkLogonResult
                $Script:CaSettings.Header    = @{ Authorization = $Script:CaSettings.AuthToken }
            }
        }
        catch {
            $ErrFormat = '{0}:{1}'
            
            # Try to output something meaningful.
            if ($PSItem.ErrorDetails) {
                # Generally if the ErrorDetails property exists, there's a CyberArk
                # error message to display.
                $ErrorDetails = $PSItem.ErrorDetails.Message | ConvertFrom-Json

                throw ($ErrFormat -f $ErrorDetails.ErrorCode, $ErrorDetails.ErrorMessage)
            }
            else {
                throw ($ErrFormat -f $PSitem.InvocationInfo.ScriptLineNumber, $PSItem.Exception.Message)
            }
        }

    }
}