Update manifest and docs to 3.1.5 ***NO_CI***

Venafi · Jul 27, 2021 · d5babe8 · d5babe8
1 parent 57b6a9e
commit d5babe8
Show file tree

Hide file tree

Showing 7 changed files with 271 additions and 15 deletions.
diff --git a/VenafiPS/VenafiPS.psd1 b/VenafiPS/VenafiPS.psd1
@@ -3,7 +3,7 @@
 #
 # Generated by: Greg Brownstein
 #
-# Generated on: 7/26/2021
+# Generated on: 7/27/2021
 #
 
 @{
@@ -12,7 +12,7 @@
 RootModule = 'VenafiPS.psm1'
 
 # Version number of this module.
-ModuleVersion = '3.1.4'
+ModuleVersion = '3.1.5'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()
@@ -89,7 +89,7 @@ FunctionsToExport = 'Add-TppCertificateAssociation', 'ConvertTo-TppGuid',
                'Remove-TppPermission', 'Rename-TppObject', 'Revoke-TppCertificate', 
                'Revoke-TppToken', 'Set-TppAttribute', 'Set-TppCodeSignProjectStatus', 
                'Set-TppPermission', 'Set-TppWorkflowTicketStatus', 'Test-ModuleHash', 
-               'Test-TppIdentity', 'Test-TppObject', 'Write-TppLog'
+               'Test-TppIdentity', 'Test-TppObject', 'Test-TppToken', 'Write-TppLog'
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
 CmdletsToExport = @()

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,12 +1,19 @@
 ## 3.1.5
+- Thanks to @wilddev65 for this contribution
+- Add `Test-TppToken` function to test if a TPP token is valid.
+  - Tests an AccessToken, TppToken, or VenafiSession
+  - `-GrantDetail` parameter returns detailed info about token from TPP server response
+- Update `New-TppToken` to capture the refresh token expiry if part of the response.
+- Update `Find-TppCertificate` to add `-CertificateType` as a parameter to filter results by type of certificate.  Can use CodeSigning, Device, Server, and/or User.
+- Update `Get-VenafiCertificate` to get historical certificate versions with `-IncludePreviousVersions`.  `-ExcludeExpired` and `-ExcludeRevoked` filters the results.
+
+## 3.1.4
+- Fix [#19](https://github.com/gdbarron/VenafiPS/issues/19), `Revoke-TppToken -AccessToken` not decrypting password
 - Update `Set-TppAttribute`
   - Change from name and value parameters to hashtable
   - API calls were sending deprecated payloads, fix this
   - Add custom field validation and `-BypassValidation` switch.  The validation is field type aware and will validate string, date, list, and identity.
 
-## 3.1.4
-- Fix [#19](https://github.com/gdbarron/VenafiPS/issues/19), `Revoke-TppToken -AccessToken` not decrypting password
-
 ## 3.1.3
 - Add `-Force` parameter to `Revoke-TppToken` and `Revoke-TppCertificate` to bypass confirmation prompt
 

diff --git a/docs/functions/Find-TppCertificate.md b/docs/functions/Find-TppCertificate.md
@@ -14,10 +14,10 @@ Find-TppCertificate [-First <Int32>] [-Offset <Int32>] [-Country <String>] [-Com
  [-SanUri <String>] [-SerialNumber <String>] [-SignatureAlgorithm <String>] [-Thumbprint <String>]
  [-IssueDate <DateTime>] [-ExpireDate <DateTime>] [-ExpireAfter <DateTime>] [-ExpireBefore <DateTime>]
  [-Enabled] [-InError <Boolean>] [-NetworkValidationEnabled <Boolean>] [-CreatedDate <DateTime>]
- [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>] [-ManagementType <TppManagementType[]>]
- [-PendingWorkflow] [-Stage <TppCertificateStage[]>] [-StageGreaterThan <TppCertificateStage>]
- [-StageLessThan <TppCertificateStage>] [-ValidationEnabled] [-ValidationState <String[]>] [-CountOnly]
- [-VenafiSession <VenafiSession>] [<CommonParameters>]
+ [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>] [-CertificateType <String[]>]
+ [-ManagementType <TppManagementType[]>] [-PendingWorkflow] [-Stage <TppCertificateStage[]>]
+ [-StageGreaterThan <TppCertificateStage>] [-StageLessThan <TppCertificateStage>] [-ValidationEnabled]
+ [-ValidationState <String[]>] [-CountOnly] [-VenafiSession <VenafiSession>] [<CommonParameters>]
 ```
 
 ### ByPath
@@ -29,7 +29,7 @@ Find-TppCertificate -Path <String> [-Recursive] [-First <Int32>] [-Offset <Int32
  [-SanUpn <String>] [-SanUri <String>] [-SerialNumber <String>] [-SignatureAlgorithm <String>]
  [-Thumbprint <String>] [-IssueDate <DateTime>] [-ExpireDate <DateTime>] [-ExpireAfter <DateTime>]
  [-ExpireBefore <DateTime>] [-Enabled] [-InError <Boolean>] [-NetworkValidationEnabled <Boolean>]
- [-CreatedDate <DateTime>] [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>]
+ [-CreatedDate <DateTime>] [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>] [-CertificateType <String[]>]
  [-ManagementType <TppManagementType[]>] [-PendingWorkflow] [-Stage <TppCertificateStage[]>]
  [-StageGreaterThan <TppCertificateStage>] [-StageLessThan <TppCertificateStage>] [-ValidationEnabled]
  [-ValidationState <String[]>] [-CountOnly] [-VenafiSession <VenafiSession>] [<CommonParameters>]
@@ -44,7 +44,7 @@ Find-TppCertificate -Guid <Guid> [-Recursive] [-First <Int32>] [-Offset <Int32>]
  [-SanUpn <String>] [-SanUri <String>] [-SerialNumber <String>] [-SignatureAlgorithm <String>]
  [-Thumbprint <String>] [-IssueDate <DateTime>] [-ExpireDate <DateTime>] [-ExpireAfter <DateTime>]
  [-ExpireBefore <DateTime>] [-Enabled] [-InError <Boolean>] [-NetworkValidationEnabled <Boolean>]
- [-CreatedDate <DateTime>] [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>]
+ [-CreatedDate <DateTime>] [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>] [-CertificateType <String[]>]
  [-ManagementType <TppManagementType[]>] [-PendingWorkflow] [-Stage <TppCertificateStage[]>]
  [-StageGreaterThan <TppCertificateStage>] [-StageLessThan <TppCertificateStage>] [-ValidationEnabled]
  [-ValidationState <String[]>] [-CountOnly] [-VenafiSession <VenafiSession>] [<CommonParameters>]
@@ -627,6 +627,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -CertificateType
+Find certificate by category of usage.
+Use CodeSigning, Device, Server, and/or User.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -ManagementType
 Find certificates with a Management type of Unassigned, Monitoring, Enrollment, or Provisioning
 

diff --git a/docs/functions/Get-VenafiCertificate.md b/docs/functions/Get-VenafiCertificate.md
@@ -10,9 +10,15 @@ Get certificate information
 Get-VenafiCertificate [-VenafiSession <VenafiSession>] [<CommonParameters>]
 ```
 
+### OldVersions
+```
+Get-VenafiCertificate -CertificateId <String> [-IncludePreviousVersions] [-ExcludeExpired] [-ExcludeRevoked]
+ [-VenafiSession <VenafiSession>] [<CommonParameters>]
+```
+
 ### Id
 ```
-Get-VenafiCertificate [-CertificateId <String>] [-VenafiSession <VenafiSession>] [<CommonParameters>]
+Get-VenafiCertificate -CertificateId <String> [-VenafiSession <VenafiSession>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -41,6 +47,20 @@ Get-VenafiCertificate -CertificateId '\ved\policy\mycert.com'
 
 Get certificate info for a specific cert on TPP
 
+### EXAMPLE 4
+```
+Get-VenafiCertificate -CertificateId '\ved\policy\mycert.com' -IncludePreviousVersions
+```
+
+Get certificate info for a specific cert on TPP, including historical versions of the certificate.
+
+### EXAMPLE 5
+```
+Get-VenafiCertificate -CertificateId '\ved\policy\mycert.com' -IncludePreviousVersions -ExcludeRevoked -ExcludeExpired
+```
+
+Get certificate info for a specific cert on TPP, including historical versions of the certificate that are not revoked or expired.
+
 ## PARAMETERS
 
 ### -CertificateId
@@ -50,16 +70,63 @@ For TPP, use the full path.
 
 ```yaml
 Type: String
-Parameter Sets: Id
+Parameter Sets: OldVersions, Id
 Aliases: Path
 
-Required: False
+Required: True
 Position: Named
 Default value: None
 Accept pipeline input: True (ByPropertyName, ByValue)
 Accept wildcard characters: False
 ```
 
+### -IncludePreviousVersions
+Returns details about previous (historical) versions of a certificate (only from TPP).
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: OldVersions
+Aliases:
+
+Required: True
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ExcludeExpired
+Omits expired versions of the previous (historical) versions of a certificate (only from TPP).
+Can only be used with the IncludePreviousVersions parameter.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: OldVersions
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ExcludeRevoked
+Omits revoked versions of the previous (historical) versions of a certificate (only from TPP).
+Can only be used with the IncludePreviousVersions parameter.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: OldVersions
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -VenafiSession
 Session object created from New-VenafiSession method. 
 The value defaults to the script session object $VenafiSession.

diff --git a/docs/functions/New-TppToken.md b/docs/functions/New-TppToken.md
@@ -195,6 +195,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ###     TokenType
 ###     ClientId
 ###     Expires
+###     RefreshExpires (This property is null <version 21.1)
 ## NOTES
 
 ## RELATED LINKS
diff --git a/docs/functions/Test-TppToken.md b/docs/functions/Test-TppToken.md
@@ -0,0 +1,164 @@
+# Test-TppToken
+
+## SYNOPSIS
+Test if a Tpp token is valid
+
+## SYNTAX
+
+### Session (Default)
+```
+Test-TppToken [-GrantDetail] [-VenafiSession <VenafiSession>] [<CommonParameters>]
+```
+
+### AccessToken
+```
+Test-TppToken -AuthServer <String> -AccessToken <PSCredential> [-GrantDetail] [<CommonParameters>]
+```
+
+### TppToken
+```
+Test-TppToken -TppToken <PSObject> [-GrantDetail] [<CommonParameters>]
+```
+
+## DESCRIPTION
+Use the TPP API call 'Authorize/Verify' to test if the current token is valid.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```
+Test-TppToken
+```
+
+Verify that accesstoken stored in $VenafiSession object is valid.
+
+### EXAMPLE 2
+```
+$TppToken | Test-TppToken
+```
+
+Verify that token object from pipeline is valid.
+Can be used to validate directly object from New-TppToken.
+
+### EXAMPLE 3
+```
+Test-TppToken -AuthServer 'mytppserver.example.com' -AccessToken $cred
+```
+
+Verify that PsCredential object containing accesstoken is valid.
+
+### EXAMPLE 4
+```
+Test-TppToken -GrantDetail
+```
+
+Verify that accesstoken stored in $VenafiSession object is valid and return PsCustomObject as output with details.
+
+## PARAMETERS
+
+### -AuthServer
+Auth server or url, venafi.company.com or https://venafi.company.com.
+If just the server name is provided, https:// will be appended.
+
+```yaml
+Type: String
+Parameter Sets: AccessToken
+Aliases: Server
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -AccessToken
+Access token retrieved outside this module. 
+Provide a credential object with the access token as the password.
+
+```yaml
+Type: PSCredential
+Parameter Sets: AccessToken
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -TppToken
+Token object obtained from New-TppToken
+
+```yaml
+Type: PSObject
+Parameter Sets: TppToken
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -GrantDetail
+Provides detailed info about the token object from the TPP server response as an output.
+PSCustomObject with the following properties:
+    AuthUrl
+    AccessToken
+    RefreshToken
+    Scope
+    Identity
+    TokenType
+    ClientId
+    Expires
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -VenafiSession
+Session object created from New-VenafiSession method. 
+The value defaults to the script session object $VenafiSession.
+
+```yaml
+Type: VenafiSession
+Parameter Sets: Session
+Aliases:
+
+Required: False
+Position: Named
+Default value: $script:VenafiSession
+Accept pipeline input: False
+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
+
+### Accesstoken
+## OUTPUTS
+
+### Boolean (default). PSCustomObject (GrantDetail). Throws error if a 400 status is returned.
+## NOTES
+
+## RELATED LINKS
+
+[http://VenafiPS.readthedocs.io/en/latest/functions/Test-TppToken/](http://VenafiPS.readthedocs.io/en/latest/functions/Test-TppToken/)
+
+[https://github.com/gdbarron/VenafiPS/blob/main/VenafiPS/Code/Public/Test-TppToken.ps1](https://github.com/gdbarron/VenafiPS/blob/main/VenafiPS/Code/Public/Test-TppToken.ps1)
+
+[https://docs.venafi.com/Docs/20.4SDK/TopNav/Content/SDK/AuthSDK/r-SDKa-GET-Authorize-Verify.php?tocpath=Auth%20SDK%20reference%20for%20token%20management%7C_____13](https://docs.venafi.com/Docs/20.4SDK/TopNav/Content/SDK/AuthSDK/r-SDKa-GET-Authorize-Verify.php?tocpath=Auth%20SDK%20reference%20for%20token%20management%7C_____13)
+
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -62,5 +62,6 @@ pages:
     - Test-ModuleHash: functions/Test-ModuleHash.md
     - Test-TppIdentity: functions/Test-TppIdentity.md
     - Test-TppObject: functions/Test-TppObject.md
+    - Test-TppToken: functions/Test-TppToken.md
     - Write-TppLog: functions/Write-TppLog.md