Get-TssUserStub - closes #97

thycotic-ps · Mar 27, 2021 · 5650be7 · 5650be7
1 parent 87929d6
commit 5650be7
Show file tree

Hide file tree

Showing 8 changed files with 255 additions and 3 deletions.
diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml
@@ -133,6 +133,8 @@ commands:
         url: /commands/Search-TssUser
       - title: "Find-TssUser"
         url: /commands/Find-TssUser
+      - title: "Get-TssUserStub"
+        url: /commands/Get-TssUserStub
 
   - title: "Configurations"
     children:

diff --git a/docs/collections/_abouttopics/about_tssuser.md b/docs/collections/_abouttopics/about_tssuser.md
@@ -122,4 +122,5 @@ last_modified_at: 2021-03-03T00:00:00-00:00
 # METHODS
 
 # RELATED LINKS:
-    Get-TssUser
+    Get-TssUser
+    Get-TssUserStub
diff --git a/docs/collections/_commands/Get-TssUserStub.md b/docs/collections/_commands/Get-TssUserStub.md
@@ -0,0 +1,78 @@
+---
+category: general
+external help file: Thycotic.SecretServer-help.xml
+Module Name: Thycotic.SecretServer
+online version: https://thycotic-ps.github.io/thycotic.secretserver/commands/Get-TssUserStub
+schema: 2.0.0
+title: Get-TssUserStub
+---
+
+# Get-TssUserStub
+
+## SYNOPSIS
+Get user stub object
+
+## SYNTAX
+
+```
+Get-TssUserStub [-TssSession] <TssSession> [<CommonParameters>]
+```
+
+## DESCRIPTION
+Get user stub object to create a new user
+
+## EXAMPLES
+
+### EXAMPLE 1
+```
+$session = New-TssSession -SecretServer https://alpha -Credential $ssCred
+Get-TssUserStub -TssSession $session
+```
+
+Returns an empty User object
+
+### EXAMPLE 2
+```
+$session = New-TssSession -SecretServer https://alpha -Credential $ssCred
+$newUser = Get-TssUserStub -TssSession $session
+$newUser.DisplayName = 'IT Operator - Bob'
+$newUser.Username = 'bob'
+New-TssUser -TssSession $session -UserStub $newUser -Password (ConvertTo-SecureString 'P@ssword$01' -AsPlainText -Force)
+```
+
+Get empty User object, setting required minimum properties for Local User, and creating via New-TssUser
+
+## PARAMETERS
+
+### -TssSession
+TssSession object created by New-TssSession for auth
+
+```yaml
+Type: TssSession
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+### TssUser
+## NOTES
+Requires TssSession object returned by New-TssSession
+
+## RELATED LINKS
+
+[https://thycotic-ps.github.io/thycotic.secretserver/commands/Get-TssUserStub](https://thycotic-ps.github.io/thycotic.secretserver/commands/Get-TssUserStub)
+
+[https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/users/Get-UserStub.ps1](https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/users/Get-UserStub.ps1)
+
diff --git a/docs/collections/_pages/abouttopics.md b/docs/collections/_pages/abouttopics.md
@@ -88,7 +88,7 @@ About topics cover the [PowerShell classes](https://docs.microsoft.com/en-us/pow
 
 **Class** | **Thycotic.SecretServer Command** |
 --------------------------------- | -------------------------------------------------- |
-[TssUser] | [Get-TssUser]
+[TssUser] | [Get-TssUser] [Get-TssUserStub]
 [TssUserAuditSummary] | [Get-TssUserAudit]
 [TssRoleSummary] | [Get-TssUserRole]
 [TssUserRoleSummary] | [Get-TssUserRoleAssigned]
@@ -154,6 +154,7 @@ About topics cover the [PowerShell classes](https://docs.microsoft.com/en-us/pow
 [Get-TssSecretState]:/thycotic.secretserver/commands/Get-TssSecretState
 [Get-TssSecretHeartbeatStatus]:/thycotic.secretserver/commands/Get-TssSecretHeartbeatStatus
 [Get-TssUserAudit]:/thycotic.secretserver/commands/Get-TssUserAudit
+[Get-TssUserStub]:/thycotic.secretserver/commands/Get-TssUserStub
 
 [TssUserAuditSummary]:/thycotic.secretserver/abouttopics/about_tssuserauditsummary
 [TssSecretHeartbeatStatus]:/thycotic.secretserver/abouttopics/about_tsssecretheartbeatstatus

diff --git a/docs/collections/_pages/commands.md b/docs/collections/_pages/commands.md
@@ -131,6 +131,7 @@ A Thycotic.SecretServer command may not appear in the below list because it is n
 [Get-TssUserRoleAssigned] | [GET /users/{userId}/roles-assigned]
 [Search-TssUser] | [GET /users]
 [Show-TssCurrentUser] | [GET /users/current]
+[Get-TssUserStub] | [GET /users/stub]
 
 ## Directory Services
 
@@ -203,7 +204,9 @@ A Thycotic.SecretServer command may not appear in the below list because it is n
 [Search-TssSecretTemplate]:/thycotic.secretserver/commands/Search-TssSecretTemplate
 [Get-TssUserAudit]:/thycotic.secretserver/commands/Get-TssUserAudit
 [Protect-TssSecret]:/thycotic.secretserver/commands/Protect-TssSecret
+[Get-TssUserStub]:/thycotic.secretserver/commands/Get-TssUserStub
 
+[GET /users/stub]:https://updates.thycotic.net/secretserver/restapiguide/10.9.33/TokenAuth/#operation--users-stub-get
 [POST /secrets/{id}/check-in]:https://updates.thycotic.net/secretserver/restapiguide/10.9.33/TokenAuth/#operation--secrets--id--check-in-post
 [GET /users/{userId}/audit]:https://updates.thycotic.net/secretserver/restapiguide/10.9.33/TokenAuth/#operation--users--userId--audit-get
 [GET /secret-templates]:https://updates.thycotic.net/secretserver/restapiguide/10.9.33/TokenAuth/#operation--secret-templates-get

diff --git a/src/classes/users/Get-UserStub.ps1 b/src/classes/users/Get-UserStub.ps1
@@ -0,0 +1,74 @@
+function Get-UserStub {
+    <#
+    .SYNOPSIS
+    Get user stub object
+
+    .DESCRIPTION
+    Get user stub object to create a new user
+
+    .EXAMPLE
+    $session = New-TssSession -SecretServer https://alpha -Credential $ssCred
+    Get-TssUserStub -TssSession $session
+
+    Returns an empty User object
+
+    .EXAMPLE
+    $session = New-TssSession -SecretServer https://alpha -Credential $ssCred
+    $newUser = Get-TssUserStub -TssSession $session
+    $newUser.DisplayName = 'IT Operator - Bob'
+    $newUser.Username = 'bob'
+    New-TssUser -TssSession $session -UserStub $newUser -Password (ConvertTo-SecureString 'P@ssword$01' -AsPlainText -Force)
+
+    Get empty User object, setting required minimum properties for Local User, and creating via New-TssUser
+
+    .LINK
+    https://thycotic-ps.github.io/thycotic.secretserver/commands/Get-TssUserStub
+
+    .LINK
+    https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/users/Get-UserStub.ps1
+
+    .NOTES
+    Requires TssSession object returned by New-TssSession
+    #>
+    [CmdletBinding()]
+    [OutputType('TssUser')]
+    param (
+        # TssSession object created by New-TssSession for auth
+        [Parameter(Mandatory,ValueFromPipeline,Position = 0)]
+        [TssSession]
+        $TssSession
+    )
+    begin {
+        $tssParams = $PSBoundParameters
+        $invokeParams = . $GetInvokeTssParams $TssSession
+    }
+
+    process {
+        Write-Verbose "Provided command parameters: $(. $GetInvocation $PSCmdlet.MyInvocation)"
+        if ($tssParams.ContainsKey('TssSession') -and $TssSession.IsValidSession()) {
+            . $CheckVersion $TssSession '10.9.000000' $PSCmdlet.MyInvocation
+            $restResponse = $null
+            $uri = $TssSession.ApiUrl, 'users', 'stub' -join '/'
+            $invokeParams.Uri = $uri
+            $invokeParams.Method = 'GET'
+
+            # these properties always return null for an empty user object
+            $invokeParams.RemoveProperty = 'verifyEmailSentDate', 'passwordLastChanged', 'adAccountExpires', 'resetSessionStarted', 'lastSessionActivity', 'LastLogin'
+
+            Write-Verbose "Performing the operation $($invokeParams.Method) $uri"
+            try {
+                $restResponse = Invoke-TssRestApi @invokeParams
+            } catch {
+                Write-Warning "Issue getting user stub"
+                $err = $_
+                . $ErrorHandling $err
+            }
+
+            if ($restResponse) {
+                [TssUser]$restResponse
+            }
+        } else {
+            Write-Warning "No valid session found"
+        }
+    }
+}
diff --git a/src/en-us/about_tssuser.help.txt b/src/en-us/about_tssuser.help.txt
@@ -116,4 +116,5 @@ PROPERTIES
 METHODS
 
 RELATED LINKS:
-    Get-TssUser
+    Get-TssUser
+    Get-TssUserStub
diff --git a/tests/users/Get-TssUserStub.Tests.ps1 b/tests/users/Get-TssUserStub.Tests.ps1
@@ -0,0 +1,92 @@
+BeforeDiscovery {
+    $commandName = Split-Path ($PSCommandPath.Replace('.Tests.ps1','')) -Leaf
+    . ([IO.Path]::Combine([string]$PSScriptRoot, '..', 'constants.ps1'))
+}
+Describe "$commandName verify parameters" {
+    BeforeDiscovery {
+        [object[]]$knownParameters = 'TssSession'
+        [object[]]$currentParams = ([Management.Automation.CommandMetaData]$ExecutionContext.SessionState.InvokeCommand.GetCommand($commandName,'Function')).Parameters.Keys
+        [object[]]$commandDetails = [System.Management.Automation.CommandInfo]$ExecutionContext.SessionState.InvokeCommand.GetCommand($commandName,'Function')
+        $unknownParameters = Compare-Object -ReferenceObject $knownParameters -DifferenceObject $currentParams -PassThru
+    }
+    Context "Verify parameters" -ForEach @{currentParams = $currentParams } {
+        It "$commandName should contain <_> parameter" -TestCases $knownParameters {
+            $_ -in $currentParams | Should -Be $true
+        }
+        It "$commandName should not contain parameter= $<_>" -TestCases $unknownParameters {
+            $_ | Should -BeNullOrEmpty
+        }
+    }
+    Context "Command specific details" {
+        It "$commandName should set OutputType to TssUser" -TestCases $commandDetails {
+            $_.OutputType.Name | Should -Be 'TssUser'
+        }
+    }
+}
+Describe "$commandName functions" {
+    Context "Checking" {
+        BeforeAll {
+            $session = [pscustomobject]@{
+                ApiVersion   = 'api/v1'
+                Take         = 2147483647
+                SecretServer = 'http://alpha/'
+                ApiUrl       = 'http://alpha/api/v1'
+                AccessToken  = 'AgJf5YLFWtzw2UcBrM1s1KB2BGZ5Ufc4qLZ'
+                RefreshToken = '9oacYFZZ0YqgBNg0L7VNIF6-Z9ITE51Qplj'
+                TokenType    = 'bearer'
+                ExpiresIn    = 1199
+            }
+            Mock -Verifiable -CommandName Get-TssVersion -MockWith {
+                return @{
+                    Version = '10.9.000033'
+                }
+            }
+
+            Mock -Verifiable -CommandName Invoke-TssRestApi -ParameterFilter { $Uri -eq "$($session.ApiUrl)/users/stub"; $Method -eq 'GET' } -MockWith {
+                return [pscustomobject]@{
+                    id                       = 0
+                    userName                 = ""
+                    displayName              = ""
+                    lastLogin                = '1/1/0001 12:00:00 AM'
+                    created                  = '1/1/0001 12:00:00 AM'
+                    enabled                  = $false
+                    loginFailures            = 0
+                    emailAddress             = ""
+                    userLcid                 = 0
+                    domainId                 = -1
+                    lastSessionActivity      = '1/1/0001 12:00:00 AM'
+                    isLockedOut              = $false
+                    radiusUserName           = ""
+                    twoFactor                = $false
+                    radiusTwoFactor          = $false
+                    isEmailVerified          = $false
+                    mustVerifyEmail          = $false
+                    verifyEmailSentDate      = '1/1/0001 12:00:00 AM'
+                    passwordLastChanged      = '1/1/0001 12:00:00 AM'
+                    dateOptionId             = -1
+                    timeOptionId             = -1
+                    isEmailCopiedFromAD      = $false
+                    adGuid                   = ""
+                    adAccountExpires         = '1/1/0001 12:00:00 AM'
+                    resetSessionStarted      = '1/1/0001 12:00:00 AM'
+                    isApplicationAccount     = $false
+                    oathTwoFactor            = $false
+                    oathVerified             = $false
+                    duoTwoFactor             = $false
+                    fido2TwoFactor           = $false
+                    unixAuthenticationMethod = 'Password'
+                    lockOutReason            = ""
+                    lockOutReasonDescription = ""
+                }
+            }
+            $object = Get-TssUserStub -TssSession $session
+            Assert-VerifiableMock
+        }
+        It "Should not be empty" {
+            $object | Should -Not -BeNullOrEmpty
+        }
+        It "Should have property <_>" -TestCases 'Username', 'DisplayName' {
+            $object[0].PSObject.Properties.Name | Should -Contain $_
+        }
+    }
+}