Guide: Authentication Methods

Authentication Methods

This guide covers authentication configuration for the F5 Distributed Cloud Terraform provider.

Quick Reference

Method	Complexity	Best For	Security
API Token	Simplest	Development, quick testing	Bearer token over TLS
P12 Certificate	Moderate	Production, CI/CD	Mutual TLS (mTLS)
PEM Certificate	Advanced	When tooling requires PEM format	Derived from P12, mTLS

Prerequisites

• F5 Distributed Cloud Account - Sign up at https://www.f5.com/cloud/products/distributed-cloud-console
• Terraform >= 1.8 - Download from https://www.terraform.io/downloads
• Console Access - Ability to create credentials in the F5XC Console

Creating Credentials in F5 Distributed Cloud

Personal Credentials

Personal credentials are tied to your user account and ideal for development.

Creating an API Token

1. Open the F5 Distributed Cloud Console
2. Navigate to Administration → Personal Management → Credentials
3. Click + Add Credentials
4. Enter a name (e.g., “terraform-dev-token”)
5. Select API Token from the dropdown
6. Choose an expiry date
7. Click Generate, then Copy the token value

!> Warning: Copy and save your token immediately. You cannot retrieve it after closing this dialog.

Creating a P12 Certificate

1. Navigate to Administration → Personal Management → Credentials
2. Click + Add Credentials
3. Enter a name (e.g., “terraform-dev-cert”)
4. Select API Certificate from the dropdown
5. Enter and confirm a password
6. Select an expiry date
7. Click Download to get the .p12 file

-> Tip: Store the P12 file securely and never commit it to version control.

Service Credentials (IAM)

Service credentials are managed through IAM and recommended for production. They can be scoped to specific roles and namespaces.

Creating a Service API Token

1. Navigate to Administration → IAM → Service Credentials
2. Click + Add Service Credentials
3. Enter a name (e.g., “terraform-cicd-token”)
4. Select API Token from the dropdown
5. Optionally assign roles and namespaces to limit scope
6. Choose an expiry date
7. Click Generate, then Copy the token value

Creating a Service P12 Certificate

1. Navigate to Administration → IAM → Service Credentials
2. Click + Add Service Credentials
3. Enter a name
4. Select API Certificate from the dropdown
5. Optionally assign roles and namespaces
6. Enter and confirm a password
7. Select an expiry date
8. Click Download to get the .p12 file

Provider Configuration

Method 1: API Token Authentication (Simplest)

API tokens provide bearer token authentication over TLS. This is the quickest way to get started.

Using Environment Variables:

export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

Using Provider Configuration:

provider "f5xc" {
  api_url   = var.f5xc_api_url
  api_token = var.f5xc_api_token
}

Method 2: P12 Certificate Authentication (Recommended for Production)

P12 certificates provide mutual TLS (mTLS) authentication, where both client and server verify each other’s identity.

Using Environment Variables:

export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
export F5XC_P12_FILE="/path/to/your-credentials.p12"
export F5XC_P12_PASSWORD="your-p12-password"  # pragma: allowlist secret

Using Provider Configuration:

provider "f5xc" {
  api_url      = var.f5xc_api_url
  api_p12_file = var.f5xc_api_p12_file
  p12_password = var.f5xc_p12_password
}

Method 3: PEM Certificate Authentication (Derived from P12)

PEM authentication uses separate certificate and private key files. Since F5XC only provides P12 certificates, you must extract PEM files using OpenSSL.

When to use this method: Only when your tooling specifically requires PEM format instead of P12.

Step 1: Extract PEM files from P12:

# Create a directory for certificates
mkdir -p certs

# Extract the certificate
openssl pkcs12 -in ~/your-tenant.console.ves.volterra.io.api-creds.p12 \
  -nodes -nokeys -out certs/f5xc.cert
# Enter Import Password: <your p12 password>

# Extract the private key
openssl pkcs12 -in ~/your-tenant.console.ves.volterra.io.api-creds.p12 \
  -nodes -nocerts -out certs/f5xc.key
# Enter Import Password: <your p12 password>

Step 2: Configure the provider:

Using Environment Variables:

export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
export F5XC_CERT="/path/to/certs/f5xc.cert"
export F5XC_KEY="/path/to/certs/f5xc.key"

Using Provider Configuration:

provider "f5xc" {
  api_url  = var.f5xc_api_url
  api_cert = var.f5xc_api_cert
  api_key  = var.f5xc_api_key
}

~> Note: For server certificate verification, specify a CA certificate using F5XC_CACERT environment variable or api_ca_cert provider attribute.

Environment Variable Reference

Variable	Description	Required
F5XC_API_URL	F5XC tenant API URL	Yes
F5XC_API_TOKEN	API token for bearer authentication	One of: token, P12, or PEM
F5XC_P12_FILE	Path to P12 certificate file	With F5XC_P12_PASSWORD
F5XC_P12_PASSWORD	Password for P12 file	With F5XC_P12_FILE
F5XC_CERT	Path to PEM certificate file	With F5XC_KEY
F5XC_KEY	Path to PEM private key file	With F5XC_CERT
F5XC_CACERT	Path to CA certificate for server verification	No

Adding to Shell Profile:

# Add to ~/.bashrc or ~/.zshrc
export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

Then reload: source ~/.zshrc or source ~/.bashrc

Authentication Priority

When multiple methods are configured, the provider uses this priority:

1. P12 Certificate - If api_p12_file is set (requires p12_password)
2. PEM Certificate - If both api_cert and api_key are set
3. API Token - If api_token is set
4. Error - If none are provided

CI/CD Integration

GitHub Actions with API Token

name: Terraform Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  terraform:
    runs-on: Ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.8.0"

      - name: Terraform Init
        run: terraform init

      - name: Terraform Plan
        env:
          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
          F5XC_API_TOKEN: ${{ secrets.F5XC_API_TOKEN }}
        run: terraform plan -out=tfplan

      - name: Terraform Apply
        if: GitHub.ref == 'refs/heads/main' && GitHub.event_name == 'push'
        env:
          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
          F5XC_API_TOKEN: ${{ secrets.F5XC_API_TOKEN }}
        run: terraform apply -auto-approve tfplan

GitHub Secrets to configure:

Secret Name	Value
F5XC_API_URL	https://your-tenant.console.ves.volterra.io
F5XC_API_TOKEN	Your API token value

GitHub Actions with P12 Certificate

For production deployments requiring mTLS:

name: Terraform Deploy with P12

on:
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: Ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.8.0"

      - name: Setup P12 Certificate
        run: |
          echo "${{ secrets.F5XC_P12_BASE64 }}" | base64 -d > /tmp/f5xc-credentials.p12
          chmod 600 /tmp/f5xc-credentials.p12

      - name: Terraform Init
        run: terraform init

      - name: Terraform Plan
        env:
          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
          F5XC_P12_FILE: /tmp/f5xc-credentials.p12
          F5XC_P12_PASSWORD: ${{ secrets.F5XC_P12_PASSWORD }}
        run: terraform plan -out=tfplan

      - name: Terraform Apply
        env:
          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
          F5XC_P12_FILE: /tmp/f5xc-credentials.p12
          F5XC_P12_PASSWORD: ${{ secrets.F5XC_P12_PASSWORD }}
        run: terraform apply -auto-approve tfplan

      - name: Cleanup
        if: always()
        run: rm -f /tmp/f5xc-credentials.p12

Encoding P12 for GitHub Secrets:

# On macOS
base64 -i your-credentials.p12 | pbcopy

# On Linux
base64 -w 0 your-credentials.p12

GitHub Secrets to configure:

Secret Name	Value
F5XC_API_URL	https://your-tenant.console.ves.volterra.io
F5XC_P12_BASE64	base64-encoded P12 file contents
F5XC_P12_PASSWORD	Password for the P12 file

Security Best Practices

• Never commit credentials to version control. Add *.tfvars, *.p12, and *.pem to .gitignore
• Use environment variables for sensitive values in local development
• Use GitHub Secrets or equivalent for CI/CD pipelines
• Limit credential scope using Service Credentials with specific roles and namespaces

Choosing the Right Method

Use Case	Recommended Method	Reason
Local development	API Token	Simplest setup
CI/CD pipelines	P12 Certificate	mTLS security
Production automation	Service Credentials	Role-based access control

Troubleshooting

Authentication Failed (401 Unauthorized)

1. Verify API URL does NOT include /api suffix (e.g., https://tenant.console.ves.volterra.io)
2. Check token hasn’t expired
3. Verify token copied correctly (no whitespace)
4. Ensure environment variables are exported:

echo $F5XC_API_URL
echo $F5XC_API_TOKEN

Certificate Verification Failed

1. Verify P12 password is correct
2. Check file path is absolute or correctly relative
3. Test P12 file:

openssl pkcs12 -in your-credentials.p12 -nokeys -info

Permission Denied (403 Forbidden)

1. Verify credential has required permissions
2. For Service Credentials, check role and namespace assignments
3. Some operations require specific system roles

Environment Variables Not Working

1. Ensure variables are exported:

export F5XC_API_TOKEN="token"  # Correct
F5XC_API_TOKEN="token"         # Won't work

1. Verify spelling is exact (case-sensitive)
2. Check for hidden characters in values

Revoking Credentials

1. Navigate to Administration → Personal Management → Credentials (or IAM → Service Credentials)
2. Find the credential
3. Click Actions (three dots) → Force Expiry

Next Steps

• HTTP Load Balancer Guide - Deploy your first load balancer
• Blindfold Functions Guide - Secure secret management

Support

• Provider Documentation
• F5 Distributed Cloud Docs
• F5 Credentials Guide
• GitHub Issues