Authentication

Authentication

This guide covers authentication methods and API token management in PVE4J.

Table of Contents

• API Tokens
• Creating API Tokens
• Using API Tokens
• Token Security
• Password Authentication
• Ticket Authentication
• Common Authentication Patterns
• Troubleshooting Authentication

API Tokens

API tokens are the recommended authentication method for PVE4J. They provide:

• Secure, token-based authentication
• Fine-grained permission control
• Easy revocation
• No password exposure

Token Format

Proxmox API tokens follow this format:

USER@REALM!TOKENID=SECRET

Components:

• USER - Username (e.g., root, admin, automation)
• REALM - Authentication realm (e.g., pam, pve)
• TOKENID - Token identifier (user-defined)
• SECRET - Token secret (UUID generated by Proxmox)

Example Tokens

// Root user with PAM authentication
String token = "root@pam!automation=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

// Custom user with PVE realm
String token = "admin@pve!readonly=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy";

// Service account
String token = "backup@pam!backup-service=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz";

Creating API Tokens

Via Proxmox Web Interface

1. Log in to Proxmox web interface
2. Navigate to Datacenter → Permissions → API Tokens
3. Click Add
4. Fill in the form:
   • User: Select the user
   • Token ID: Enter a descriptive name (e.g., automation, readonly)
   • Privilege Separation:
     • Checked: Token has same permissions as user
     • Unchecked: Token has limited permissions (recommended)
   • Expire: Set expiration (optional)
   • Comment: Add description
5. Click Add
6. Important: Copy the displayed secret immediately (shown only once)

Via Command Line

SSH into your Proxmox server:

# Create API token
pveum user token add root@pam automation --privsep 0

# The secret will be displayed - save it immediately

Token Permissions

After creating a token, assign appropriate permissions:

# Grant VM.Admin role to token for all VMs
pveum acl modify /vms -token 'root@pam!automation' -role PVEVMAdmin

# Grant read-only access to cluster
pveum acl modify / -token 'root@pam!readonly' -role PVEAuditor

Using API Tokens

Basic Usage

import fr.freshperf.pve4j.Proxmox;

Proxmox proxmox = Proxmox.create(
    "pve.example.com",
    8006,
    "root@pam!automation=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
);

From Environment Variables

public class ProxmoxConfig {
    public static Proxmox createClient() {
        String host = System.getenv("PROXMOX_HOST");
        int port = Integer.parseInt(System.getenv("PROXMOX_PORT"));
        String token = System.getenv("PROXMOX_API_TOKEN");
        
        return Proxmox.create(host, port, token);
    }
}

Set environment variables:

export PROXMOX_HOST=pve.example.com
export PROXMOX_PORT=8006
export PROXMOX_API_TOKEN=root@pam!automation=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

From Configuration File

import java.io.*;
import java.util.Properties;

public class ProxmoxConfig {
    public static Proxmox createClientFromConfig(String configPath) 
            throws IOException {
        
        Properties props = new Properties();
        try (FileInputStream fis = new FileInputStream(configPath)) {
            props.load(fis);
        }
        
        String host = props.getProperty("proxmox.host");
        int port = Integer.parseInt(props.getProperty("proxmox.port"));
        String token = props.getProperty("proxmox.token");
        
        return Proxmox.create(host, port, token);
    }
}

Configuration file (proxmox.properties):

proxmox.host=pve.example.com
proxmox.port=8006
proxmox.token=root@pam!automation=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Token Security

Never Hardcode Tokens

// BAD - hardcoded token
Proxmox proxmox = Proxmox.create(
    "pve.example.com", 8006, 
    "root@pam!app=12345678-1234-1234-1234-123456789abc"
);

// GOOD - from environment
Proxmox proxmox = Proxmox.create(
    System.getenv("PROXMOX_HOST"),
    Integer.parseInt(System.getenv("PROXMOX_PORT")),
    System.getenv("PROXMOX_API_TOKEN")
);

Use Least Privilege

# Create limited token for specific operations
pveum user token add automation@pve readonly --privsep 1

# Grant only necessary permissions
pveum acl modify /vms -token 'automation@pve!readonly' -role PVEAuditor

Rotate Tokens Regularly

public class TokenRotation {
    public void rotateToken() {
        // 1. Create new token in Proxmox
        // 2. Update configuration with new token
        // 3. Test new token
        // 4. Remove old token from Proxmox
    }
}

Set Expiration Dates

When creating tokens, set expiration dates for better security:

pveum user token add root@pam temp --expire "2025-12-31"

Monitor Token Usage

Regularly audit which tokens are in use and revoke unused ones.

Storing Tokens Securely

Environment Variables

# Linux/Mac
export PROXMOX_API_TOKEN="root@pam!app=secret"

# Windows
set PROXMOX_API_TOKEN=root@pam!app=secret

Encrypted Configuration Files

import javax.crypto.*;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class SecureConfig {
    public String decryptToken(String encryptedToken, String key) 
            throws Exception {
        
        Cipher cipher = Cipher.getInstance("AES");
        SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(), "AES");
        cipher.init(Cipher.DECRYPT_MODE, secretKey);
        
        byte[] decrypted = cipher.doFinal(Base64.getDecoder().decode(encryptedToken));
        return new String(decrypted);
    }
}

Password Authentication

PVE4J supports username/password authentication through the createWithPassword() method. This creates a client that authenticates using a ticket obtained from the Proxmox API.

Basic Password Authentication

import fr.freshperf.pve4j.Proxmox;
import fr.freshperf.pve4j.SecurityConfig;

try {
    // With default PAM realm and secure settings
    Proxmox proxmox = Proxmox.createWithPassword(
        "pve.example.com",
        8006,
        "root",
        "your-password"
    );
    
    // Now you can use the client as normal
    System.out.println("Version: " + proxmox.getVersion().execute().getVersion());
    
} catch (ProxmoxAPIError | InterruptedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
}

With Custom Realm

try {
    // Authenticate with a specific realm (e.g., LDAP, Active Directory)
    Proxmox proxmox = Proxmox.createWithPassword(
        "pve.example.com",
        8006,
        "admin",
        "password",
        "ldap",  // Custom realm
        SecurityConfig.secure()
    );
} catch (ProxmoxAPIError | InterruptedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
}

With Custom Security Configuration

try {
    // For development with self-signed certificates
    Proxmox proxmox = Proxmox.createWithPassword(
        "192.168.1.100",
        8006,
        "root",
        "password",
        SecurityConfig.insecure()
    );
} catch (ProxmoxAPIError | InterruptedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
}

Password Authentication Considerations

• Tickets are short-lived (2 hours by default)
• The client stores the ticket and CSRF token for subsequent requests
• If the session expires, you need to create a new client
• API tokens are recommended for long-running applications

Recommendation: Use API tokens for automated applications and password authentication for interactive tools or short-lived scripts.

Ticket Authentication (Manual)

For more control over the authentication process, you can manually request a ticket:

Get Authentication Ticket

import fr.freshperf.pve4j.entities.access.PveAccessTicket;

try {
    PveAccessTicket ticket = proxmox.getAccess()
            .getTicket("root", "password123", "pam")
            .execute();
    
    System.out.println("Ticket: " + ticket.getTicket());
    System.out.println("CSRF Token: " + ticket.getCSRFPreventionToken());
    System.out.println("Username: " + ticket.getUsername());
    System.out.println("Cluster: " + ticket.getClustername());
    
} catch (ProxmoxAPIError | InterruptedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
}

Ticket Limitations

• Short-lived (2 hours by default)
• Requires password storage
• Needs refresh mechanism for long-running applications

Common Authentication Patterns

Pattern 1: Single Client Instance

public class ProxmoxClient {
    private static final Proxmox INSTANCE;
    
    static {
        INSTANCE = Proxmox.create(
            System.getenv("PROXMOX_HOST"),
            Integer.parseInt(System.getenv("PROXMOX_PORT")),
            System.getenv("PROXMOX_API_TOKEN")
        );
    }
    
    public static Proxmox getInstance() {
        return INSTANCE;
    }
}

Pattern 2: Per-Operation Clients

public class ProxmoxOperations {
    public void performOperation() {
        Proxmox proxmox = createClient();
        try {
            // Perform operation
        } catch (Exception e) {
            // Handle error
        }
    }
    
    private Proxmox createClient() {
        return Proxmox.create(
            System.getenv("PROXMOX_HOST"),
            Integer.parseInt(System.getenv("PROXMOX_PORT")),
            System.getenv("PROXMOX_API_TOKEN")
        );
    }
}

Pattern 3: Multi-Environment Support

public class ProxmoxConfig {
    public enum Environment {
        DEVELOPMENT,
        STAGING,
        PRODUCTION
    }
    
    public static Proxmox createClient(Environment env) {
        String prefix = env.name().toLowerCase();
        
        String host = System.getenv(prefix + "_PROXMOX_HOST");
        int port = Integer.parseInt(System.getenv(prefix + "_PROXMOX_PORT"));
        String token = System.getenv(prefix + "_PROXMOX_TOKEN");
        
        return Proxmox.create(host, port, token);
    }
}

Troubleshooting Authentication

Invalid Token Error (401)

Error: HTTP 401 - Unauthorized

Solutions:

1. Verify token format: USER@REALM!TOKENID=SECRET
2. Check token exists in Proxmox
3. Ensure token is not expired
4. Verify token has required permissions

Permission Denied (403)

Error: HTTP 403 - Forbidden

Solutions:

1. Check token permissions in Proxmox
2. Verify ACL settings for the resource
3. Ensure privilege separation is configured correctly

Testing Token

public boolean testToken(Proxmox proxmox) {
    try {
        proxmox.getVersion().execute();
        System.out.println("Token is valid");
        return true;
    } catch (ProxmoxAPIError e) {
        if (e.getStatusCode() == 401) {
            System.err.println("Token is invalid or expired");
        } else if (e.getStatusCode() == 403) {
            System.err.println("Token lacks necessary permissions");
        }
        return false;
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        return false;
    }
}

Next Steps

• Client Configuration - Configure Proxmox client
• Access Control - User and permission management
• Getting Started - Start using PVE4J