Skip to content

CLI Authentication

The VDC CLI supports two authentication methods to secure your access to VDC resources. Choose the method that best fits your environment and use case.

Authentication Methods Overview

Method Platform Support Best For Setup Complexity
Windows Authentication Windows only Interactive use on Windows machines None (automatic)
Token Authentication All platforms (Windows, Linux, macOS) Automation, CI/CD, cross-platform One-time setup

Windows Authentication

How It Works

Windows Authentication uses the credentials of the currently logged-in Windows user. If your user account has the necessary VDC permissions, commands work automatically without additional setup.

Usage

Simply run VDC CLI commands without the --token parameter:

# Commands work automatically on Windows with proper permissions
vdc ingredient get --project myproject --feed main --name myingredient
vdc download --project myproject --feed main --name myingredient

Limitations

  • Windows only - Does not work on Linux or macOS
  • Interactive sessions only - May not work in some automated scenarios
  • User-dependent - Tied to the logged-in Windows user account

When to Use

  • Local development on Windows machines
  • Interactive CLI usage
  • Quick testing and exploration

How It Works

Token authentication uses a generated security token that represents your VDC permissions. This token can be used across all supported operating systems and is ideal for automation.

Advantages

  • Cross-platform - Works on Windows, Linux, and macOS
  • Automation-friendly - Perfect for CI/CD pipelines and scripts
  • Portable - Same token works across different machines
  • Secure - Can be revoked and regenerated as needed

Setting Up Token Authentication

Step 1: Generate Token

Important: Token generation must be done on a Windows machine using your Intel account.

  1. Log in to a Windows machine with your Intel account
  2. Open Command Prompt or PowerShell
  3. Run the token creation command:
vdc token create
  1. The command outputs a long alphanumeric string - this is your authentication token
  2. Copy and store this token immediately in a secure location

Step 2: Secure Token Storage

Store the token in an environment variable for easy reuse:

Linux/macOS:

# Add to ~/.bashrc or ~/.zshrc
export VDC_TOKEN="your-generated-token-here"

# Use in commands
vdc ingredient get --project myproject --name myingredient --token $VDC_TOKEN

Windows (PowerShell):

# Set for current session
$env:VDC_TOKEN = "your-generated-token-here"

# Set permanently (optional)
[Environment]::SetEnvironmentVariable("VDC_TOKEN", "your-generated-token-here", "User")

# Use in commands
vdc ingredient get --project myproject --name myingredient --token $env:VDC_TOKEN

CI/CD Secrets

Store tokens as encrypted secrets in your CI/CD system:

GitHub Actions:

- name: Download VDC Release
  run: |
    vdc download --project myproject --name myingredient --token ${{ secrets.VDC_TOKEN }}

Azure DevOps:

- script: |
    vdc download --project myproject --name myingredient --token $(VDC_TOKEN)
  displayName: 'Download VDC Release'

Step 3: Using Tokens in Commands

Add the --token parameter to any VDC CLI command:

# Basic usage
vdc ingredient get --project myproject --name myingredient --token YOUR_TOKEN

# With environment variable
vdc download --project myproject --name myingredient --token $VDC_TOKEN

# In scripts
TOKEN="your-token-here"
vdc ingredient-release submit --project myproject --name myingredient --version 1.0.0 --token $TOKEN

Token Security Best Practices

DOs

  • Store tokens securely - Use environment variables, password managers, or CI/CD secrets
  • Limit token exposure - Don't include tokens in logs or error messages
  • Use environment variables - Avoid hardcoding tokens in scripts
  • Regenerate periodically - Create new tokens regularly for enhanced security
  • Different tokens for different purposes - Consider separate tokens for development vs. production

Don'ts

  • Never commit tokens to version control - Tokens in Git repositories are a security risk
  • Don't share tokens - Each user/system should have its own token
  • Avoid hardcoding - Don't put tokens directly in script files
  • Don't log tokens - Exclude tokens from log files and console output

Troubleshooting Authentication

Common Issues

"Authentication failed" or "Unauthorized"

Possible Causes:

  • Expired or invalid token
  • Token was revoked
  • Insufficient permissions for the requested resource

Solutions:

# Regenerate token on Windows machine
vdc token create

# Verify token format (should be long alphanumeric string)
echo $VDC_TOKEN

# Test with a simple command
vdc ingredient get --project myproject --name myingredient --token $VDC_TOKEN --verbose

"Token not found" or "No token provided"

Possible Causes:

  • Forgot to include --token parameter
  • Environment variable not set correctly
  • Token string has spaces or special characters

Solutions:

# Verify environment variable is set
echo $VDC_TOKEN

# Use token directly in command
vdc ingredient get --project myproject --name myingredient --token "your-token-here"

# Check for hidden characters
echo $VDC_TOKEN | cat -A

Windows Authentication Not Working

Possible Causes:

  • Not running on Windows machine
  • User account lacks VDC permissions
  • Network/domain authentication issues

Solutions:

  • Switch to token authentication
  • Verify user account has proper VDC project access
  • Contact VDC administrators for permission verification

Token Lifecycle Management

When to Regenerate Tokens

  • Security incidents - If token may have been compromised
  • Regular rotation - Periodic regeneration (quarterly/annually)
  • Team changes - When team members leave
  • Platform changes - When moving to new CI/CD systems

Regeneration Process

  1. Generate new token on Windows machine: vdc token create
  2. Update environment variables and CI/CD secrets
  3. Test new token with simple commands
  4. Update all automation scripts and configurations
  5. Revoke old token (if VDC supports token revocation)

Next Steps

Authentication Set Up Successfully?

Having Issues?