364 lines
10 KiB
Markdown
364 lines
10 KiB
Markdown
# API Key Integration Guide for PowerShell Scripts
|
|
|
|
## Overview
|
|
This guide explains how to configure API key authentication in the PowerShell asset collection scripts when deploying to production environments.
|
|
|
|
---
|
|
|
|
## Configuration Methods
|
|
|
|
### Method 1: Environment Variable (Recommended)
|
|
Set both the dashboard URL and API key as Windows environment variables:
|
|
|
|
```powershell
|
|
# Set environment variables (run as Administrator)
|
|
[Environment]::SetEnvironmentVariable("ASSET_DASHBOARD_URL", "http://10.48.130.158/dashboard-v2/api.php", "User")
|
|
[Environment]::SetEnvironmentVariable("ASSET_API_KEY", "your-secret-api-key-here", "User")
|
|
```
|
|
|
|
### Method 2: Configuration File
|
|
Create a `dashboard-config.json` file in the script directory:
|
|
|
|
```json
|
|
{
|
|
"DashboardURL": "http://10.48.130.158/dashboard-v2/api.php",
|
|
"ApiKey": "your-secret-api-key-here",
|
|
"ProxyURL": "http://10.48.130.158/vendor-api-proxy.php"
|
|
}
|
|
```
|
|
|
|
### Method 3: Command Line Parameter
|
|
Pass the API key when running the script:
|
|
|
|
```powershell
|
|
.\Update-PC-CompleteAsset.ps1 -DashboardURL "http://10.48.130.158/dashboard-v2/api.php" -ApiKey "your-secret-api-key-here"
|
|
```
|
|
|
|
---
|
|
|
|
## PowerShell Script Modifications
|
|
|
|
### 1. Add API Key Parameter
|
|
Add to the param block in `Update-PC-CompleteAsset.ps1`:
|
|
|
|
```powershell
|
|
param(
|
|
[Parameter(Mandatory=$false)]
|
|
[string]$DashboardURL,
|
|
|
|
[Parameter(Mandatory=$false)]
|
|
[string]$ProxyURL,
|
|
|
|
[Parameter(Mandatory=$false)]
|
|
[string]$ApiKey, # New parameter for API key
|
|
|
|
[Parameter(Mandatory=$false)]
|
|
[switch]$SkipWarranty = $false,
|
|
|
|
[Parameter(Mandatory=$false)]
|
|
[switch]$TestConnections = $false
|
|
)
|
|
```
|
|
|
|
### 2. Create Get-ApiKey Function
|
|
Add this function after the Get-DashboardURL function:
|
|
|
|
```powershell
|
|
function Get-ApiKey {
|
|
param([string]$ProvidedKey)
|
|
|
|
# Priority 1: Command line parameter
|
|
if (-not [string]::IsNullOrEmpty($ProvidedKey)) {
|
|
Write-Host " Using provided API key" -ForegroundColor Gray
|
|
return $ProvidedKey
|
|
}
|
|
|
|
# Priority 2: Environment variable
|
|
$envKey = [Environment]::GetEnvironmentVariable("ASSET_API_KEY", "User")
|
|
if (-not [string]::IsNullOrEmpty($envKey)) {
|
|
Write-Host " Using API key from environment variable" -ForegroundColor Gray
|
|
return $envKey
|
|
}
|
|
|
|
# Priority 3: Config file
|
|
$configPath = "$PSScriptRoot\dashboard-config.json"
|
|
if (Test-Path $configPath) {
|
|
try {
|
|
$config = Get-Content $configPath | ConvertFrom-Json
|
|
if ($config.ApiKey) {
|
|
Write-Host " Using API key from config file" -ForegroundColor Gray
|
|
return $config.ApiKey
|
|
}
|
|
} catch {
|
|
Write-Warning "Failed to read config file: $_"
|
|
}
|
|
}
|
|
|
|
# No API key found (okay for development)
|
|
Write-Host " No API key configured (running without authentication)" -ForegroundColor Yellow
|
|
return $null
|
|
}
|
|
```
|
|
|
|
### 3. Update API Calls to Include Authentication
|
|
|
|
#### For GET Requests:
|
|
```powershell
|
|
# Original code
|
|
$response = Invoke-RestMethod -Uri "$DashboardURL?action=getDashboardData" -Method Get -TimeoutSec 10
|
|
|
|
# Updated with API key
|
|
$apiKey = Get-ApiKey -ProvidedKey $ApiKey
|
|
$uri = "$DashboardURL?action=getDashboardData"
|
|
if ($apiKey) {
|
|
$uri += "&api_key=$apiKey"
|
|
}
|
|
$response = Invoke-RestMethod -Uri $uri -Method Get -TimeoutSec 10
|
|
```
|
|
|
|
#### For POST Requests (Preferred Method):
|
|
```powershell
|
|
# Get API key
|
|
$apiKey = Get-ApiKey -ProvidedKey $ApiKey
|
|
|
|
# Build headers
|
|
$headers = @{
|
|
'Content-Type' = 'application/x-www-form-urlencoded'
|
|
}
|
|
|
|
# Add Authorization header if API key exists
|
|
if ($apiKey) {
|
|
$headers['Authorization'] = "Bearer $apiKey"
|
|
}
|
|
|
|
# Make the request
|
|
$response = Invoke-RestMethod -Uri $DashboardURL -Method Post -Body $postData -Headers $headers -TimeoutSec 30
|
|
```
|
|
|
|
### 4. Update Send-ToDatabase Function
|
|
Modify the Send-ToDatabase function to include authentication:
|
|
|
|
```powershell
|
|
function Send-ToDatabase {
|
|
param(
|
|
[hashtable]$Data,
|
|
[string]$DashboardURL,
|
|
[string]$ApiKey # Add ApiKey parameter
|
|
)
|
|
|
|
try {
|
|
Write-Host "`n Sending complete asset data to database..." -ForegroundColor Cyan
|
|
|
|
# Create form data
|
|
$postData = @{
|
|
action = 'updatePCComplete'
|
|
}
|
|
|
|
# Add all data fields
|
|
foreach ($key in $Data.Keys) {
|
|
if ($null -ne $Data[$key]) {
|
|
$postData[$key] = $Data[$key]
|
|
}
|
|
}
|
|
|
|
# Build headers
|
|
$headers = @{
|
|
'Content-Type' = 'application/x-www-form-urlencoded'
|
|
}
|
|
|
|
# Add API key authentication if provided
|
|
if ($ApiKey) {
|
|
$headers['Authorization'] = "Bearer $ApiKey"
|
|
Write-Host " Using API key authentication" -ForegroundColor Gray
|
|
}
|
|
|
|
$response = Invoke-RestMethod -Uri $DashboardURL -Method Post -Body $postData -Headers $headers -TimeoutSec 30
|
|
|
|
if ($response.success) {
|
|
Write-Host " [OK] Complete asset data stored in database!" -ForegroundColor Green
|
|
if ($response.message) {
|
|
Write-Host " $($response.message)" -ForegroundColor Gray
|
|
}
|
|
return $true
|
|
} else {
|
|
Write-Warning "Database update failed: $($response.message)"
|
|
return $false
|
|
}
|
|
} catch {
|
|
Write-Error "Failed to send data to database: $_"
|
|
return $false
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Deployment Batch File Updates
|
|
|
|
Update `Deploy-To-Multiple-PCs-Enhanced.bat` to include API key:
|
|
|
|
```batch
|
|
REM Configuration section
|
|
set SOURCE_DIR=S:\DT\adata\script
|
|
set TARGET_DIR=C:\Temp\AssetCollection
|
|
set API_KEY=your-secret-api-key-here
|
|
|
|
REM Create config file on target PC
|
|
echo Creating configuration file...
|
|
(
|
|
echo {
|
|
echo "DashboardURL": "http://10.48.130.158/dashboard-v2/api.php",
|
|
echo "ApiKey": "%API_KEY%",
|
|
echo "ProxyURL": "http://10.48.130.158/vendor-api-proxy.php"
|
|
echo }
|
|
) > "\\!COMPUTER!\C$\Temp\AssetCollection\dashboard-config.json"
|
|
```
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
### 1. Never Hardcode API Keys
|
|
- Don't put API keys directly in scripts
|
|
- Use environment variables or config files
|
|
- Add `dashboard-config.json` to `.gitignore`
|
|
|
|
### 2. Secure Storage on Client PCs
|
|
```powershell
|
|
# Set restrictive permissions on config file
|
|
$configPath = "C:\Temp\AssetCollection\dashboard-config.json"
|
|
$acl = Get-Acl $configPath
|
|
$acl.SetAccessRuleProtection($true, $false)
|
|
$adminRule = New-Object System.Security.AccessControl.FileSystemAccessRule("Administrators", "FullControl", "Allow")
|
|
$systemRule = New-Object System.Security.AccessControl.FileSystemAccessRule("SYSTEM", "FullControl", "Allow")
|
|
$acl.SetAccessRule($adminRule)
|
|
$acl.SetAccessRule($systemRule)
|
|
Set-Acl $configPath $acl
|
|
```
|
|
|
|
### 3. Use HTTPS in Production
|
|
When API key is configured, always use HTTPS:
|
|
```powershell
|
|
$DashboardURL = "https://your-server/dashboard-v2/api.php"
|
|
```
|
|
|
|
---
|
|
|
|
## Testing API Key Authentication
|
|
|
|
### Test Script
|
|
Create `Test-ApiAuth.ps1`:
|
|
|
|
```powershell
|
|
param(
|
|
[string]$DashboardURL = "http://10.48.130.158/dashboard-v2/api.php",
|
|
[string]$ApiKey
|
|
)
|
|
|
|
Write-Host "Testing API Authentication..." -ForegroundColor Cyan
|
|
|
|
# Test without API key
|
|
Write-Host "`nTest 1: Without API key"
|
|
try {
|
|
$response = Invoke-RestMethod -Uri "$DashboardURL?action=health" -Method Get
|
|
Write-Host " Result: Success (no auth required)" -ForegroundColor Green
|
|
} catch {
|
|
Write-Host " Result: Failed - $($_.Exception.Message)" -ForegroundColor Red
|
|
}
|
|
|
|
# Test with API key in header
|
|
if ($ApiKey) {
|
|
Write-Host "`nTest 2: With API key (Bearer token)"
|
|
$headers = @{
|
|
'Authorization' = "Bearer $ApiKey"
|
|
}
|
|
try {
|
|
$response = Invoke-RestMethod -Uri "$DashboardURL?action=health" -Method Get -Headers $headers
|
|
Write-Host " Result: Success (authenticated)" -ForegroundColor Green
|
|
} catch {
|
|
Write-Host " Result: Failed - $($_.Exception.Message)" -ForegroundColor Red
|
|
}
|
|
}
|
|
|
|
# Test with API key in query
|
|
if ($ApiKey) {
|
|
Write-Host "`nTest 3: With API key (query parameter)"
|
|
try {
|
|
$response = Invoke-RestMethod -Uri "$DashboardURL?action=health&api_key=$ApiKey" -Method Get
|
|
Write-Host " Result: Success (authenticated via query)" -ForegroundColor Green
|
|
} catch {
|
|
Write-Host " Result: Failed - $($_.Exception.Message)" -ForegroundColor Red
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Environment-Specific Configuration
|
|
|
|
### Development Environment
|
|
```json
|
|
{
|
|
"DashboardURL": "http://localhost/dashboard-v2/api.php",
|
|
"ApiKey": "",
|
|
"ProxyURL": "http://localhost/vendor-api-proxy.php"
|
|
}
|
|
```
|
|
|
|
### Production Environment
|
|
```json
|
|
{
|
|
"DashboardURL": "https://asset-server.company.com/api.php",
|
|
"ApiKey": "sk_live_a7b9c2d8e5f4g6h3i9j0k1l2m3n4o5p6q7r8s9t0",
|
|
"ProxyURL": "https://asset-server.company.com/vendor-api-proxy.php"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **401 Unauthorized Error**
|
|
- Verify API key is correct
|
|
- Check if APP_ENV=production in .env
|
|
- Ensure API_KEY is set in .env file
|
|
|
|
2. **API Key Not Being Sent**
|
|
- Check if headers are properly constructed
|
|
- Verify Authorization header format: `Bearer YOUR_KEY`
|
|
- Try query parameter method as fallback
|
|
|
|
3. **Script Works Locally but Not on Remote PCs**
|
|
- Ensure config file is deployed to target PCs
|
|
- Check environment variables on target machines
|
|
- Verify network connectivity to API server
|
|
|
|
### Debug Mode
|
|
Add verbose output to troubleshoot:
|
|
|
|
```powershell
|
|
# Enable verbose mode
|
|
$VerbosePreference = "Continue"
|
|
|
|
# Add debug output
|
|
Write-Verbose "API Key present: $($null -ne $ApiKey)"
|
|
Write-Verbose "Dashboard URL: $DashboardURL"
|
|
Write-Verbose "Headers: $($headers | ConvertTo-Json)"
|
|
```
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
When deploying to production:
|
|
|
|
1. **Generate secure API key**: `openssl rand -hex 32`
|
|
2. **Set in .env file**: `API_KEY=your-generated-key`
|
|
3. **Set environment to production**: `APP_ENV=production`
|
|
4. **Configure PowerShell scripts** with one of the three methods above
|
|
5. **Test authentication** before mass deployment
|
|
6. **Use HTTPS** for all production API calls
|
|
|
|
The API key provides an additional layer of security for your asset management system, ensuring only authorized scripts and users can update the database. |