diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 71359c9b4..878f3bcf8 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -420,6 +420,11 @@ const config = { label: "Strata Cloud Manager API Best Practices", icon: "doc", }, + { + to: "/mim", + label: "Next-Gen Trust Security", + icon: "doc", + }, ], }, ], diff --git a/products/scm/api/config/mim/building-integrations/best-practices.md b/products/scm/api/config/mim/building-integrations/best-practices.md new file mode 100644 index 000000000..4d74ff8d8 --- /dev/null +++ b/products/scm/api/config/mim/building-integrations/best-practices.md @@ -0,0 +1,479 @@ +--- +id: building-integrations-best-practices +title: "Integration Best Practices" +sidebar_label: "Integration Best Practices" +keywords: + - Machine Identity Management + - Building Integrations +--- + +# Integration Best Practices + +Lessons learned from building CA connectors, machine connectors, and TPP adaptable drivers across dozens of platforms. + +--- + +## General Principles + +### Start with a Reference Implementation + +**CA Connectors**: Study the [DigiCert ONE connector](https://github.com/Venafi/digicert-ca-connector) for complete examples. + +**Machine Connectors**: Clone the [VMware Avi connector](https://github.com/Venafi/vmware-avi-connector) as your starting point. It includes: +- Correct project structure for vSatellite deployment +- Working Makefile with all required build targets +- Proper Dockerfile pattern (distroless, nonroot) +- Payload encryption middleware +- Correct manifest.json structure +- Proven dependency versions + +**TPP Drivers**: Review existing PowerShell drivers in the marketplace (search for "Adaptable" tag). + +**Don't start from scratch** — reference implementations save weeks of trial-and-error. + +--- + +## Error Handling + +### Extract Error Details from Responses + +APIs return errors in different formats. Implement flexible parsing: + +**Go (REST API)**: +```go +func parseAPIError(resp *resty.Response) error { + var errResp struct { + Error struct { + Code string `json:"code"` + Message string `json:"message"` + } `json:"error"` + Errors []struct { + Message string `json:"message"` + } `json:"errors"` + Message string `json:"message"` + } + + json.Unmarshal(resp.Body(), &errResp) + + // Try multiple formats + if errResp.Error.Message != "" { + return fmt.Errorf("%s: %s", errResp.Error.Code, errResp.Error.Message) + } + if len(errResp.Errors) > 0 { + return fmt.Errorf("%s", errResp.Errors[0].Message) + } + if errResp.Message != "" { + return fmt.Errorf("%s", errResp.Message) + } + + // Fallback to raw body + return fmt.Errorf("API error: %s", string(resp.Body())) +} +``` + +**PowerShell (TPP Driver)**: +```powershell +try { + Invoke-RestMethod -Uri $uri +} +catch { + $stream = $_.Exception.Response.GetResponseStream() + $reader = New-Object System.IO.StreamReader($stream) + $errorBody = $reader.ReadToEnd() | ConvertFrom-Json + + # Try multiple error fields + $message = $errorBody.error ?? $errorBody.message ?? $errorBody.detail ?? "Unknown error" + throw "[error] API call failed: $message" +} +``` + +### Return Proper HTTP Status Codes + +**Connectors (Go)**: Return HTTP 400 for all errors, HTTP 200 for success. The Venafi framework expects this convention. + +**TPP Drivers**: Throw exceptions with descriptive messages. Prefix with `[error]` for easy log filtering. + +--- + +## Logging + +### Use Structured Logging + +**Go (zap)**: +```go +logger.Debug("Installing certificate", + zap.String("hostname", hostname), + zap.String("certId", certId), + zap.String("operation", "install"), +) +``` + +**PowerShell**: +```powershell +Write-Host "[info] Installing certificate: certId=$certId, hostname=$hostname" +Write-Host "[error] Installation failed: $($_.Exception.Message)" +``` + +### Log at Debug Level in Production + +For connectors running on vSatellite, container logs are the only debugging interface. Set log level to Debug: + +```go +loggerConfig.Level = zap.NewAtomicLevelAt(zap.DebugLevel) +``` + +Log every step: authentication, API calls, response parsing, file operations. + +### What to Log + +✅ **Do log**: +- Every API call (URL, method, status code) +- Authentication attempts (success/failure) +- Certificate operations (install, extract, discover) +- Parsed response data (IDs, names, counts) +- Error details (codes, messages, stack traces) + +❌ **Don't log**: +- Passwords or API keys +- Private key material +- Full certificate PEMs (log thumbprints instead) +- Sensitive user data + +--- + +## Authentication + +### OAuth2 Client Credentials (Recommended) + +**Best for**: Modern REST APIs with service account support. + +**Implementation**: +- Request token per function call (don't cache) +- Store client ID and secret in secure fields +- Handle token errors gracefully + +**Example (PowerShell)**: +```powershell +function Get-OAuthToken { + param($ClientId, $ClientSecret, $TokenUrl) + + $body = @{ + grant_type = "client_credentials" + client_id = $ClientId + client_secret = $ClientSecret + } + + $response = Invoke-RestMethod -Uri $TokenUrl -Method Post -Body $body + return $response.access_token +} +``` + +### API Key Authentication + +**Best for**: Platforms with header-based auth. + +**Implementation**: +- Store key in Passwd/VarPass field +- Include in Authorization or custom header +- Validate key format in Test-Settings + +### Avoid Username/Password When Possible + +OAuth2 or API keys are more secure and easier to rotate. + +--- + +## Certificate Handling + +### Certificate Format Conversion + +**Venafi expects**: Base64-encoded DER bytes (not PEM strings). + +**Conversion pattern**: +```go +// Parse PEM +block, _ := pem.Decode([]byte(pemString)) +if block == nil { + return errors.New("invalid PEM") +} + +// Return base64 DER +certBase64 := base64.StdEncoding.EncodeToString(block.Bytes) +``` + +**Handle both PEM and DER input**: Some APIs return PEM, others return base64 DER. Try PEM first, fall back to DER. + +### CSR Handling + +**Send CSR with PEM headers**: Most CA APIs expect full PEM including `-----BEGIN CERTIFICATE REQUEST-----`. + +**Parse CSR to extract attributes**: Even if the CSR contains subject/SANs, many CAs require these as separate fields. + +```go +csr, _ := x509.ParseCertificateRequest(csrBytes) + +subject := map[string]string{ + "common_name": csr.Subject.CommonName, + "organization": csr.Subject.Organization[0], +} + +sans := csr.DNSNames +``` + +### DER vs PEM Pitfalls + +**Common mistakes**: +- Returning PEM when Venafi expects DER +- Stripping PEM headers when CA expects them +- Not validating certificate parsing before returning + +**Test both directions**: Create test cases for PEM→DER and DER→PEM conversions. + +--- + +## Discovery and Pagination + +### Always Implement Pagination + +Production environments may have hundreds or thousands of certificates. + +**Pattern (Go)**: +```go +allCerts := []Certificate{} +offset := 0 +limit := 100 + +for { + resp := client.ListCertificates(offset, limit) + allCerts = append(allCerts, resp.Items...) + + if len(resp.Items) < limit { + break // Last page + } + offset += limit +} +``` + +**Pattern (PowerShell)**: +```powershell +$allCerts = @() +$offset = 0 +$limit = 100 + +do { + $response = Invoke-Api -Endpoint "/certs?offset=$offset&limit=$limit" + $allCerts += $response.items + $offset += $limit +} while ($response.items.Count -eq $limit) +``` + +### Handle Parse Failures Gracefully + +One bad certificate shouldn't abort discovery of all others. + +```go +for _, item := range apiResponse.Items { + cert, err := parseCertificate(item.PEM) + if err != nil { + logger.Warn("Failed to parse certificate", zap.String("id", item.ID), zap.Error(err)) + continue // Skip this cert + } + results = append(results, cert) +} +``` + +### Sanitize Identifiers + +Platform-specific IDs may contain special characters. + +```go +sanitized := regexp.MustCompile(`[^a-zA-Z0-9-]`).ReplaceAllString(name, "-") +sanitized = strings.Trim(sanitized, "-") +``` + +--- + +## Testing Strategies + +### Unit Testing + +Test service interfaces in isolation: + +```go +func TestInstallCertificate(t *testing.T) { + mockClient := &MockAPIClient{ + InstallFunc: func(cert Certificate) (string, error) { + return "cert-123", nil + }, + } + + service := NewService(mockClient) + result, err := service.InstallCertificate(testCert) + + assert.NoError(t, err) + assert.Equal(t, "cert-123", result.AssetID) +} +``` + +### Integration Testing + +**For Connectors**: Use VenProxy simulation utility to test against local endpoints. + +**For TPP Drivers**: Test directly on TPP server with Test-Settings, Discovery jobs, and provisioning. + +### End-to-End Testing + +**Test the full lifecycle**: +1. Test-Settings (connectivity) +2. Discovery (enumeration) +3. Install (provisioning) +4. Extract (validation) +5. Renewal (install new + delete old) +6. Revocation (if applicable) + +--- + +## Security Considerations + +### Never Log Credentials + +```go +// ❌ BAD +logger.Debug("Auth successful", zap.String("password", password)) + +// ✅ GOOD +logger.Debug("Auth successful", zap.String("username", username)) +``` + +### Validate All Input + +```go +func validateHostname(hostname string) error { + if hostname == "" { + return errors.New("hostname is required") + } + if strings.Contains(hostname, "..") { + return errors.New("invalid hostname") + } + return nil +} +``` + +### Use TLS for All Connections + +Only allow insecure connections via explicit opt-in flag (Option1, etc.). + +### Handle Self-Signed Certificates Carefully + +Provide option to bypass certificate validation, but default to validation enabled. + +--- + +## Performance Optimization + +### Connection Pooling + +Reuse HTTP clients instead of creating new ones per request: + +```go +var httpClient = &http.Client{ + Timeout: 30 * time.Second, + Transport: &http.Transport{ + MaxIdleConns: 10, + IdleConnTimeout: 90 * time.Second, + }, +} +``` + +### Rate Limiting + +Implement retry with backoff for HTTP 429 responses: + +```go +client := resty.New(). + SetRetryCount(3). + SetRetryWaitTime(1 * time.Second). + SetRetryMaxWaitTime(30 * time.Second). + AddRetryCondition(func(r *resty.Response, err error) bool { + return r.StatusCode() == 429 // Rate limit + }) +``` + +### Batch Operations When Possible + +Group API calls to reduce round-trips: + +```go +// ❌ BAD: N+1 queries +for _, certId := range certIds { + cert := apiClient.GetCertificate(certId) +} + +// ✅ GOOD: Batch fetch +certs := apiClient.GetCertificatesBatch(certIds) +``` + +--- + +## Common Pitfalls + +### CA Connectors + +1. ❌ Returning PEM instead of base64 DER for certificate fields +2. ❌ Stripping PEM headers from CSR +3. ❌ Using flat attribute structure instead of nested (e.g., `attributes.subject.common_name`) +4. ❌ Not implementing retry on HTTP 429 rate limits +5. ❌ Hardcoding auth header name instead of making it configurable + +### Machine Connectors + +1. ❌ Not implementing pagination for discovery +2. ❌ Failing entire batch when one certificate fails to parse +3. ❌ Not cleaning up temp files in finally blocks +4. ❌ Caching connections across handler calls (each call is independent) +5. ❌ Not validating AssetName before using it in Extract-Certificate + +### TPP Adaptable Drivers + +1. ❌ Missing stub implementations for unused functions (TPP validates all 10) +2. ❌ Not re-saving policy after script changes (script won't be approved) +3. ❌ Making old certificate deletion fatal during renewal +4. ❌ Not sanitizing identifiers from target platforms +5. ❌ Forgetting to set AssetName after successful installation + +--- + +## Deployment Checklist + +### For Go-Based Connectors + +- [ ] Dockerfile uses distroless base image +- [ ] Container runs as nonroot user +- [ ] Makefile includes all required targets (build, test, docker-build, docker-push) +- [ ] Manifest.json validates against schema +- [ ] Payload encryption middleware is implemented +- [ ] All dependencies are pinned to specific versions +- [ ] Health check endpoint responds correctly +- [ ] Container logs are structured and debug-level + +### For PowerShell TPP Drivers + +- [ ] All 10 required functions exist (even if stubs) +- [ ] Field definitions block is correctly formatted +- [ ] Test-Settings validates all required fields +- [ ] AssetName is set correctly after Install-Certificate +- [ ] Discovery implements pagination +- [ ] Temp files are cleaned up in finally blocks +- [ ] Script is approved in TPP WebAdmin after any changes +- [ ] Error messages are descriptive and prefixed with [error] + +--- + +## Next Steps + +Apply these practices when building: +- [CA Connector Framework](/scm/api/config/mim/libraries-and-sdks/libraries-and-sdks-ca-framework) +- [Machine Connector Framework](/scm/api/config/mim/libraries-and-sdks/libraries-and-sdks-machine-framework) +- [TPP Adaptable App Drivers](/scm/api/config/mim/building-integrations/building-integrations-tpp-adaptable) + +Review your integration against this checklist before deploying to production. diff --git a/products/scm/api/config/mim/building-integrations/index.md b/products/scm/api/config/mim/building-integrations/index.md new file mode 100644 index 000000000..a56d34486 --- /dev/null +++ b/products/scm/api/config/mim/building-integrations/index.md @@ -0,0 +1,130 @@ +--- +id: building-integrations +title: "Overview" +sidebar_label: "Overview" +keywords: + - Machine Identity Management + - Building Integrations +--- + +# Building Integrations + +## Introduction + +Machine identity integrations connect Venafi's platforms with external systems for managing certificates, code signing, SSH keys, and more. This section provides guidance on building integrations for your own environment. + +**Important**: You do NOT need to contribute your integration to the public marketplace. Build what you need for your organization, and only package it for public distribution if you want to share with the broader community. + +--- + +## Integration Types + +### CA Connectors + +**Purpose**: Issue certificates from external Certificate Authorities + +CA connectors are REST-based web services that communicate between Venafi platforms and third-party CAs. They handle authentication, product/option retrieval, certificate requests, and certificate issuance. + +**When to use**: +- Integrating with a new Certificate Authority +- Need certificate issuance workflows +- Support for Certificate Manager SaaS or NGTS + +**Learn more**: [CA Connector Framework](/scm/api/config/mim/libraries-and-sdks/libraries-and-sdks-ca-framework) + +--- + +### Machine Connectors + +**Purpose**: Deploy certificates to servers, load balancers, and network devices + +Machine connectors are plugins that push and configure certificates from Venafi to target applications. They handle authentication, certificate installation, and service configuration. + +**When to use**: +- Deploying certificates to new device/platform types +- Automating certificate lifecycle on servers +- Support for Certificate Manager SaaS or NGTS + +**Learn more**: [Machine Connector Framework](/scm/api/config/mim/libraries-and-sdks/libraries-and-sdks-machine-framework) + +--- + +### TPP Adaptable App Drivers + +**Purpose**: Extend Certificate Manager Self-Hosted (formerly TLS Protect Datacenter) + +Adaptable App Drivers are PowerShell-based integrations specifically for Certificate Manager Self-Hosted. They provide a lighter-weight alternative to full Go-based connectors. + +**When to use**: +- Targeting Certificate Manager Self-Hosted only (not SaaS/NGTS) +- Need rapid development (PowerShell vs Go) +- Integrating with Windows-based systems +- Don't need advanced features like discovery + +**Learn more**: [TPP Adaptable App Drivers](/scm/api/config/mim/building-integrations/building-integrations-tpp-adaptable) + +--- + +### REST API & VCert SDK + +**Purpose**: Programmatic certificate operations and automation + +Direct API integration or SDK usage for custom applications and automation scripts. + +**When to use**: +- Quick prototyping and testing +- Custom automation scripts +- Integration into existing applications +- Direct control over certificate operations + +**Learn more**: +- [Certificate Manager SaaS APIs](/api-endpoints/saas/certificate-manager-saas-api) +- [VCert SDK](/scm/api/config/mim/libraries-and-sdks/libraries-and-sdks-vcert) +- [VenafiPS PowerShell Module](/scm/api/config/mim/libraries-and-sdks/libraries-and-sdks-venafips) + +--- + +## Decision Matrix + +Choose the right approach for your use case: + +| Use Case | Recommended Approach | +|----------|---------------------| +| Deploy certificates to new device type | Machine Connector Framework | +| Connect to new Certificate Authority | CA Connector Framework | +| Extend TLS Protect Self-Hosted with PowerShell | TPP Adaptable App Driver | +| Automate certificate operations in scripts | VCert SDK or REST API | +| Prototype and test quickly | VCert SDK or REST API | +| Build production-grade multi-platform connector | CA/Machine Connector Framework | + +--- + +## Development Workflow + +1. **Choose your approach** using the decision matrix above +2. **Review the framework documentation** for your chosen approach +3. **Set up your development environment** following the framework guide +4. **Implement your integration** using provided templates and patterns +5. **Test locally** using simulation tools (VenProxy for connectors) +6. **Deploy to your environment** for production use + +**Optional**: If you want to share your integration publicly, see [Contributing to the Marketplace](/scm/api/config/mim/contributing-to-the-marketplace) for packaging and submission guidance. + +--- + +## Best Practices + +Review [Integration Best Practices](/scm/api/config/mim/building-integrations/building-integrations-best-practices) for: +- Error handling patterns +- Logging standards +- Testing strategies +- Security considerations +- Performance optimization + +--- + +## Getting Help + +- **Framework Documentation**: See individual framework guides for detailed implementation guidance +- **GitHub Issues**: [Report bugs or request features](https://github.com/paulternate/mis-marketplace/issues) +- **Support**: cybr-mis.support@paloaltonetworks.com diff --git a/products/scm/api/config/mim/building-integrations/tpp-adaptable-app.md b/products/scm/api/config/mim/building-integrations/tpp-adaptable-app.md new file mode 100644 index 000000000..fce4d26ef --- /dev/null +++ b/products/scm/api/config/mim/building-integrations/tpp-adaptable-app.md @@ -0,0 +1,475 @@ +--- +id: building-integrations-tpp-adaptable +title: "TPP Adaptable App Drivers" +sidebar_label: "TPP Adaptable App Drivers" +keywords: + - Machine Identity Management + - Building Integrations +--- + +# TPP Adaptable App Drivers + +## Overview + +TPP Adaptable App Drivers are PowerShell-based integrations for **Certificate Manager Self-Hosted** (formerly TLS Protect Datacenter/TPP). They provide a flexible way to extend certificate deployment capabilities without building full Go-based connectors. + +**Key characteristics**: +- PowerShell-based (easier development than Go) +- Runs directly on TPP server +- Certificate Manager Self-Hosted only (not SaaS or NGTS) +- Suitable for internal-use integrations +- No container deployment required + +--- + +## When to Use Adaptable Drivers + +### Choose Adaptable Drivers when: +- Targeting **Certificate Manager Self-Hosted only** (not SaaS/NGTS) +- Need **rapid development** (PowerShell vs Go) +- Integrating with **Windows-based systems** +- Building for **internal use** (not distributing publicly) +- Don't need advanced features like discovery hooks + +### Choose Machine Connector Framework when: +- Need **cross-platform support** (SaaS, Self-Hosted, NGTS) +- Building **production-grade connectors** for public distribution +- Need **container deployment** +- Require advanced discovery capabilities +- Want framework validation and testing tools + +--- + +## How Adaptable Drivers Work + +An adaptable driver is a single PowerShell (.ps1) script that implements 10 required functions: + +| Function | Purpose | Required | +|----------|---------|----------| +| `Test-Settings` | Validate configuration and connectivity | Yes (must work) | +| `Discover-Certificates` | Find existing certificates on target platform | Yes (if discovery needed) | +| `Install-Certificate` | Deploy certificate to target platform | Yes (must work) | +| `Extract-Certificate` | Retrieve certificate for validation | Yes (must work) | +| `Install-Chain` | Deploy intermediate certificates | Optional (stub) | +| `Install-PrivateKey` | Deploy private key separately | Optional (stub) | +| `Update-Binding` | Configure service bindings | Optional (stub) | +| `Activate-Certificate` | Enable/activate deployed certificate | Optional (stub) | +| `Extract-PrivateKey` | Retrieve private key | Optional (stub) | +| `Remove-Certificate` | Delete certificate from target | Optional (stub) | + +**Important**: All 10 functions must exist in the script (TPP validates at load time), but you only need real logic in 4-5 of them. The rest can be stubs returning `@{ Result = "NotUsed" }`. + +--- + +## Authentication Patterns + +### OAuth2 Client Credentials (Recommended) + +Cleanest pattern for API-based integrations. No interactive login required. + +**Field definitions**: +``` +Text1|API Client ID|111 +Passwd|API Client Secret|111 +``` + +**Authentication code pattern**: +```powershell +function Get-ApiToken { + param($General) + + $tokenUrl = "https://$($General.HostAddress)/oauth2/token" + $body = @{ + grant_type = "client_credentials" + client_id = $General.VarText1 + client_secret = $General.VarPass + } + + $response = Invoke-RestMethod -Uri $tokenUrl -Method Post -Body $body + return $response.access_token +} +``` + +### API Key / Header Token + +For platforms using header-based authentication: + +**Field definitions**: +``` +Passwd|API Key|111 +``` + +**Usage**: +```powershell +$headers = @{ + "Authorization" = "Bearer $($General.VarPass)" +} +``` + +### Basic Authentication + +For platforms using username/password: + +**Field definitions**: +``` +Text1|Username|111 +Passwd|Password|111 +``` + +--- + +## Required Functions + +### Test-Settings + +**When called**: Admin saves the certificate object configuration in TPP WebAdmin. + +**Purpose**: Validate all required fields are populated and prove authentication/connectivity works. + +**Implementation**: +```powershell +function Test-Settings { + param( + [Parameter(Mandatory)] [hashtable] $General, + [Parameter()] [hashtable] $Specific = @{} + ) + + # Validate required fields + Assert-Field $General "HostAddress" "Required" + Assert-Field $General "VarText1" "Required" + Assert-Field $General "VarPass" "Required" + + # Test authentication + try { + $token = Get-ApiToken -General $General + return @{ Result = "Success" } + } + catch { + throw "Authentication failed: $_" + } +} +``` + +--- + +### Discover-Certificates + +**When called**: A Discovery job runs against the device. + +**Purpose**: Enumerate all certificates on the target platform. + +**Returns**: Array of discovered certificates with Name, PEM, and metadata. + +**Implementation tips**: +- **Always implement pagination** — production may have hundreds of certificates +- Use try/catch per certificate — one bad cert shouldn't abort discovery +- Sanitize identifiers (remove special characters) +- Use prefixes to distinguish cert types: `Platform-CertType-123` + +**Example return structure**: +```powershell +@{ + Result = "Success" + Applications = @( + @{ + Name = "Example-ServiceCert-123" + ApplicationClass = "Adaptable App" + PEM = "-----BEGIN CERTIFICATE-----..." + CertificateName = "example.com" + } + ) +} +``` + +--- + +### Install-Certificate + +**When called**: Provisioning or renewal of a certificate. + +**Purpose**: Deploy certificate to target platform. + +**Parameters provided**: +- `$Specific.CertPem` — Certificate in PEM format +- `$Specific.PrivKeyPem` — Private key in PEM format +- `$Specific.ChainPem` — Chain/intermediates in PEM format +- `$Specific.Pkcs12` — PKCS#12 bundle as byte array +- `$Specific.EncryptPass` — PKCS#12 password +- `$General.AssetName` — Previous certificate ID (on renewal) + +**Must return**: `@{ Result = "Success"; AssetName = "cert-id-123" }` + +**AssetName is critical**: This value persists and is used by Extract-Certificate and future renewals. + +**Renewal pattern**: +```powershell +# Install new certificate +$newCertId = (Invoke-Api -Endpoint "/certificates" -Method Post -Body $certData).id + +# Delete old certificate (non-fatal) +if ($General.AssetName) { + try { + Invoke-Api -Endpoint "/certificates/$($General.AssetName)" -Method Delete + } + catch { + Write-Warning "Could not delete old certificate: $_" + } +} + +return @{ Result = "Success"; AssetName = $newCertId } +``` + +--- + +### Extract-Certificate + +**When called**: Certificate inventory/validation. + +**Purpose**: Retrieve certificate for verification. + +**Returns**: Certificate PEM, serial number, and thumbprint. + +**Example**: +```powershell +function Extract-Certificate { + param( + [Parameter(Mandatory)] [hashtable] $General, + [Parameter()] [hashtable] $Specific = @{} + ) + + # Get certificate using AssetName + $cert = Invoke-Api -Endpoint "/certificates/$($General.AssetName)" + + # Parse PEM to extract serial and thumbprint + $x509 = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new( + [System.Text.Encoding]::ASCII.GetBytes($cert.pem) + ) + + return @{ + Result = "Success" + CertPem = $cert.pem + Serial = $x509.GetSerialNumberString() + Thumprint = $x509.Thumbprint # Note: no 'b'! + } +} +``` + +--- + +## Best Practices + +### Script Validation + +TPP validates all 10 required functions at script load time. Include stub implementations for unused functions: + +```powershell +function Install-Chain { + return @{ Result = "NotUsed" } +} +``` + +### Error Handling + +Extract error details from API responses: + +```powershell +try { + Invoke-RestMethod -Uri $uri -Method Post +} +catch { + $stream = $_.Exception.Response.GetResponseStream() + $reader = New-Object System.IO.StreamReader($stream) + $errorBody = $reader.ReadToEnd() | ConvertFrom-Json + throw "[error] API returned: $($errorBody.message)" +} +``` + +### Pagination + +Always implement pagination for discovery: + +```powershell +$allCerts = @() +$offset = 0 +$limit = 100 + +do { + $response = Invoke-Api -Endpoint "/certificates?offset=$offset&limit=$limit" + $allCerts += $response.items + $offset += $limit +} while ($response.items.Count -eq $limit) +``` + +### Self-Signed Certificate Handling + +For platforms with self-signed TLS certificates, implement optional validation bypass: + +```powershell +if ($General.Option1) { + Add-Type @" + public class TrustAllCertsPolicy : System.Net.ICertificatePolicy { + public bool CheckValidationResult( + System.Net.ServicePoint srvPoint, + System.Security.Cryptography.X509Certificates.X509Certificate certificate, + System.Net.WebRequest request, + int certificateProblem) { + return true; + } + } +"@ + [System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy +} +``` + +--- + +## Development Workflow + +### 1. Set up prerequisites on target platform + +- Create API client credentials (OAuth2 apps, API keys, etc.) +- Document the one-time setup steps +- Verify API endpoints are accessible + +### 2. Create driver script + +**Location**: `C:\Program Files\Venafi\Scripts\AdaptableApp\YourDriver.ps1` + +**Start with skeleton**: +```powershell +<# +.SYNOPSIS + Adaptable App driver for [Platform Name] + +.DESCRIPTION + Deploys certificates to [Platform Name] via REST API + +.FIELD DEFINITIONS + Text1|API Client ID|111 + Passwd|API Client Secret|111 + Option1|Disable SSL Validation|0 +#> + +# Helper functions +function Assert-Field { ... } +function Get-ApiToken { ... } +function Invoke-Api { ... } + +# Required functions (10 total) +function Test-Settings { ... } +function Discover-Certificates { ... } +function Install-Certificate { ... } +function Extract-Certificate { ... } + +# Stub functions +function Install-Chain { return @{ Result = "NotUsed" } } +function Install-PrivateKey { return @{ Result = "NotUsed" } } +function Update-Binding { return @{ Result = "NotUsed" } } +function Activate-Certificate { return @{ Result = "NotUsed" } } +function Extract-PrivateKey { return @{ Result = "NotUsed" } } +function Remove-Certificate { return @{ Result = "NotUsed" } } +``` + +### 3. Test in TPP + +1. Copy script to `C:\Program Files\Venafi\Scripts\AdaptableApp\` on TPP server +2. In TPP WebAdmin, create or edit Adaptable App driver object +3. Select your script from the dropdown +4. **Save the policy** (this approves the script for execution) +5. Configure a device with HostAddress, credentials +6. Run Test-Settings to verify connectivity +7. Run Discovery job to test enumeration +8. Provision test certificate to verify installation +9. Check Extract-Certificate returns correct data + +### 4. Handle script changes + +**Important**: Every time you modify the .ps1 file, you MUST re-save the policy object in WebAdmin. Without this, TPP shows: "The current PowerShell script is not yet allowed." + +--- + +## Common Patterns + +### Centralized API wrapper + +```powershell +function Invoke-PlatformApi { + param( + [string]$Endpoint, + [string]$Method = "Get", + [object]$Body + ) + + $token = Get-ApiToken -General $General + $uri = "https://$($General.HostAddress):$($General.TcpPort)$Endpoint" + + $headers = @{ + "Authorization" = "Bearer $token" + "Content-Type" = "application/json" + } + + $params = @{ + Uri = $uri + Method = $Method + Headers = $headers + } + + if ($Body) { + $params.Body = ($Body | ConvertTo-Json -Depth 10) + } + + try { + return Invoke-RestMethod @params + } + catch { + # Extract error details + $stream = $_.Exception.Response.GetResponseStream() + $reader = New-Object System.IO.StreamReader($stream) + $errorBody = $reader.ReadToEnd() + throw "[error] API call failed: $errorBody" + } +} +``` + +### File cleanup pattern + +```powershell +$tempFile = $null +try { + # Create temp file + $tempFile = Join-Path $env:TEMP "cert-$([guid]::NewGuid()).p12" + [System.IO.File]::WriteAllBytes($tempFile, $Specific.Pkcs12) + + # Use file... +} +finally { + if ($tempFile -and (Test-Path $tempFile)) { + Remove-Item $tempFile -Force + } +} +``` + +--- + +## Examples + +Browse existing adaptable drivers in the marketplace: + +- Search for integrations with tag "Adaptable" at [pan.dev/mis/marketplace](https://pan.dev/mis/marketplace) +- Review PowerShell scripts in the `/Integrations/` directory +- Study authentication patterns (OAuth2, API key, Basic) + +--- + +## Next Steps + +- **Building for internal use?** You're done — deploy and use your driver +- **Want to share publicly?** See [Contributing to the Marketplace](/scm/api/config/mim/contributing-to-the-marketplace) for packaging guidance + +--- + +## Getting Help + +- **TPP Documentation**: Refer to Certificate Manager Self-Hosted admin guides +- **GitHub Issues**: [Report bugs or request features](https://github.com/paulternate/mis-marketplace/issues) +- **Support**: cybr-mis.support@paloaltonetworks.com diff --git a/products/scm/api/config/mim/certification/index.md b/products/scm/api/config/mim/certification/index.md new file mode 100644 index 000000000..07c222279 --- /dev/null +++ b/products/scm/api/config/mim/certification/index.md @@ -0,0 +1,139 @@ +--- +id: ecosystem-certification-tlspc +title: "CyberArk Trust Protection Foundation - SaaS" +sidebar_label: "CyberArk Trust Protection Foundation - SaaS" +keywords: + - Machine Identity Management + - Ecosystem Certification +--- + +## Trust Protection Foundation - SaaS Certification + +This page is meant to be your home base throughout the certification process, so please feel free to jump around, read ahead, bookmark and come back to it as needed. + +> ✅ Ready to certify? +> +>If you've already completed your solution, understand and meet the necessary requirements and are ready to submit a request for Certification, you can [start here.](#submit-your-solution) + +### Introduction + +As a **CyberArk Trust Protection Foundation - SaaS Certified** solution, you have an extra level of confidence that your solution was designed with your best interests at the forefront. For that reason, certified solutions see more adoption from our mutual users. When building a solution for Trust Protection Foundation, one desired outcome should be official certification. Official certification is the first step to listing the solution on the [CyberArk Marketplace](https://community.cyberark.com/marketplace/), which is the #1 way end users discover and deploy solutions. + +> ✅ Success +> +> Certification is the only way that a solution will be listed on the CyberArk Marketplace as compatible with Certificate Manager - SaaS. + +![Certify](/img/mim/tls-protect-cloud-certification/certify-chart.png) + +The Certificate Manager - SaaS Certification Program is still evolving and so some specifics about the following requirements are subject to change. Ample notice will be given to any developers of an existing certified solution, ensuring plenty of time to make any necessary updates to maintain certification. + +The following requirements are applicable to every Certificate Manager - SaaS solution, however there may be additional, unlisted requirements depending on the specific use case of the solution. There will be solutions and use cases that come forward that are totally new and unique from every solution that has gone through the certification process - and that's GREAT! It means machine identity management is continuing to evolve and see continued adoption. + +> ℹ️ We're all in this together +> +> In cases where the CyberArk team requests additional requirements be met, we will work with you to determine what success looks like and do our best to provide any Tools/guidance necessary to reach certification. + +### Technical Certification vs. Partner Program + +The technical certification process is not to be confused with CyberArk Partnership, though the two are related. The best way to think about it would be "Packaging" vs. "Marketing". + +#### Packaging + +The final step of the Certificate Manager - SaaS certification process will be ***Packaging*** - deciding how end users will deploy and interact with your solution. In order for end users to discover the solution and establish a strong user base, the packaging of the solution should be polished and easy to understand. Use of company logos, iconography, product names, marketing copy, etc. will all help users quickly identify your solution in the growing [CyberArk Marketplace](https://community.cyberark.com/marketplace/). + +![Package](/img/mim/tls-protect-cloud-certification/package-chart.png) + +#### Marketing + +***Marketing***, on the other hand, focuses on bringing attention to a fully packaged & published solution. Once the solution has been certified and the initial Marketplace Listing has been created, the next logical step would be an official partnership with CyberArk, which will also engage the CyberArk Marketing team to start making some noise about the new solution available to CyberArk users. + +## Requirements + +There are currently two levels of certification for Certificate Manager - SaaS solutions, **Foundation Certification** and **Advanced Certification**. It's our hope that every developer strives for the most comprehensive solution, but understand that isn't always possible due to resource and/or time constraints. The purpose of creating multiple levels of certification is two-fold: + +- It provides a lower barrier to entry for smaller organizations and individual contributors +- It provides an opportunity for developers to further differentiate their solution by providing additional collateral that will help end users get started [#fastsecure](https://www.venafi.com/blog/why-fastsecure-future-machine-identity-management) when using the solution. + +Meeting the requirements for Foundation Certification should be the first point of focus for any new developer. These requirements have been designed to create a simple pathway for developers to get a listing onto the CyberArk Marketplace, while ensuring a consistent, stable experience for all Certificate Manager - SaaS end users. All Certificate Manager - SaaS solutions that are published on the CyberArk Marketplace are required to meet the requirements for Foundation Certification. + +Advanced Certification provides a means to differentiate a solution that goes above & beyond the requirements specified above. Functionally, both Foundation Certification and Advanced Certification have the same technical requirements. The difference between the two levels is really about end user enablement and ongoing testing to ensure the solution remains fully functional. + +From an end user's perspective, generally the more collateral available to be consumed, the less likely end users are to have questions that might block them from testing and ultimately utilizing the solution. The easier it is to deploy and test the solution, the more widely adopted that solution becomes throughout the user base. More users generate more feedback and ideas, and the solution becomes more robust as a result. + +### Certification Requirements + +#### Foundation + +- [x] The description of the solution is an accurate representation of functionality. +- [x] The solution doesn't interfere with Certificate Manager - SaaS native functionality or performance. +- [x] The solution was developed with overall security best practices in mind and makes no attempts to harvest user data. +- [x] The solution uses generally available interfaces to interact with Certificate Manager - SaaS (VCert, REST API, etc.). +- [x] Accompanying documentation must be packaged with the solution and should include any necessary configuration instructions as well as clear usage examples. [Templates are provided](https://coolsolutions.venafi.com/ecosystem/example-solution-repo) for this purpose. (**NOTE:** a free [CyberArk Account](https://success.venafi.com/signin/register) will be required to access this resource) +- [x] The support model is clearly defined for all user types. +- [x] A demonstration of all documented functionality must be [scheduled](https://venafi-service-certification.paperform.co) & completed with the CyberArk Ecosystem team. + +#### Advanced + +Everything listed in the Foundation Certification Requirements section tab be completed, in addition to the following: + +- [x] A 5-10 minute technical demonstration video covering any initial configuration and typical usage examples must be available online. +- [x] When necessary, and if possible/feasible for the solution, a test instance or account will be provided to the CyberArk Ecosystem team for internal testing and demonstration purposes. +- [x] Automated testing must be put in place to test all documented functionality of your solution. +- [x] All REST endpoints and/or VCert functions used by the solution must be documented and provided to CyberArk. + +These will be used internally by CyberArk to track which features & functions are being used most by developers and end users. They will not be shared publicly. + +> ℹ️ Do you have feedback about the certification process? +> +> We've tried to make the certification process as simple and pain free as possible, but we're always looking to make it better. If you have any suggestions or feedback to improve the process, [we'd love to hear them](mailto:ecosystem@venafi.com?subject=TLSPC+Certification+Feedback)! + +## Resources & FAQs + +Below are some useful resources and frequently asked questions from previous developers who've already completed the certification process: + +### Resources + +> ⚠️ Account Required +> +> Some of the resources on this page will require a [CyberArk user account](https://success.venafi.com) in order to access. Please feel free to create one. If you encounter any issues, [please let us know](mailto:ecosystem@venafi.com?subject=ecosystem.venafi.com+feedback). + +- [Certificate Manager - SaaS API Documentation](/api-endpoints/saas/certificate-manager-saas-api) +- [Example Solution Repo](https://coolsolutions.venafi.com/ecosystem/example-integration-repo) - This provides a thorough example of how the README.md file should be created to be most impactful for CyberArk users. Rather than creating Word documents or PDFs, all documentation should start in Markdown, which provides better version control and can then be easily translated to other formats as needed. +- [CyberArk Marketplace](https://community.cyberark.com/marketplace/) - Explore the Marketplace to get an idea about some of the existing solutions to CyberArk. + +### FAQs + +
+Will my solution be listed on the CyberArk Marketplace if I don't pursue official certification? + +> ✅ Your solution may still be listed if it works with Certificate Manager - Self-Hosted, but it will not be listed as officially compatible with Certificate Manager - SaaS and will not have the official badge of certification. + +
+ +
+How long will the certification process take? + +> ✅ The certification process itself moves relatively quickly - you've already done the time-consuming part building and documenting the solution. Once you've submitted a Request for Certification, it typically takes only a couple of days to schedule the final milestone demo (a short session for you to demonstrate the described functionality to the CyberArk Ecosystem team). + +
+ +
+Will I receive any marketing assets that I can use on my own websites and collateral? + +> ✅ Yes, definitely! We love seeing CyberArk certification badges out in the wild. Official badges will be provided upon completion of the certification process. + +
+
+How often will I be required to re-certify my solution? + +> ✅ For now, we'd like you to re-certify for any Major release or feature addition/enhancement. Minor releases don't require re-certification. If you've just released a new Major version or added a new feature, please submit a new certification request. + +[Submit Certification Request](https://venafi-service-certification-request.paperform.co) + +
+ +## Submit Your Solution + +Once your solution has been built and been tested internally by your team, you've produced any accompanying documentation and you've recorded a short video demo walking through each supported function of your solution, your solution is ready for certification! + +[Submit Certification Request](https://venafi-service-certification-request.paperform.co) \ No newline at end of file diff --git a/products/scm/api/config/mim/code-sign-manager/_authenticate-using-api-key.md b/products/scm/api/config/mim/code-sign-manager/_authenticate-using-api-key.md new file mode 100644 index 000000000..da05080a2 --- /dev/null +++ b/products/scm/api/config/mim/code-sign-manager/_authenticate-using-api-key.md @@ -0,0 +1,110 @@ +--- +title: Authenticate using a user API key +id: code-sign-client-auth-user +slug: /dev-docs/code-sign-client-auth-user +sidebar_position: 3 +--- + +You can authenticate the CyberArk Code Sign Client using a user API key when signing operations should run on behalf of an individual developer or engineer. Once authenticated, the client can list and use any Signing Keys the user has been authorized to access in CyberArk Code Sign Manager – SaaS. + +> See the [API key authentication end-to-end tutorial](https://docs.cyberark.com/mis-saas/CSH_csm_api_key_tutorial/) for an overview of the entire process. + +## Before you begin + +Make sure: + +- You have a CyberArk Certificate Manager – SaaS account. +- Your administrator has assigned you as an Authorized Signer on at least one Project in Code Sign Manager – SaaS. +- You have [generated or retrieved your API key](https://docs.cyberark.com/mis-saas/CSH_get_api_key/) from the Certificate Manager – SaaS UI. +- You must have the [Code Sign Client installed](/scm/api/config/mim/code-sign-manager/code-sign-client-install). + +## Authenticate using API key + +**Obtain your API key** +1. [Sign in](https://docs.cyberark.com/mis-saas/CSH_sign_in/) to Certificate Manager – SaaS. +1. Select your avatar in the top-right corner, and then click **Preferences**. +1. From **API keys**, copy your API key. + + !!! note + If you do not have an API key yet, select **Generate** at the bottom of the screen. + +**Authenticate from your client** + +1. On your signing workstation, run the following to sign in using the Code Sign Client: + + ```bash + pkcs11config login + ``` + This launches the interactive configuration wizard. + + 1. Enter the hostname of the Code Sign Manager server for [your region](/scm/api/config/mim/tls-protect-cloud/control-plane-api-endpoints). + 1. When prompted for an authentication method, select **API key**. + 1. Enter your API key. + +1. (Optional) Verify your configuration. + + ```bash + pkcs11config option show + ``` + + Your result should look similar to the following: + ``` + Name │ Value + ─────────────────┼─────────────────────────────────────────────────── + HSM SERVER URL │ https://api.venafi.cloud/vedhsm/ + SUPPORTS API KEY │ true + AUTH SERVER URL │ https://api.venafi.cloud/ + API KEY │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + CSC SERVER URL │ https://dl.venafi.cloud/cyberark-code-sign-client/ + ``` + +**List your keys and certificates** + +If your administrator has given your user identity access to a Project that contains one or more Signing Keys, you should be able to list those signing objects now. + +```bash +pkcs11config list +``` + +Your result should look similar to the following: +``` +Certificate 1: +Label: Project Name-Key Name +Subject: CN=Example\, Inc. +ID: 34353563356132632D333634392D343065652D616261302D306132623436326632333466 +Environment: Certificate + +Public Key 1: +Label: Project Name-Key Name +Key-Type: RSA 2048 +ID: 34353563356132632D333634392D343065652D616261302D306132623436326632333466 +Environment: Certificate +``` + +If you do not see any objects, confirm that you are assigned as an Authorized Signer on the Project. + + +## Troubleshooting + +### “INFO: No objects available.” +This means the client authenticated successfully, but your user is not authorized to use any Signing Keys. + +Verify that: + +- You are assigned as an Authorized Signer on the Project +- You belong to a Team that is assigned as an Authorized Signer. + +### “Authentication failed” +Check the following: + +- Confirm you entered the [regional API hostname](/scm/api/config/mim/tls-protect-cloud/control-plane-api-endpoints), not a tenant URL. +- Make sure the API key is valid and has not been regenerated or revoked. + +--- + +## What's next + +After authenticating with your user API key, you can: + +- [Perform a test signing](/scm/api/config/mim/code-sign-manager/code-sign-client-test-signing) +- Integrate signing into your build tools. See the sample integrations in this section. diff --git a/products/scm/api/config/mim/code-sign-manager/authenticate-using-service-account.md b/products/scm/api/config/mim/code-sign-manager/authenticate-using-service-account.md new file mode 100644 index 000000000..d343c0352 --- /dev/null +++ b/products/scm/api/config/mim/code-sign-manager/authenticate-using-service-account.md @@ -0,0 +1,48 @@ +--- +id: code-sign-client-auth-service-account +title: "Authenticate using a service account" +sidebar_label: "Authenticate using a service account" +keywords: + - Machine Identity Management + - Code Sign Manager +--- + +Service accounts allow the Code Sign Client to authenticate as a machine identity rather than a user. This is the recommended approach for automated signing environments such as CI/CD pipelines or build servers. + +Because the service account setup requires interaction with the Strata Cloud Manager UI, the full procedure is documented in the main product documentation. + +> For the complete end-to-end process, see the **[service account authentication tutorial](https://docs.cyberark.com/mis-saas/CSH_csm_service_account_tutorial/)**. + +## Before you begin + +- An administrator has created a service account for NGTS +- You are a member of the service account’s Owning Team +- The service account is assigned as an Authorized Signer on at least one Project +- The Code Sign Client is installed on the signing machine + +## How service account authentication works + +Here is a high-level view of the workflow, regardless of platform: + +1. An administrator configures the Project, Signing Key, Team, and service account. +2. The Code Sign Client generates a key pair on the signing machine. +3. You paste the public key into the service account configuration in Strata Cloud Manager. +4. Strata Cloud Manager issues a **Client ID** for the service account. +5. You provide this Client ID to the Code Sign Client. +6. The client authenticates using the Client ID and the locally stored private key. + +After these steps, the Code Sign Client is authenticated as the service account. + +## Authenticate the service account + +The detailed configuration steps are provided in the main documentation, as they require UI interaction. See [Using a service account](https://docs.cyberark.com/mis-saas/CSH_csm_service_account/) for complete setup and authentication instructions. + +Once the UI configuration is finished, the Code Sign Client can authenticate and begin syncing Signing Keys. + +## What's next + +After authenticating using a service account, you can: + +- List available Signing Keys with `pkcs11config list` +- [Perform a test signing](/scm/api/config/mim/code-sign-manager/code-sign-client-test-signing) +- [Integrate with signing applications](/scm/api/config/mim/code-sign-manager) diff --git a/products/scm/api/config/mim/code-sign-manager/cli-reference.md b/products/scm/api/config/mim/code-sign-manager/cli-reference.md new file mode 100644 index 000000000..91a0fd8f0 --- /dev/null +++ b/products/scm/api/config/mim/code-sign-manager/cli-reference.md @@ -0,0 +1,301 @@ +--- +id: code-sign-client-cli-reference +title: "Code Sign Client CLI reference" +sidebar_label: "Code Sign Client CLI reference" +keywords: + - Machine Identity Management + - Code Sign Manager +--- + +## Synopsis + +For setting up the PKCS11 client (supported on all platforms): + +``` +pkcs11config [command] [--options] +``` + +For setting up the CSP/KSP client on Windows: + +``` +cspconfig [command] [--options] +``` + +## Configuration commands + +| Command | Description| +| --- | --- | +| `login` | Authenticates to a NGTS server. | +| `checklogin` | Checks the current authentication status. | +| `logout` | Revokes a grant. | +| `trust` | Manages trust for the NGTS server. | +| `seturls` | Detects or sets URLs. | +| `option` | Manages general configuration. | +| `proxy` | Sets HTTP proxy options. | +| `reset` | Resets the client configuration. | +| `update` | Checks for and installs software updates. | + +## Signing and verification commands + +| Command | Description| +| --- | --- | +| `list` | Lists all objects available to the user. | +| `sign` | Creates a signature for a file. | +| `verify` | Verifies a file signature. | + +## Common commands + +| Command | Description| +| --- | --- | +| `getcertificate` | Retrieves a certificate. | +| `getpublickey` | Retrieves the public key of a certificate. | +| `trace` | Manages trace settings for troubleshooting. | +| `health` | Checks client configuration health. No additional options. | +| `version` | Displays the version number and build timestamp. No additional options. | +| `help` | Displays general usage information. To get specific command help, run `pkcs11config [command] -h`. | + +## Command options + +### `login` options + +Authenticates to NGTS. + +If previously authenticated, then the existing authentication values will be verified and refreshed if needed, ignoring any other provided credentials, unless `--force` is used. + +If URL arguments are specified, the given URLs will be configured and used to authenticate. + +Running `login` without any options will invoke interactive mode. + +**Service account credential options:** + +| Option | Description| +| --- | --- | +| `--clientid=` | The UUID of the service account. | +| `--keyfile=` | Path to a file that contains the private key in PEM format. Used when authenticating a service account using **Auto-generate a keypair and download the private key**. | +| `--generate` | Generates a key pair for the service account. Used when authenticating a service account using **Generate your own keypair and upload the public key**. | + +**URL options:** + +| Option | Description| +| --- | --- | +| `--hostname=` | API endpoint URL for your region. This option detects and automatically sets the URLs for `authurl`, `hsmurl`, and `updateurl`. For a list of regional endpoint URLs, see [API Endpoints](/scm/api/config/mim/tls-protect-cloud/control-plane-api-endpoints). | +| `--authurl=` | Authentication server URL. This option is set automatically when using `--hostname`. | +| `--hsmurl=` | VedHsm backend URL. This option is set automatically when using `--hostname`. | +| `--updateurl=` | Update server URL. This option is set automatically when using `--hostname`. | + +**Proxy options:** + +| Option | Description| +| --- | --- | +| `--proxymode=` | Enables or disables using a proxy server for communication (options: `auto`, `disable`, `url`). | +| `--proxyurl=` | URL of the proxy server to use (implies `--proxymode:url`). | +| `--noproxy=` | A list of hostnames that should not use the proxy. | +| `--show` | Shows current proxy settings. | + +**Advanced options:** + +| Option | Description| +| --- | --- | +| `--force` | Forces getting a new grant; never refreshes. | + +--- + +### `checklogin` options + +Verifies the currently stored authentication details with the NGTS server and displays details. + +Return code `0` indicates a grant has been configured. + +Return code `1` indicates a missing or expired grant. + +| Option | Description| +| --- | --- | +| `--days=` | Authentication is treated as *invalid* if it will expire within `` days. This option is valid only for service account authentication. | + +--- + +### `logout` options + +Logs the user or service account out. + +| Option | Description| +| --- | --- | +| `--clear` | Completely removes any stored configuration after logging out. | +| `--force` | Forces logging out without confirmation. | + +--- + +### `trust` options + +Manages the certificate trust store. Trust is required to communicate with the NGTS server. + +| Option | Description| +| --- | --- | +| `--check` | Checks if the configured NGTS server is trusted. | +| `--delete=` | Removes trust for any certificate with a subject containing ``. | +| `--filename=` | PEM certificate file to import certificates from. | +| `--force` | Forces import without confirmation. | +| `--hostname=` | API endpoint URL for your region. This option detects and automatically sets the URLs for `authurl`, `hsmurl`, and `updateurl`. For a list of regional endpoint URLs, see [API Endpoints](/scm/api/config/mim/tls-protect-cloud/control-plane-api-endpoints). | +| `--show` | Shows existing certificates in the trust store. | + +--- + +### `seturls` options + +Detects or sets the URLs that should be used for authentication, signing, and client updates. These same options are available from the `login` command. + +| Option | Description| +| --- | --- | +| `--hostname=` | API endpoint URL for your region. This option detects and automatically sets the URLs for `authurl`, `hsmurl`, and `updateurl`. For a list of regional endpoint URLs, see [API Endpoints](/scm/api/config/mim/tls-protect-cloud/control-plane-api-endpoints). | +| `--authurl=` | Authentication server URL. This option is set automatically when using `--hostname`. | +| `--hsmurl=` | VedHsm backend URL. This option is set automatically when using `--hostname`. | +| `--updateurl=` | Update server URL. This option is set automatically when using `--hostname`. | + +--- + +### `option` options + +Manages and displays configuration options. + +| Option | Description| +| --- | --- | +| `--clear=` | Clears the value for ``. | +| `--show` | Displays the value for `` or all if no `--name` specified. | +| `--name=` | Name to set, show, or clear. | +| `--value=` | Value to set. | + +--- + +### `proxy` options + +Configures proxy settings to use when communicating with backend APIs. These same options are available from the `login` command. + +| Option | Description| +| --- | --- | +| `--proxymode=` | Enables or disables using a proxy server for communication (options: `auto`, `disable`, `url`). | +| `--proxyurl=` | URL of the proxy server to use (implies `--proxymode:url`). | +| `--noproxy=` | A list of hostnames that should not use the proxy. | +| `--show` | Shows current proxy settings. | + +--- + +### `reset` options + +Resets the client configuration. + +| Option | Description| +| --- | --- | +| `--all` | Resets all configuration. | +| `--current` | Resets only the current configuration (default). | +| `--preserve` | Preserves configured URLs. | + +--- + +### `update` options + +Checks for and displays available client software updates. + +| Option | Description| +| --- | --- | +| `--latest` | Downloads and installs the latest available version unless it is already installed. | +| `--architecture=` | Overrides the detected architecture (options: `x86_64`, `x86_32`, `arm64`). | +| `--type=` | Overrides the detected package type (options: `msi`, `rpm`, `deb`, `dmg`). | +| `--out=` | Stores the package in the specified output directory and does not install it. | +| `--updateurl=` | Sets the client update server URL. | + +--- + +### `list` options + +Displays a list of all available objects. Defaults to listing certificates and public keys from all available environments. + +Use `list` to find object labels. + +| Option | Description| +| --- | --- | +| `--env=` | Shows only environments of the specified types (options: `all`, `certificate`, `keypair`). | +| `--type=` | Shows only objects of the specified types (options: `all`, `private`, `public`, `certificate`). | +| `--sort=` | Sorts by the specified column (options: `label`, `environment`, `object`, `keytype`, `detail`, `context`, `keyid`, `handle`). | +| `--grouped` | Groups related objects. | +| `--table` | Outputs in table format. | +| `--number` | Displays a number for each item when used with `--table`. | +| `--reverse` | Reverses the sort order. | +| `--force` | Does not wait and reload if objects are pending creation. | + +--- + +### `sign` options + +Creates a signature for a file using the NGTS server directly. + +> This command hashes the specified file, signs the hash, and stores the raw resulting signature. The format of the signature is intended to test key access only and is not compatible with most other tools. + +| Option | Description| +| --- | --- | +| `--filename=` | File to sign. | +| `--output=` | Filename to store the signature in. | +| `--label=