Skip to Content
GuidesWorkflowsEnrollmentFiles Identity Provider

Files Identity Provider

The files provider loads X.509 certificates from the local filesystem. This is ideal for development, testing, or organizations with existing PKI infrastructure.

Quick Start

1. Generate Certificates

For development, generate a self-signed CA and leaf certificates using OpenSSL:

# Create a CA
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -key ca-key.pem -sha256 \
  -subj "/CN=Agent Harbor Dev CA" -days 365 -out ca.pem
 
# Create access point certificate
openssl genrsa -out ap-key.pem 2048
openssl req -new -key ap-key.pem \
  -subj "/CN=access-point" -out ap.csr
 
cat > ap-ext.cnf << EOF
subjectAltName = DNS:localhost, DNS:access-point, IP:127.0.0.1
EOF
 
openssl x509 -req -in ap.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -days 30 -sha256 \
  -extfile ap-ext.cnf -out ap.pem
 
# Create executor certificate
openssl genrsa -out executor-key.pem 2048
openssl req -new -key executor-key.pem \
  -subj "/CN=executor-1" -out executor.csr
 
cat > executor-ext.cnf << EOF
subjectAltName = DNS:executor-1, URI:spiffe://agent-harbor.local/ah/agent/executor-1
EOF
 
openssl x509 -req -in executor.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -days 30 -sha256 \
  -extfile executor-ext.cnf -out executor.pem

2. Start Access Point

ah agent access-point \
  --fleet-listen 0.0.0.0:4433 \
  --server-identity files \
  --cert ap.pem \
  --key ap-key.pem \
  --ca ca.pem \
  --executor-san-uri-prefix "spiffe://agent-harbor.local/ah/agent/"

3. Enroll Executor

ah agent enroll \
  --remote-server https://127.0.0.1:4433 \
  --identity files \
  --cert executor.pem \
  --key executor-key.pem \
  --ca ca.pem \
  --name executor-1

Certificate Requirements

Executor Certificates

Executor certificates must include:

  • Subject Alternative Name (SAN): At least one of:

    • URI with SPIFFE ID: spiffe://trust-domain/ah/agent/name
    • DNS name matching executor hostname
    • IP address of executor

  • Key Usage: Digital Signature, Key Encipherment

  • Extended Key Usage: TLS Client Authentication

Access Point Certificates

Access point certificates must include:

  • Subject Alternative Name (SAN):

    • DNS names clients will connect to
    • IP addresses (if connecting by IP)
    • Optional: SPIFFE ID URI

  • Key Usage: Digital Signature, Key Encipherment

  • Extended Key Usage: TLS Server Authentication

CA Certificates

  • Both parties must trust the same CA chain
  • Can use a self-signed CA or existing enterprise CA
  • Intermediate CAs are supported (provide full chain)

File Permissions

Secure your private keys:

chmod 600 *-key.pem
chmod 644 *.pem
chown agent-harbor:agent-harbor *.pem

Certificate Rotation

The files provider watches certificate files for changes using inotify (Linux) or kqueue (macOS).

When certificates are updated:

  1. Replace the PEM files atomically (use mv, not cp)
  2. The provider detects the change
  3. New connections use the new certificates
  4. Existing connections continue until closed
# Atomic certificate replacement
mv new-cert.pem cert.pem
mv new-key.pem key.pem

Production Considerations

Using Your Enterprise CA

If you have an existing enterprise CA:

  1. Issue certificates with appropriate SANs
  2. Export in PEM format (cert + key separate files)
  3. Include the full CA chain in the CA file

Automated Renewal

For automated renewal, use a script with cron or systemd timer:

#!/bin/bash
# /usr/local/bin/renew-executor-cert.sh
 
# Request new certificate from your CA
# (replace with your CA's issuance mechanism)
step ca certificate executor /tmp/new-cert.pem /tmp/new-key.pem
 
# Atomic replacement
mv /tmp/new-cert.pem /etc/ah/executor.pem
mv /tmp/new-key.pem /etc/ah/executor-key.pem

High Availability

For HA deployments with multiple access points:

  1. Use a shared CA for all access points
  2. Each access point has its own certificate
  3. Executors trust the shared CA
  4. Use load balancer health checks on /healthz

Troubleshooting

Certificate Verification Failed

error: certificate verify failed: unable to get local issuer certificate

Solution: Ensure the CA file includes the full chain:

cat intermediate-ca.pem root-ca.pem > ca-chain.pem

Permission Denied

error: permission denied reading /etc/ah/executor-key.pem

Solution: Check file permissions and ownership:

ls -la /etc/ah/
sudo chown agent-harbor:agent-harbor /etc/ah/*.pem
sudo chmod 600 /etc/ah/*-key.pem

Certificate Expired

error: certificate has expired or is not yet valid

Solution:

  1. Check system time: date
  2. Renew certificates
  3. Verify not-before/not-after dates: openssl x509 -in cert.pem -noout -dates

Example: step-ca Integration

step-ca  provides an easy-to-deploy CA:

# Initialize CA
step ca init --name "Agent Harbor CA" --dns localhost --address :443
 
# Issue executor certificate
step ca certificate executor /etc/ah/executor.pem /etc/ah/executor-key.pem
 
# Issue access point certificate
step ca certificate access-point /etc/ah/ap.pem /etc/ah/ap-key.pem \
  --san localhost --san access-point.example.com

Next Steps

Executor EnrollmentSPIFFE/SPIRE Deployment Guide