Add Convert-TppObject, Find-TppObject path tweak, other fixes (#49)

CHANGELOG.md

@@ -1,3 +1,12 @@
+## 3.5.0
+- BREAKING CHANGE: change parameter `-NewName` to `-NewPath` in `Rename-TppObject` to allow moving an object in addition to renaming
+- Add `Convert-TppObject` to change the class/type of an existing object
+- Fix typos in examples for `Add-TppCertificateAssociation` and `Remove-TppCertificateAssociation`
+- Set the default for `-Path` in `Find-TppObject` to \ved\policy.  Running `Find-TppObject` without a path will now recursively search from \ved\policy.
+- Add additional pipeline options to `Get-TppAttribute`
+- Add help and examples to `Invoke-VenafiRestMethod`, [#48](https://github.com/gdbarron/VenafiPS/issues/48)
+- Set VenafiSession default value in `Invoke-VenafiRestMethod`, [#47](https://github.com/gdbarron/VenafiPS/issues/47)
+
 ## 3.4.0
 - Add `-All` option to `Get-TppAttribute` to get ALL effective attribute values for an object.  This will provide the values as well as the path where the policy was applied
 - Add getting policies (policy attributes) with `Get-TppAttribute`

RELEASE.md

@@ -1,6 +1,7 @@
-- Add `-All` option to `Get-TppAttribute` to get ALL effective attribute values for an object.  This will provide the values as well as the path where the policy was applied
-- Add getting policies (policy attributes) with `Get-TppAttribute`
-- Add setting policies (policy attributes) with `Set-TppAttribute`
-- Add `Invoke-VenafiCertificateAction`.  This is your one stop shop for certificate actions on TPP or VaaS.  You can Retire, Reset, Renew, Push, Validate, or Revoke.
-- Cleanup output and verbose logging with `Remove-TppCertificate`
-- Fix parameter set issue in `New-VenafiSession`, ensure version and custom field info retrieval doesn't occur when creating a VaaS session
+- BREAKING CHANGE: change parameter `-NewName` to `-NewPath` in `Rename-TppObject` to allow moving an object in addition to renaming
+- Add `Convert-TppObject` to change the class/type of an existing object
+- Fix typos in examples for `Add-TppCertificateAssociation` and `Remove-TppCertificateAssociation`
+- Set the default for `-Path` in `Find-TppObject` to \ved\policy.  Running `Find-TppObject` without a path will now recursively search from \ved\policy.
+- Add additional pipeline options to `Get-TppAttribute`
+- Add help and examples to `Invoke-VenafiRestMethod`, [#48](https://github.com/gdbarron/VenafiPS/issues/48)
+- Set VenafiSession default value in `Invoke-VenafiRestMethod`, [#47](https://github.com/gdbarron/VenafiPS/issues/47)

VenafiPS/Classes/VenafiSession.ps1

@@ -21,6 +21,7 @@ class VenafiSession {
     # AuthType can be key, token or vaas
     # key is TPP and all functions
     # token is TPP and some functions require it
+    # tpp is key or token for tpp
     # vaas is Venafi as a Service
 
     # return $AuthType so functions know what we're working with
@@ -34,8 +35,12 @@ class VenafiSession {
                     throw "You must first connect to Venafi as a Service with New-VenafiSession -VaasKey"
                 }
 
+                'tpp' {
+                    throw "You must first connect to a TPP server with New-VenafiSession"
+                }
+
                 Default {
-                    throw "You must first connect to the TPP server with New-VenafiSession"
+                    throw "You must first connect to either Venafi as a Service or a TPP server with New-VenafiSession"
                 }
             }
 
@@ -111,6 +116,10 @@ class VenafiSession {
                 $this.Expires = $newToken.Expires
             }
 
+            'tpp' {
+                # handled by key/token above
+            }
+
             'vaas' {
                 # nothing yet
             }

VenafiPS/Public/Add-TppCertificateAssociation.ps1

@@ -29,11 +29,11 @@ InputObject, Path
 None
 
 .EXAMPLE
-Add-TppCertificateAssocation -CertificatePath '\ved\policy\my cert' -ApplicationPath '\ved\policy\my capi'
+Add-TppCertificateAssociation -CertificatePath '\ved\policy\my cert' -ApplicationPath '\ved\policy\my capi'
 Add a single application object association
 
 .EXAMPLE
-Add-TppCertificateAssocation -Path '\ved\policy\my cert' -ApplicationPath '\ved\policy\my capi' -PushCertificate
+Add-TppCertificateAssociation -Path '\ved\policy\my cert' -ApplicationPath '\ved\policy\my capi' -PushCertificate
 Add the association and push the certificate
 
 .LINK

VenafiPS/Public/Convert-TppObject.ps1

@@ -0,0 +1,77 @@
+<#
+.SYNOPSIS
+Change the class/object type of an existing object
+
+.DESCRIPTION
+Change the class/object type of an existing object
+
+.PARAMETER Path
+Path to the object
+
+.PARAMETER Class
+New class/type
+
+.PARAMETER VenafiSession
+Session object created from New-VenafiSession method.  The value defaults to the script session object $VenafiSession.
+
+.INPUTS
+Path
+
+.OUTPUTS
+None
+
+.EXAMPLE
+Convert-TppObject -Path '\ved\policy\' -Class 'X509 Device Certificate'
+Convert an object to a different type
+
+#>
+function Convert-TppObject {
+
+    [CmdletBinding()]
+
+    param (
+        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [ValidateNotNullOrEmpty()]
+        [ValidateScript( {
+                if ( $_ | Test-TppDnPath ) {
+                    $true
+                }
+                else {
+                    throw "'$_' is not a valid path"
+                }
+            })]
+        [String] $Path,
+
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [String] $Class,
+
+        [Parameter()]
+        [VenafiSession] $VenafiSession = $script:VenafiSession
+    )
+
+    begin {
+
+        $VenafiSession.Validate('tpp') | Out-Null
+
+        $params = @{
+            VenafiSession = $VenafiSession
+            Method        = 'Post'
+            UriLeaf       = 'config/MutateObject'
+            Body          = @{
+                Class = $Class
+            }
+        }
+    }
+
+    process {
+
+        $params.Body.ObjectDN = $Path
+
+        $response = Invoke-TppRestMethod @params
+
+        if ( $response.Result -ne [TppConfigResult]::Success ) {
+            throw $response.Error
+        }
+    }
+}

VenafiPS/Public/Find-TppIdentity.ps1

@@ -38,12 +38,10 @@ PSCustomObject with the following properties:
 
 .EXAMPLE
 Find-TppIdentity -Name 'greg' -IncludeUsers
-
-Find user identities with the name greg
+Find only user identities with the name greg
 
 .EXAMPLE
 'greg', 'brownstein' | Find-TppIdentity
-
 Find all identity types with the name greg and brownstein
 
 .LINK
@@ -53,7 +51,7 @@ http://VenafiPS.readthedocs.io/en/latest/functions/Find-TppIdentity/
 https://github.com/gdbarron/VenafiPS/blob/main/VenafiPS/Public/Find-TppIdentity.ps1
 
 .LINK
-https://docs.venafi.com/Docs/20.4SDK/TopNav/Content/SDK/WebSDK/r-SDK-POST-Identity-Browse.php?tocpath=Web%20SDK%7CIdentity%20programming%20interface%7C_____5
+https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Identity-Browse.php
 #>
 function Find-TppIdentity {
 

VenafiPS/Public/Find-TppObject.ps1

@@ -6,10 +6,10 @@ Find objects by path, class, or pattern
 Find objects by path, class, or pattern.
 
 .PARAMETER Path
-The path to start our search.
+The path to start our search.  The default is \ved\policy.
 
 .PARAMETER Class
-1 or more classes to search for
+1 or more classes/types to search for
 
 .PARAMETER Pattern
 Filter against object paths.
@@ -37,36 +37,40 @@ Path
 TppObject
 
 .EXAMPLE
-Find-TppObject -Path '\VED\Policy'
+Find-TppObject
+Get all objects recursively starting from \ved\policy
+
+.EXAMPLE
+Find-TppObject -Path '\VED\Policy\certificates'
 Get all objects in the root of a specific folder
 
 .EXAMPLE
 Find-TppObject -Path '\VED\Policy\My Folder' -Recursive
 Get all objects in a folder and subfolders
 
 .EXAMPLE
-Find-TppObject -Path '\VED\Policy' -Pattern 'test'
+Find-TppObject -Path '\VED\Policy' -Pattern '*test*'
 Get items in a specific folder filtering the path
 
 .EXAMPLE
-Find-TppObject -Class 'iis6'
-Get all objects of the type iis6
+Find-TppObject -Class 'capi' -Path '\ved\policy\installations' -Recursive
+Get objects of a specific type
 
 .EXAMPLE
-Find-TppObject -Class 'iis6' -Pattern 'test*'
-Get all objects of the type iis6 filtering the path
+Find-TppObject -Class 'capi' -Pattern '*test*' -Path '\ved\policy\installations' -Recursive
+Get all objects of a specific type where the path is of a specific pattern
 
 .EXAMPLE
-Find-TppObject -Class 'iis6', 'capi'
-Get all objects of the type iis6 or capi
+Find-TppObject -Class 'capi', 'iis6' -Pattern '*test*' -Path '\ved\policy\installations' -Recursive
+Get objects for multiple types
 
 .EXAMPLE
-Find-TppObject -Pattern 'test*'
-Find objects with the specific name.  All objects will be searched.
+Find-TppObject -Pattern '*f5*'
+Find objects with the specific name.  All objects under \ved\policy (the default) will be searched.
 
 .EXAMPLE
-Find-TppObject -Pattern 'test*' -Attribute 'Consumers'
-Find all objects where the specific attribute matches the pattern
+Find-TppObject -Pattern 'awesome*' -Attribute 'Description'
+Find objects where the specific attribute matches the pattern
 
 .LINK
 http://VenafiPS.readthedocs.io/en/latest/functions/Find-TppObject/
@@ -75,23 +79,24 @@ http://VenafiPS.readthedocs.io/en/latest/functions/Find-TppObject/
 https://github.com/gdbarron/VenafiPS/blob/main/VenafiPS/Public/Find-TppObject.ps1
 
 .LINK
-https://docs.venafi.com/Docs/20.4SDK/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-find.php?tocpath=Web%20SDK%7CConfig%20programming%20interface%7C_____17
+https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-find.php
 
 .LINK
-https://docs.venafi.com/Docs/20.4SDK/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-findobjectsofclass.php?tocpath=Web%20SDK%7CConfig%20programming%20interface%7C_____19
+https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-findobjectsofclass.php
 
 .LINK
-https://docs.venafi.com/Docs/20.4SDK/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-enumerate.php?tocpath=Web%20SDK%7CConfig%20programming%20interface%7C_____13
+https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-enumerate.php
 
 #>
 function Find-TppObject {
 
-    [CmdletBinding()]
+    [CmdletBinding(DefaultParameterSetName = 'FindByPath')]
     [Alias('fto')]
 
     param (
-        [Parameter(Mandatory, ParameterSetName = 'FindByPath', ValueFromPipelineByPropertyName)]
-        [Parameter(Mandatory, ParameterSetName = 'FindByClassAndPath', ValueFromPipelineByPropertyName)]
+        [Parameter(ParameterSetName = 'FindByPath', ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [Parameter(ParameterSetName = 'FindByClass', ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [Parameter(ParameterSetName = 'FindByPattern', ValueFromPipeline, ValueFromPipelineByPropertyName)]
         [ValidateNotNullOrEmpty()]
         [ValidateScript( {
                 if ( $_ | Test-TppDnPath -AllowRoot ) {
@@ -102,85 +107,83 @@ function Find-TppObject {
                 }
             })]
         [Alias('DN')]
-        [String] $Path,
+        [String] $Path = '\ved\policy',
 
-        [Parameter(ParameterSetName = 'FindByPath')]
         [Parameter(Mandatory, ParameterSetName = 'FindByPattern')]
         [Parameter(ParameterSetName = 'FindByClass')]
-        [Parameter(ParameterSetName = 'FindByClassAndPath')]
         [Parameter(Mandatory, ParameterSetName = 'FindByAttribute')]
         [ValidateNotNullOrEmpty()]
         [String] $Pattern,
 
-        [Parameter(ParameterSetName = 'FindByPath')]
-        [Parameter(ParameterSetName = 'FindByClassAndPath')]
-        [switch] $Recursive,
-
         [Parameter(Mandatory, ParameterSetName = 'FindByClass')]
-        [Parameter(Mandatory, ParameterSetName = 'FindByClassAndPath')]
         [ValidateNotNullOrEmpty()]
+        [Alias('TypeName')]
         [String[]] $Class,
 
         [Parameter(Mandatory, ParameterSetName = 'FindByAttribute')]
         [ValidateNotNullOrEmpty()]
         [Alias('AttributeName')]
         [String[]] $Attribute,
 
+        [Parameter(ParameterSetName = 'FindByPath')]
+        [Parameter(ParameterSetName = 'FindByClass')]
+        [Parameter(ParameterSetName = 'FindByPattern')]
+        [Alias('r')]
+        [switch] $Recursive,
+
         [Parameter()]
         [VenafiSession] $VenafiSession = $script:VenafiSession
     )
 
     begin {
+        $VenafiSession.Validate('tpp') | Out-Null
+    }
 
-        $VenafiSession.Validate() | Out-Null
-
-        Write-Verbose $PsCmdlet.ParameterSetName
+    process {
 
         $params = @{
             VenafiSession = $VenafiSession
-            Method     = 'Post'
-            UriLeaf    = 'placeholder'
-            Body       = @{ }
+            Method        = 'Post'
+            Body          = @{
+                'ObjectDN' = $Path
+            }
         }
 
-        Switch -Wildcard ($PsCmdlet.ParameterSetName) {
+        Switch ($PsCmdlet.ParameterSetName) {
             'FindByAttribute' {
                 $params.UriLeaf = 'config/find'
+                # this is the only api for this function which doesn't accept a path, let's remove it
+                $params.Body.Remove('ObjectDN')
+                $params.Body['AttributeNames'] = $Attribute
             }
 
-            'FindByPath' {
+            {$_ -in 'FindByPath', 'FindByPattern'} {
                 $params.UriLeaf = 'config/enumerate'
+                # if a path wasn't provided, default to recursive enumeration of \ved\policy
+                if ( -not $PSBoundParameters.ContainsKey('Path') ) {
+                    $params.Body['Recursive'] = 'true'
+                }
             }
 
-            'FindByPattern' {
-                $params.UriLeaf = 'config/enumerate'
-                $params.Body.Add( 'ObjectDN', '\VED' )
-                $params.Body.Add( 'Recursive', 'true' )
-            }
+            # 'FindByPattern' {
+            #     $params.UriLeaf = 'config/enumerate'
+            # }
 
-            'FindByClass*' {
+            'FindByClass' {
                 $params.UriLeaf = 'config/FindObjectsOfClass'
+                $params.Body['ObjectDN'] = $Path
             }
+
         }
 
         # add filters
         if ( $PSBoundParameters.ContainsKey('Pattern') ) {
             $params.Body.Add( 'Pattern', $Pattern )
         }
 
-        if ( $PSBoundParameters.ContainsKey('Attribute') ) {
-            $params.Body.Add( 'AttributeNames', $Attribute )
-        }
-
         if ( $PSBoundParameters.ContainsKey('Recursive') ) {
             $params.Body.Add( 'Recursive', 'true' )
         }
-    }
-
-    process {
-        if ( $PSBoundParameters.ContainsKey('Path') ) {
-            $params.Body['ObjectDN'] = $Path
-        }
 
         if ( $PSBoundParameters.ContainsKey('Class') ) {
             # the rest api doesn't have the ability to search for multiple classes and path at the same time

VenafiPS/Public/Get-TppAttribute.ps1

@@ -93,8 +93,8 @@ function Get-TppAttribute {
 
         [Parameter(Mandatory, ParameterSetName = 'EffectiveByPath', ValueFromPipeline, ValueFromPipelineByPropertyName)]
         [Parameter(Mandatory, ParameterSetName = 'ByPath', ValueFromPipeline, ValueFromPipelineByPropertyName)]
-        [Parameter(Mandatory, ParameterSetName = 'AllEffectivePath')]
-        [Parameter(Mandatory, ParameterSetName = 'PolicyPath')]
+        [Parameter(Mandatory, ParameterSetName = 'AllEffectivePath', ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [Parameter(Mandatory, ParameterSetName = 'PolicyPath', ValueFromPipeline, ValueFromPipelineByPropertyName)]
         [ValidateNotNullOrEmpty()]
         [ValidateScript( {
                 if ( $_ | Test-TppDnPath ) {