Authentication

Learn how to set up API authentication for FortiOS devices.

Environment Variables (Best Practice)

Never hardcode tokens in your code. Use environment variables instead:

Using python-dotenv

  1. Install python-dotenv:

    pip install python-dotenv

  2. Create a .env file:

    FORTIGATE_HOST=192.168.1.99
FORTIGATE_TOKEN=your-actual-api-token-here
FORTIGATE_VERIFY_SSL=False

  3. Add .env to your .gitignore:

    echo ".env" >> .gitignore

  4. Use in your code:

    import os
from dotenv import load_dotenv
from hfortix import FortiOS

# Load environment variables
load_dotenv()

# Initialize client from environment
fgt = FortiOS(
    host=os.getenv('FORTIGATE_HOST'),
    token=os.getenv('FORTIGATE_TOKEN'),
    verify=os.getenv('FORTIGATE_VERIFY_SSL', 'True').lower() == 'true'
)

Using OS Environment Variables

# Set environment variables
export FORTIGATE_HOST=192.168.1.99
export FORTIGATE_TOKEN=your-api-token
export FORTIGATE_VERIFY_SSL=false

# Run your script
python your_script.py

import os
from hfortix import FortiOS

fgt = FortiOS(
    host=os.getenv('FORTIGATE_HOST'),
    token=os.getenv('FORTIGATE_TOKEN'),
    verify=os.getenv('FORTIGATE_VERIFY_SSL', 'true').lower() == 'true'
)

Username/Password Authentication (Legacy)

Warning

Username/password authentication is deprecated in FortiOS 7.6.x and later. Use API tokens instead for better security and compatibility.

For FortiOS ≤7.4.x only:

from hfortix import FortiOS

fgt = FortiOS(
    host='192.168.1.99',
    username='admin',
    password='your-password',
    verify=False
)

SSL Certificate Verification

Production Environments

Always use verify=True in production with valid SSL certificates:

fgt = FortiOS(
    host='fortigate.company.com',
    token='your-api-token',
    verify=True  # Verify SSL certificates
)

Custom Certificate Authority

If using a custom CA:

fgt = FortiOS(
    host='fortigate.company.com',
    token='your-api-token',
    verify='/path/to/ca-bundle.crt'  # Path to CA certificate
)

Development/Testing with Self-Signed Certificates

Only use verify=False in development/testing environments:

import urllib3

# Suppress SSL warnings (optional)
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

fgt = FortiOS(
    host='192.168.1.99',
    token='your-api-token',
    verify=False  # Disable SSL verification
)

Danger

Never use verify=False in production! This disables SSL certificate validation and makes your connection vulnerable to man-in-the-middle attacks.

Administrator Profiles

When creating API users, select an appropriate administrator profile:

  • super_admin: Full access to all features (use with caution)

  • prof_admin: Read/write access to most features

  • Read-Only: View-only access (safe for monitoring scripts)

  • Custom Profile: Create a custom profile with specific permissions

Example: Creating a Read-Only API User

For monitoring scripts that only need read access:

  1. Create a custom administrator profile:

    • Navigate to System > Admin Profiles

    • Create a new profile with read-only permissions

  2. Create an API user with this profile

  3. Use the token for monitoring operations

from hfortix import FortiOS

# Read-only monitoring client
fgt_monitor = FortiOS(
    host='192.168.1.99',
    token='read-only-api-token',
    verify=True
)

# Safe operations - will succeed
status = fgt_monitor.api.monitor.system.status.get()
policies = fgt_monitor.api.cmdb.firewall.policy.get()

# Write operations - will fail with permission error
# fgt_monitor.api.cmdb.firewall.address.post(...)  # PermissionError

Trusted Hosts (Security Best Practice)

Restrict API access to specific IP addresses:

  1. When creating the API user, set Trusted Hosts

  2. Add your application server’s IP address

  3. Click the + to add multiple trusted hosts if needed

Example trusted hosts:

  • 192.168.1.100/32 - Single IP address

  • 10.0.0.0/24 - Entire subnet

  • 0.0.0.0/0 - Any IP (not recommended for production)

Testing Your Authentication

Verify your credentials work:

from hfortix import FortiOS, APIError

try:
    fgt = FortiOS(
        host='192.168.1.99',
        token='your-api-token',
        verify=False
    )
    
    # Test with a simple API call (use dict access - Monitor fields may not have type hints)
    status = fgt.api.monitor.system.status.get()
    print(f"✅ Connected to {status['hostname']}")
    print(f"   Model: {status['model']}")
    print(f"   Model Number: {status['model_number']}")
    
except APIError as e:
    print(f"❌ Authentication failed: {e.message}")
except Exception as e:
    print(f"❌ Connection error: {e}")

Next Steps