VaulTLS is a modern solution for managing mTLS (mutual TLS) certificates with ease. It provides a centralized platform for generating, managing, and distributing client TLS certificates for your home lab.

The main reason why I developed VaulTLS was that I didn't like messing with shell scripts and OpenSSL. I also did not have an overview about the expiration of individual certificates.

• 🔒 mTLS client and CA certificate management
• 📱 Modern web interface for certificate management
• 🔐 OpenID Connect authentication support
• 📨 Email notifications for certificate expiration
• 🚀 RESTful API for automation
• 🛠 Docker/Podman container support
• ⚡ Built with Rust (backend) and Vue.js (frontend) for performance and reliability

Installation is managed through a Container. The app needs to be behind a reverse proxy for TLS handling. VAULTLS_API_SECRET is required and should be a 256-bit base64 encoded string (openssl rand -base64 32).

podman run -d \
  --name vaultls \
  -p 5173:80 \
  -v vaultls-data:/app/data \
  -e VAULTLS_API_SECRET="[VAULTLS_API_SECRET]" \
  -e VAULTLS_URL="https://vaultls.example.com/" \
  ghcr.io/7ritn/vaultls:latest

By specifying the VAULTLS_DB_SECRET environmental variable, the database is encrypted. Data is retained. It is not possible to go back.

To set up OIDC you need to create a new client in your authentication provider. For Authelia a configuration could look like this

- client_id: "[client_id]"
  client_name: "vautls"
  client_secret: "[client_secret_hash]"
  public: false
  authorization_policy: "one_factor"
  pkce_challenge_method: "S256"
  redirect_uris:
    - "https://vaultls.example.com/api/auth/oidc/callback"
  scopes:
    - "openid"
    - "profile"
    - "email"
  userinfo_signed_response_alg: "none"

For VaulTLS the required variables can be configured via environmental variables or web UI.

If VaulTLS claims that OIDC is not configured, the most likely cause is that it couldn't discover the OIDC provider based on the VAULTLS_OIDC_AUTH_URL given. In general the the base url to the auth provider should be enough. For Authentik the required URL path is /application/o/<application slug>/. If that doesn't work, directly specify the .well_known url.

During the first setup a Certificate Authority is automatically created. If OIDC is configured no password needs to be set. Users can either log in via password or OIDC. If a user first logs in via OIDC their e-mail is matched with all VaulTLS users and linked. If no user is found a new one is created.

Users can only see certificates created for them. Only admins can create new certificates. User certificates can be downloaded through the web interface.

The CA certificate to be integrated with your reverse proxy is available as a file at /app/data/ca.cert and as download via the API endpoint /api/certificates/ca/download.

By default, PKCS12 passwords are optional and certificates will be generated with no password. In the settings page, the PKCS12 password requirements can be set with the following options:

Passwords are stored in the database and retrieved from the web interface only when the user clicks on view password.

To use caddy as reverse proxy for the VaulTLS app, a configuration like the following is required.

reverse_proxy 127.0.0.1:5173

To integrate the CA cert for client validation, you can either use a file or http based approach. Extend your TLS instruction for that with the client_auth section. Documentation here: https://caddyserver.com/docs/caddyfile/directives/tls#client_auth.

File based:

tls {
  client_auth {
    mode <usually verify_if_given OR require_and_verify>
    trust_pool file {
      pem_file <Path to VaulTLS Directory>/ca.cert
    }
  }
}

HTTP based:

tls {
  client_auth {
    mode <usually verify_if_given OR require_and_verify>
    trust_pool http {
      endpoints <Address of VaulTLS Instance such as 127.0.0.1:5173>/api/certificates/ca/download
    }
  }
}

If you choose verify_if_given, you can still block clients for apps that you want to require client authentication:

@blocked {
  vars {tls_client_subject} ""
}
abort @blocked

• Add database encryption
• Hash passwords in Frontend
• Allow user details to be updated
• Generate new certificates automatically if the old one expires soon
• Add testing
• Add / improve logging