Authentication

PiVirt supports flexible, zero-trust authentication mechanisms tailored for interactive CLI users, automated CI/CD runners, and internal service-to-service communications.

Authentication Methods

1. OIDC (OpenID Connect)

For external clients (pvcli, Web UIs).

Configuration:

# agent config
auth:
  oidc:
    issuer_url: "https://auth.pilab.hu/realms/pivirt"
    client_id: "pivirt-agent"
    # JWKS auto-discovered from issuer_url/.well-known/jwks.json

Login with pvcli:

# Interactive login (opens browser)
pvcli auth login --oidc

# Device code flow (headless)
pvcli auth login --oidc --device-code

# Check token status
pvcli auth status

# Refresh token
pvcli auth refresh

Supported Providers:

• Keycloak
• Dex
• Auth0
• Azure AD
• Google Workspace

2. mTLS (Mutual TLS)

For service-to-service authentication.

Configuration:

# agent config
server:
  connectrpc:
    tls:
      cert_file: "/etc/pivirt-agent/tls/server.crt"
      key_file: "/etc/pivirt-agent/tls/server.key"
      ca_file: "/etc/pivirt-agent/tls/ca.crt"
      client_ca_file: "/etc/pivirt-agent/tls/ca.crt"

pvcli mTLS:

# Generate client certificate
pvcli cert generate --cn "admin@pilab.hu" --org "PiLab"

# Configure context with certificates
pvcli config set-context production \
  --ca-file /path/to/ca.crt \
  --cert-file /path/to/client.crt \
  --key-file /path/to/client.key

3. PiTrust PKI & Zero-Trust mTLS

For service-to-service zero-trust identity and automated certificate management.

Configuration:

# agent config
tls:
  enabled: true
  ca_file: "/etc/pivirt/certs/ca-chain.pem"
  cert_file: "/etc/pivirt/certs/agent-client.crt"
  key_file: "/etc/pivirt/certs/agent-client.key"
  verify_peer: true
  require_client_cert: true

Automated Kubernetes Management:

• Declarative ManagedCertificate CRDs managed by PiTrust Operator
• Automatic 30-day pre-expiry renewal into Kubernetes Secrets
• Zero external ACME/DNS challenge requirement (air-gapped ready)

4. API Keys

For service accounts and automation.

Create API Key:

pvcli auth apikey create \
  --name "ci-pipeline" \
  --role "operator" \
  --namespace "production" \
  --ttl 30d

Use API Key:

export PIVIRT_API_KEY="pivirt_apikey_..."
pvcli vm list

Token Management

JWT Tokens

# Get token info
pvcli auth token inspect

# Decode token
pvcli auth token decode

# Revoke token
pvcli auth token revoke --token-id <id>

Service Account Tokens

apiVersion: pivirt.pilab.hu/v1
kind: ServiceAccount
metadata:
  name: ci-pipeline
  namespace: production
spec:
  roles:
    - "operator"
  token_ttl: "30d"

Multi-Factor Authentication

TOTP (Time-based One-Time Password)

# Enable MFA for user
pvcli auth mfa enable --user admin@pilab.hu --method totp

# Verify MFA
pvcli auth login --mfa

Hardware Keys (FIDO2/WebAuthn)

# Register hardware key
pvcli auth mfa enable --user admin@pilab.hu --method webauthn

# Login with hardware key
pvcli auth login --mfa

Session Management

Session Configuration

# agent config
auth:
  session:
    max_age: "24h"
    idle_timeout: "1h"
    refresh_interval: "5m"

Active Sessions

# List active sessions
pvcli auth session list

# Revoke session
pvcli auth session revoke --session-id <id>

# Revoke all sessions
pvcli auth session revoke --all

Troubleshooting

Authentication Failures

# Check token validity
pvcli auth status

# Verify OIDC configuration
cat /etc/pivirt-agent/config.yaml | grep -A5 oidc

# Check certificate validity
openssl x509 -in ~/.config/pvcli/client.crt -text -noout | grep "Not After"

# Test OIDC endpoint
curl https://auth.pilab.hu/realms/pivirt/.well-known/openid-configuration

Common Issues

Issue	Resolution
Token expired	Refresh token: pvcli auth refresh
Certificate expired	Regenerate certificate: pitrust issue-mtls-client or check Operator
OIDC provider unreachable	Check network, verify issuer_url
mTLS handshake failed	Verify CA trust chain with PiRootR1.pem / PiCA.pem

Related

• Security Overview
• TLS/mTLS
• PiTrust PKI & mTLS
• RBAC
• pvcli Authentication