diff --git a/VenafiPS/VenafiPS.psd1 b/VenafiPS/VenafiPS.psd1 index e5043e4d..1192070a 100644 --- 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 index 6a54fd5c..db157ff1 100644 --- 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 index 7a1ce219..ad5b4b2a 100644 --- a/docs/functions/Find-TppCertificate.md +++ b/docs/functions/Find-TppCertificate.md @@ -14,10 +14,10 @@ Find-TppCertificate [-First ] [-Offset ] [-Country ] [-Com [-SanUri ] [-SerialNumber ] [-SignatureAlgorithm ] [-Thumbprint ] [-IssueDate ] [-ExpireDate ] [-ExpireAfter ] [-ExpireBefore ] [-Enabled] [-InError ] [-NetworkValidationEnabled ] [-CreatedDate ] - [-CreatedAfter ] [-CreatedBefore ] [-ManagementType ] - [-PendingWorkflow] [-Stage ] [-StageGreaterThan ] - [-StageLessThan ] [-ValidationEnabled] [-ValidationState ] [-CountOnly] - [-VenafiSession ] [] + [-CreatedAfter ] [-CreatedBefore ] [-CertificateType ] + [-ManagementType ] [-PendingWorkflow] [-Stage ] + [-StageGreaterThan ] [-StageLessThan ] [-ValidationEnabled] + [-ValidationState ] [-CountOnly] [-VenafiSession ] [] ``` ### ByPath @@ -29,7 +29,7 @@ Find-TppCertificate -Path [-Recursive] [-First ] [-Offset ] [-SanUri ] [-SerialNumber ] [-SignatureAlgorithm ] [-Thumbprint ] [-IssueDate ] [-ExpireDate ] [-ExpireAfter ] [-ExpireBefore ] [-Enabled] [-InError ] [-NetworkValidationEnabled ] - [-CreatedDate ] [-CreatedAfter ] [-CreatedBefore ] + [-CreatedDate ] [-CreatedAfter ] [-CreatedBefore ] [-CertificateType ] [-ManagementType ] [-PendingWorkflow] [-Stage ] [-StageGreaterThan ] [-StageLessThan ] [-ValidationEnabled] [-ValidationState ] [-CountOnly] [-VenafiSession ] [] @@ -44,7 +44,7 @@ Find-TppCertificate -Guid [-Recursive] [-First ] [-Offset ] [-SanUpn ] [-SanUri ] [-SerialNumber ] [-SignatureAlgorithm ] [-Thumbprint ] [-IssueDate ] [-ExpireDate ] [-ExpireAfter ] [-ExpireBefore ] [-Enabled] [-InError ] [-NetworkValidationEnabled ] - [-CreatedDate ] [-CreatedAfter ] [-CreatedBefore ] + [-CreatedDate ] [-CreatedAfter ] [-CreatedBefore ] [-CertificateType ] [-ManagementType ] [-PendingWorkflow] [-Stage ] [-StageGreaterThan ] [-StageLessThan ] [-ValidationEnabled] [-ValidationState ] [-CountOnly] [-VenafiSession ] [] @@ -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 index 86c1494e..65f53289 100644 --- a/docs/functions/Get-VenafiCertificate.md +++ b/docs/functions/Get-VenafiCertificate.md @@ -10,9 +10,15 @@ Get certificate information Get-VenafiCertificate [-VenafiSession ] [] ``` +### OldVersions +``` +Get-VenafiCertificate -CertificateId [-IncludePreviousVersions] [-ExcludeExpired] [-ExcludeRevoked] + [-VenafiSession ] [] +``` + ### Id ``` -Get-VenafiCertificate [-CertificateId ] [-VenafiSession ] [] +Get-VenafiCertificate -CertificateId [-VenafiSession ] [] ``` ## 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 index 77e94875..7e539e28 100644 --- 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 ] [] +``` + +### AccessToken +``` +Test-TppToken -AuthServer -AccessToken [-GrantDetail] [] +``` + +### TppToken +``` +Test-TppToken -TppToken [-GrantDetail] [] +``` + +## 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 index 0a10d30d..346f2b0a 100644 --- 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