AuthKeySync

Automatically synchronize SSH public keys from remote URLs to your servers

📖 Full Documentation

The Problem

Managing SSH access across multiple servers is painful:

• Team members join or leave, and you need to update authorized_keys on every server
• Developers rotate their SSH keys, and now you have 20 servers to update
• You're using Infrastructure as Code, but SSH key management is still manual
• Homemade bash scripts for key management are often poorly written, insecure, or have subtle bugs that can lock you out of your servers
• You want to use GitHub/GitLab keys, but copying them everywhere is tedious

The Solution

AuthKeySync is a lightweight CLI that fetches SSH public keys from URLs (GitHub, GitLab, your own API) and syncs them to your servers. It's safe, reliable, and designed for automation.

# /etc/authkeysync/config.yaml
users:
  - username: "deploy"
    sources:
      - url: "https://github.com/your-username.keys"
      - url: "https://github.com/another-username.keys"

Run authkeysync (manually or via cron), and your authorized_keys is updated. That's it.

Key Features

• Single binary: No dependencies, just download and run
• Safe by default: Preserves existing local keys, creates backups, uses atomic writes
• Fail-safe: If any source fails, the update is aborted to prevent lockouts
• Flexible sources: GitHub, GitLab, or any URL returning plain text SSH keys
• API support: POST requests with custom headers for authenticated APIs
• IaC-ready: Stateless, idempotent, perfect for Ansible/Terraform/cloud-init
• Cross-platform: Works on Linux and macOS (AMD64 and ARM64)

Quick Start

1. Download

Get the latest binary from the releases page:

# Linux AMD64
curl -Lo authkeysync https://github.com/eduardolat/authkeysync/releases/latest/download/authkeysync-linux-amd64
chmod +x authkeysync
sudo mv authkeysync /usr/local/bin/

2. Configure

Create a config file at /etc/authkeysync/config.yaml:

policy:
  backup_enabled: true # Create backups before changes (default: true)
  backup_retention_count: 10 # Number of backups to keep (default: 10)
  preserve_local_keys: true # Keep keys not in remote sources (default: true)

users:
  - username: "root"
    sources:
      - url: "https://github.com/your-username.keys"

3. Run

# Test first with dry-run
sudo authkeysync --dry-run

# Apply changes
sudo authkeysync

4. Automate

Set up a cron job or systemd timer to run periodically:

# Every 5 minutes (use --quiet to reduce log noise in cron)
echo "*/5 * * * * root /usr/local/bin/authkeysync --quiet" | sudo tee /etc/cron.d/authkeysync

Configuration Options

Policy (all optional)

Users (required)

Sources

Example with all options

policy:
  backup_enabled: true
  backup_retention_count: 10
  preserve_local_keys: true

users:
  - username: "deploy"
    sources:
      # Simple GitHub keys
      - url: "https://github.com/your-username.keys"

      # Private API with authentication
      - url: "https://keys.yourcompany.com/api/keys"
        method: "POST"
        headers:
          Authorization: "Bearer your-secret-token"
          Content-Type: "application/json"
        body: '{"environment": "production"}'
        timeout_seconds: 5

CLI Options

Exit Codes

How It Works

1. Fetch: Downloads SSH keys from configured URLs
2. Parse: Validates and deduplicates keys across all sources
3. Merge: Optionally preserves keys that only exist locally
4. Write: Atomically updates authorized_keys with proper permissions
5. Backup: Creates timestamped backups before any changes

If any source fails to fetch, AuthKeySync aborts the update for that user to prevent lockouts. Your existing access remains intact.

Support the Project

If you find AuthKeySync useful, please consider giving it a star on GitHub and following me on X (Twitter) for updates:

• Star on GitHub
• Follow @eduardoolat on X

License

MIT License. See LICENSE for details.