terraform-provider-edge-connect/examples/authentication/README.md

Authentication Examples

This directory contains examples demonstrating the different authentication methods supported by the Edge Connect Terraform provider.

Configuration Methods

The provider supports configuration via:

1. Explicit Configuration - Setting values directly in your Terraform files
2. Environment Variables - Using environment variables (recommended for CI/CD and production)
3. Hybrid Approach - Mixing both methods (explicit config takes precedence)

Authentication Methods

The provider supports two mutually exclusive authentication methods:

1. Token-based Authentication

Token authentication uses a pre-generated API token for authentication.

File: token-auth.tf

Advantages:

• More secure (tokens can be scoped and rotated)
• Better for CI/CD pipelines
• Recommended for production use

Usage:

provider "edge-connect" {
  endpoint = "https://api.edge-connect.example.com"
  token    = var.edge_connect_token
}

Environment Variables: You can set credentials directly via provider-specific environment variables:

export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_TOKEN="your-token-here"
terraform apply

Alternatively, use Terraform variables:

export TF_VAR_edge_connect_token="your-token-here"
terraform apply

2. Username/Password Authentication

Username/password authentication uses standard user credentials.

File: username-password-auth.tf

Advantages:

• Simpler for development and testing
• No token generation required
• Familiar authentication method

Usage:

provider "edge-connect" {
  endpoint = "https://api.edge-connect.example.com"
  username = var.edge_connect_username
  password = var.edge_connect_password
}

Environment Variables: You can set credentials directly via provider-specific environment variables:

export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_USERNAME="your-username"
export EDGE_CONNECT_PASSWORD="your-password"
terraform apply

Alternatively, use Terraform variables:

export TF_VAR_edge_connect_username="your-username"
export TF_VAR_edge_connect_password="your-password"
terraform apply

Environment Variables

The provider supports the following environment variables that can be used instead of explicit configuration:

Environment Variable	Description	Required
EDGE_CONNECT_ENDPOINT	API endpoint URL	Yes
EDGE_CONNECT_TOKEN	API token	Conditional*
EDGE_CONNECT_USERNAME	Username for authentication	Conditional*
EDGE_CONNECT_PASSWORD	Password for authentication	Conditional*

* Either EDGE_CONNECT_TOKEN OR both EDGE_CONNECT_USERNAME and EDGE_CONNECT_PASSWORD must be provided.

Using Environment Variables Only

File: env-vars.tf

You can configure the provider without any explicit configuration by using environment variables:

provider "edge-connect" {
  # Configuration will be read from environment variables
}

Token Authentication:

export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_TOKEN="your-token-here"
terraform init
terraform plan
terraform apply

Username/Password Authentication:

export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_USERNAME="your-username"
export EDGE_CONNECT_PASSWORD="your-password"
terraform init
terraform plan
terraform apply

Precedence Rules

When both explicit configuration and environment variables are provided:

1. Explicit configuration values take precedence
2. If a value is not explicitly configured, the provider checks environment variables
3. If neither is provided, validation errors occur

Example of precedence:

provider "edge-connect" {
  endpoint = "https://api.edge-connect.example.com"  # Explicit
  # token will be read from EDGE_CONNECT_TOKEN env var
}

Helper Scripts

See the example shell scripts in this directory:

• env-vars-token.sh - Set up token authentication via environment variables
• env-vars-userpass.sh - Set up username/password authentication via environment variables

Make them executable and source them:

chmod +x env-vars-token.sh
source ./env-vars-token.sh

Important Notes

1. Mutual Exclusivity: You must use EITHER token OR username/password, not both. The provider will return an error if both methods are provided.

2. Required Credentials:

   • For token auth: endpoint and token are required
   • For username/password auth: endpoint, username, and password are required

3. Security Best Practices:

   • Never commit credentials to version control
   • Prefer environment variables over hardcoded values in Terraform files
   • Use environment variables or secure secret management systems
   • Mark sensitive variables with sensitive = true
   • Use .gitignore to exclude terraform.tfvars files
   • Consider using tools like direnv for automatic environment variable management

Validation Rules

The provider validates authentication credentials with the following rules:

• At least one authentication method must be provided
• Both authentication methods cannot be used simultaneously
• For username/password auth, both username and password must be provided together

Error Messages

Missing Credentials

Error: Missing Authentication Credentials

The provider requires authentication credentials. Please provide either:
  - token: API token for authentication (via 'token' attribute or EDGE_CONNECT_TOKEN environment variable), or
  - username and password: Username and password for authentication (via 'username'/'password' attributes or EDGE_CONNECT_USERNAME/EDGE_CONNECT_PASSWORD environment variables)

Conflicting Methods

Error: Conflicting Authentication Methods

Both token and username/password authentication methods are provided.
Please use only one authentication method.

Incomplete Credentials

Error: Incomplete Username/Password Credentials

Both username and password must be provided together for username/password authentication.

Testing Examples

Using Explicit Configuration

To test token authentication:

cd examples/authentication
terraform init
terraform plan -var="edge_connect_token=your-token" -target=edge-connect_app.token_example

To test username/password authentication:

cd examples/authentication
terraform init
terraform plan \
  -var="edge_connect_username=your-username" \
  -var="edge_connect_password=your-password" \
  -target=edge-connect_app.userpass_example

Using Environment Variables

To test with environment variables (token auth):

cd examples/authentication
export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_TOKEN="your-token"
terraform init
terraform plan -target=edge-connect_app.env_example

To test with environment variables (username/password auth):

cd examples/authentication
export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_USERNAME="your-username"
export EDGE_CONNECT_PASSWORD="your-password"
terraform init
terraform plan -target=edge-connect_app.env_example

Recommendations

• Production Environments: Use token-based authentication with properly scoped and rotated tokens via environment variables
• Development Environments: Either method is acceptable, but token auth is still recommended. Use environment variables or .tfvars files
• CI/CD Pipelines: Use token-based authentication with secrets management (e.g., HashiCorp Vault, AWS Secrets Manager) passed as environment variables
• Local Development: Use environment variables with tools like direnv for automatic management
• Configuration Management: Prefer environment variables over hardcoded values for better security and flexibility