PSMPSession.psm1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
function New-PSMPSession {
    <#
    .SYNOPSIS
    Formats PSMP connection string and connects to target using ssh.

    .DESCRIPTION
    Correctly formats PSMP ssh connection string based on the provided parameter values.
    Supports both local and domain account objects, including usernames in UPN format.
    Allows user to specify any non-default additional delimiters configured for PSMP.
    SSH client must be installed and available on your PATH.

    .PARAMETER VaultUser
    The Vault user with which to authenticate to CyberArk.
    Standard & UserPrincipalName formats are supported.

    .PARAMETER TargetAccount
    The Account in CyberArk to use to connect to a target
    Standard & UserPrincipalName formats are supported.
    if UserPrincipalName format is used, TargetDomain value must be provided.

    .PARAMETER TargetDomain
    Optional Domain name of the target account.
    Must be provided if TargetAccount is in UserPrincipalName format.

    .PARAMETER TargetAddress
    The address of the target to connect to using the target account.

    .PARAMETER TargetMachine
    The CyberArk PSMP server to connect through

    .PARAMETER AdditionalDelimiter
    Specify the AdditionalDelimiter in use.
    If left blank, the default AdditionalDelimiter of % is used.
    If Authenticating with or targetting an account in UserPrincipalName format, PSMP should be configured with an AdditionalDelimiter.

    .PARAMETER TargetAddressPortDelimiter
    The delimiter to seaparate optional connection parameters.
    A TargetAddressPortDelimiter must have been configured for PSMP.
    If left blank, the default TargetAddressPortDelimiter of # is used.

    .EXAMPLE
    New-PSMPSession -VaultUser pspete -TargetAccount someaccount -TargetAddress 1.2.3.4 -TargetMachine PSMP

    Connect via PSM when target account is a local account object.

    Resulting connection string:
    pspete@someaccount@1.2.3.4@PSMP

    .EXAMPLE
    New-PSMPSession -VaultUser pspete -TargetAccount pspete_ADM -TargetDomain domain.com -TargetAddress server -TargetMachine psmp.domain.com

    Connect via PSM when target account is a domain account object.

    Resulting connection string:
    pspete@pspete_ADM#domain.com@server@psmp.domain.com

    .EXAMPLE
    New-PSMPSession -VaultUser pspete@pspete.dev -TargetAccount localuser -TargetAddress someserver -TargetMachine somepsmp

    Connect via PSM when vault username is in UPN format, and target account is a local account object.

    Resulting connection string:
    pspete@pspete.dev%localuser%someserver@somepsmp

    .EXAMPLE
    New-PSMPSession -VaultUser pete@pspete.dev -TargetAccount SomeAccount -TargetDomain SomeDomain -TargetAddress SomeServer -TargetMachine SomePSMP

    Connect via PSM when vault username is in UPN format, and target account is a domain account.

    Resulting connection string:
    pete@pspete.dev%SomeAccount#SomeDomain%SomeServer@SomePSMP

    .EXAMPLE
    New-PSMPSession -VaultUser -TargetAccount -TargetDomain -TargetAddress -TargetMachine

    Connect via PSM when target username is in UPN format.

    Resulting connection string:
    admin%target@company.com#company.com%TargetMachine.company.com@psmp

    .EXAMPLE
    New-PSMPSession -VaultUser admin@company.com -TargetAccount target@some.company.com -TargetDomain some.company.com -TargetAddress server.some.company.com -TargetMachine psmp.company.com

    Connect via PSM when both vault username and target username are in UPN format.

    Resulting connection string:
    admin@company.com%target@some.company.com#some.company.com%server.some.company.com@psmp.company.com

    .EXAMPLE
    New-PSMPSession -VaultUser admin@company.com -TargetAccount target@some.company.com -TargetDomain some.company.com -TargetAddress server.some.company.com -TargetMachine psmp.company.com -AdditionalDelimiter "$"

    Connect via PSM when both vault username and target username are in UPN format, and an alternative additional delimiter is configured

    Resulting connection string:
    admin$target@company.com#company.com$TargetMachine.company.com@psmp

    .EXAMPLE
    New-PSMPSession -VaultUser admin@company.com -TargetAccount target@some.company.com -TargetDomain some.company.com -TargetAddress server.some.company.com -TargetMachine -AdditionalDelimiter psmp.company.com -TargetAddressPortDelimiter "$"

    Connect via PSM when both vault username and target username are in UPN format, and an alternative optional delimiter is configured

    Resulting connection string:
    admin@company.com%target@some.company.com$some.company.com%server.some.company.com@psmp.company.com

    .NOTES
    AUTHOR: Pete Maan

    #>

    [CmdletBinding(SupportsShouldProcess = $true)]
    param (
        # Vault Logon Username
        [Parameter(
            Mandatory = $true,
            ValueFromPipelineByPropertyName = $true
        )]
        [string]
        $VaultUser,

        # Target Account Username
        [Parameter(
            Mandatory = $true,
            ValueFromPipelineByPropertyName = $true
        )]
        [string]
        $TargetAccount,

        # Domain of the Target Account
        [Parameter(
            Mandatory = $false,
            ValueFromPipelineByPropertyName = $true
        )]
        [string]
        $TargetDomain,

        # Target to connect to
        [Parameter(
            Mandatory = $true,
            ValueFromPipelineByPropertyName = $true
        )]
        [string]
        $TargetAddress,

        # PSMP to connect through
        [Parameter(
            Mandatory = $true,
            ValueFromPipelineByPropertyName = $true
        )]
        [string]
        $TargetMachine,

        # Additional Delimiter, default "%"
        [Parameter(
            Mandatory = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [string]
        $AdditionalDelimiter,

        # Optioanl Delimiter, default "#"
        [Parameter(
            Mandatory = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [string]
        $TargetAddressPortDelimiter
    )

    begin {

        if ($PSBoundParameters.ContainsKey('AdditionalDelimiter')) {
            $Delimiter = $AdditionalDelimiter
        } else { $Delimiter = '%' }
        if ($PSBoundParameters.ContainsKey('TargetAddressPortDelimiter')) {
            $OptionalDelimiter = $TargetAddressPortDelimiter
        } else { $OptionalDelimiter = '#' }

    }

    process {

        if ($PSBoundParameters.ContainsKey('TargetDomain')) {
            #Target UPN
            #Domain Account Object
            $Account = "$TargetAccount$OptionalDelimiter$TargetDomain"
        } else {
            $Account = $TargetAccount
        }

        if (($VaultUser -like '*@*') -or ($TargetAccount -like '*@*')) {
            #Vault UPN: Local Account Object
            #Vault UPN: Domain Account Object
            #Vault User: Target UPN
            #Vault UPN: Target UPN
            $ConnectionString = "$VaultUser$Delimiter$Account$Delimiter$TargetAddress@$TargetMachine"
        } Else {
            #Local Account Object
            #Domain Account Object
            $ConnectionString = "$VaultUser@$Account@$TargetAddress@$TargetMachine"
        }

        Write-Debug $ConnectionString

    }

    end {

        if ($PSCmdlet.ShouldProcess($ConnectionString, 'Connect SSH')) {

            #Invoke SSH client connection with PSMP formated connection string
            ssh $ConnectionString

        }

    }

}