{"id":22436974,"url":"https://github.com/c2fmzq/tlsproxy","last_synced_at":"2026-02-11T00:03:47.209Z","repository":{"id":176359728,"uuid":"655841358","full_name":"c2FmZQ/tlsproxy","owner":"c2FmZQ","description":"TLSPROXY is a TLS termination proxy that provides automatic TLS encryption for various network services. It supports SSO, client authentication, and can act as a web server or reverse proxy.","archived":false,"fork":false,"pushed_at":"2026-01-29T17:32:21.000Z","size":1452,"stargazers_count":97,"open_issues_count":4,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-30T05:23:57.627Z","etag":null,"topics":["ech","golang","http3","lets-encrypt","mtls","oidc","passkey","passkeys","pki","quic","reverse-proxy","security","self-hosted","sso","tls-proxy","tlspassthrough","tpm"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/c2FmZQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-19T18:01:26.000Z","updated_at":"2026-01-29T17:32:25.000Z","dependencies_parsed_at":"2026-01-16T11:05:09.250Z","dependency_job_id":null,"html_url":"https://github.com/c2FmZQ/tlsproxy","commit_stats":null,"previous_names":["c2fmzq/tlsproxy"],"tags_count":142,"template":false,"template_full_name":null,"purl":"pkg:github/c2FmZQ/tlsproxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c2FmZQ%2Ftlsproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c2FmZQ%2Ftlsproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c2FmZQ%2Ftlsproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c2FmZQ%2Ftlsproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/c2FmZQ","download_url":"https://codeload.github.com/c2FmZQ/tlsproxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c2FmZQ%2Ftlsproxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29322733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T20:44:44.282Z","status":"ssl_error","status_checked_at":"2026-02-10T20:44:43.393Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ech","golang","http3","lets-encrypt","mtls","oidc","passkey","passkeys","pki","quic","reverse-proxy","security","self-hosted","sso","tls-proxy","tlspassthrough","tpm"],"created_at":"2024-12-06T00:10:30.201Z","updated_at":"2026-02-11T00:03:47.184Z","avatar_url":"https://github.com/c2FmZQ.png","language":"Go","readme":"[![pr](https://github.com/c2FmZQ/tlsproxy/actions/workflows/pr.yml/badge.svg?branch=main)](https://github.com/c2FmZQ/tlsproxy/actions/workflows/pr.yml)\n[![release](https://github.com/c2FmZQ/tlsproxy/actions/workflows/release.yml/badge.svg)](https://github.com/c2FmZQ/tlsproxy/actions/workflows/release.yml)\n[![CodeQL](https://github.com/c2FmZQ/tlsproxy/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/c2FmZQ/tlsproxy/actions/workflows/github-code-scanning/codeql)\n\n# TLSPROXY\n\n\u003cdetails\u003e\n\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\n- [1. Overview](#1-overview)\n- [2. Installation](#2-installation)\n  - [From Source](#from-source)\n  - [Docker Image](#docker-image)\n  - [Precompiled Binaries](#precompiled-binaries)\n  - [Verifying Signatures](#verifying-signatures)\n- [3. Configuration](#3-configuration)\n  - [`config.yaml` Structure](#configyaml-structure)\n  - [Backend Configuration (`Backend` Object)](#backend-configuration-backend-object)\n    - [SSORule Object](#ssorule-object)\n    - [LocalOIDCServer Object](#localoidcserver-object)\n      - [LocalOIDCClient Object](#localoidcclient-object)\n      - [LocalOIDCRewriteRule Object](#localoidcrewriterule-object)\n    - [TrustedIssuer Object](#trustedissuer-object)\n  - [Identity Provider Configuration](#identity-provider-configuration)\n  - [Group and Member Objects](#group-and-member-objects)\n    - [`Group` Object](#group-object)\n    - [`Member` Object](#member-object)\n  - [PKI Configuration (`ConfigPKI`)](#pki-configuration-configpki)\n  - [SSH Certificate Authority Configuration (`ConfigSSHCertificateAuthority`)](#ssh-certificate-authority-configuration-configsshcertificateauthority)\n  - [Bandwidth Limit Configuration (`BWLimit`)](#bandwidth-limit-configuration-bwlimit)\n  - [WebSocket Configuration (`WebSocketConfig`)](#websocket-configuration-websocketconfig)\n  - [ECH Configuration (`ECH` Object)](#ech-configuration-ech-object)\n  - [ForwardECH Configuration (`BackendECH` Object)](#forwardech-configuration-backendech-object)\n- [4. Usage](#4-usage)\n- [5. Common Use Cases](#5-common-use-cases)\n  - [5.1. Basic HTTP/HTTPS Proxying](#51-basic-httphttps-proxying)\n    - [5.1.1. HTTP Mode (HTTPS to HTTP)](#511-http-mode-https-to-http)\n    - [5.1.2. HTTPS Mode (HTTPS to HTTPS)](#512-https-mode-https-to-https)\n  - [5.2. TCP Proxying](#52-tcp-proxying)\n    - [5.2.1. TCP Mode (TLS to Plain TCP)](#521-tcp-mode-tls-to-plain-tcp)\n    - [5.2.2. TLSPASSTHROUGH Mode (TLS Passthrough)](#522-tlspassthrough-mode-tls-passthrough)\n  - [5.3. SSH Proxying with `tlsclient`](#53-ssh-proxying-with-tlsclient)\n  - [5.4. Setting up an SSH Certificate Authority (CA)](#54-setting-up-an-ssh-certificate-authority-ca)\n  - [5.5. Getting SSH Certificates](#55-getting-ssh-certificates)\n  - [5.6. Setting up PKI (Public Key Infrastructure)](#56-setting-up-pki-public-key-infrastructure)\n  - [5.7. Serving Static Files](#57-serving-static-files)\n  - [5.8. QUIC/HTTP3 Proxying](#58-quichttp3-proxying)\n- [6. Advanced Topics](#6-advanced-topics)\n- [7. Support and Community](#7-support-and-community)\n\n\u003c/details\u003e\n\n```mermaid\nflowchart LR\n  subgraph Incoming TLS Connections\n    h1(\"web.example.com\")\n    h2(\"foo.example.com\")\n    h3(\"bar.example.com\")\n    h4(...)\n  end\n  prx(((TLSPROXY)))\n  subgraph Backend Services\n    be1(HTTP Server)\n    be2(HTTPS Server)\n    be3(IMAP, SMTP, SSH)\n    be4(Any TCP, TLS, or QUIC Server)\n  end\n  h1--\u003eprx\n  h2--\u003eprx\n  h3--\u003eprx\n  h4--\u003eprx\n  prx--\u003ebe1\n  prx--\u003ebe2\n  prx--\u003ebe3\n  prx--\u003ebe4\n```\n\n## 1. Overview\n\nTLSPROXY is a versatile [TLS termination proxy](https://en.wikipedia.org/wiki/TLS_termination_proxy) designed to secure various network services. It automatically handles TLS encryption using [Let's Encrypt](https://letsencrypt.org/), allowing multiple services and server names to share the same port. Beyond TLS termination, TLSPROXY can function as a simple [web server](https://en.wikipedia.org/wiki/Web_server), a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) for HTTP(S) services, and offers robust user authentication and authorization features.\n\n**Key Features:**\n\n*   **Automatic TLS Certificates:** Integrates with Let's Encrypt for automatic certificate acquisition using http-01 and tls-alpn-01 challenges.\n*   **Flexible TLS Termination:**\n    *   Terminates TLS and forwards data to TCP servers in plain text.\n    *   Terminates TLS and forwards data to TLS servers (encrypted in transit, proxy sees plain text).\n    *   Passes through raw TLS connections to backend TLS servers (proxy does not see plain text).\n*   **QUIC and HTTP/3 Support:** Terminates QUIC connections and forwards data to QUIC or TLS/TCP servers.\n*   **Encrypted Client Hello (ECH):** Enhances privacy by encrypting ClientHello messages.\n*   **Static File Serving:** Can serve static content directly from the local filesystem.\n*   **PROXY Protocol Support:** Integrates with the PROXY protocol for incoming TCP connections (not for QUIC or HTTP/3 backends).\n*   **Client Authentication \u0026 Authorization:** Supports TLS client authentication and authorization when the proxy terminates TLS connections.\n*   **Built-in Certificate Authorities:**\n    *   Manages client and backend server TLS certificates.\n    *   Issues SSH user certificates based on SSO credentials.\n*   **User Authentication:** Supports OpenID Connect, SAML, and Passkeys for HTTP and HTTPS connections. Can optionally issue JSON Web Tokens (JWTs) and run a local OpenID Connect server.\n*   **Access Control:** Implements access control based on IP addresses.\n*   **Routing \u0026 Load Balancing:** Routes requests based on Server Name Indication (SNI) with optional default routes and simple round-robin load balancing.\n*   **ALPN Protocol Support:** Supports any ALPN protocol in TLS, TLSPASSTHROUGH, QUIC, or TCP mode.\n*   **OCSP Stapling \u0026 Verification:** Includes OCSP stapling and certificate verification.\n*   **Local TLS Certificates:** Supports using locally stored TLS certificates.\n*   **Hardware-backed Cryptographic Keys:** Can use a Trusted Platform Module (TPM) for enhanced security of cryptographic keys.\n*   **Port Sharing:** Allows multiple server names to share the same IP address and port.\n\n## 2. Installation\n\n### From Source\n\nTo install TLSPROXY from its source code, follow these steps:\n\n```console\ngit clone https://github.com/c2FmZQ/tlsproxy.git\ncd tlsproxy\ngo generate ./...\ngo build -o tlsproxy\n```\n\n### Docker Image\n\nYou can use the official Docker image from [Docker Hub](https://hub.docker.com/r/c2fmzq/tlsproxy). Here's an example command:\n\n```console\ndocker run \\\n  --name=tlsproxy \\\n  --user=1000:1000 \\\n  --restart=always \\\n  --volume=${CONFIGDIR}:/config \\\n  --volume=${CACHEDIR}:/.cache \\\n  --publish=80:10080 \\\n  --publish=443:10443 \\\n  --env=TLSPROXY_PASSPHRASE=\"\u003cpassphrase\u003e\" \\\n  c2fmzq/tlsproxy:latest\n```\n\nThe proxy reads the configuration from ${CONFIGDIR}/config.yaml.\n\n:warning: The `${TLSPROXY_PASSPHRASE}` environment variable is crucial as it's used to encrypt the TLS secrets.\n\n### Precompiled Binaries\n\nPrecompiled binaries for various platforms are available on the [release page](https://github.com/c2FmZQ/tlsproxy/releases).\n\n### Verifying Signatures\n\nIt is highly recommended to verify the authenticity of downloaded binaries and container images.\n\n**Container Image:**\n\nTo verify the authenticity of a container image, use `cosign`:\n\n```console\ncosign verify \\\n  --certificate-identity-regexp='^https://github[.]com/c2FmZQ/tlsproxy/[.]github/workflows/release[.]yml' \\\n  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \\\n  c2fmzq/tlsproxy:latest\n```\n\nAlternatively, if you have the public key:\n\n```console\ncosign verify --key keys/cosign.pub c2fmzq/tlsproxy:latest\n```\n\n**Release Binary:**\n\nTo verify the authenticity of a release binary, first import the `c2FmZQ-bot.pub` key:\n\n```console\ncurl https://raw.githubusercontent.com/c2FmZQ/tlsproxy/main/keys/c2FmZQ-bot.pub | gpg --import\n```\n\nThen, verify the signature (e.g., for `tlsproxy-linux-amd64`):\n\n```console\ngpg --verify tlsproxy-linux-amd64.sig tlsproxy-linux-amd64\n```\n\n## 3. Configuration\n\nTLSPROXY is configured using a YAML file, typically named `config.yaml`. This file defines how the proxy behaves, including backend services, authentication methods, and security settings.\n\nThe [examples directory](https://github.com/c2FmZQ/tlsproxy/tree/main/examples) contains full configuration files for various use cases.\n\n### `config.yaml` Structure\n\nThe main configuration options are:\n\n*   `acceptTOS`: (Required) Boolean. Indicates acceptance of the Let's Encrypt Terms of Service. Must be `true` for Let's Encrypt to function.\n*   `email`: (Optional) String. Your email address, used by Let's Encrypt for important notifications.\n*   `httpAddr`: (Optional) String. The address where the proxy listens for HTTP connections (e.g., `\":80\"` or `\":10080\"`). Essential for Let's Encrypt's http-01 challenge.\n*   `tlsAddr`: (Required) String. The address where the proxy listens for TLS connections (e.g., `\":443\"` or `\":10443\"`).\n*   `enableQUIC`: (Optional) Boolean. Enables QUIC protocol support. Defaults to `true` if compiled with QUIC support.\n*   `ech`: (Optional) Object. Configures Encrypted Client Hello (ECH).\n*   `acceptProxyHeaderFrom`: (Optional) List of CIDRs. Enables PROXY protocol for connections from specified IP ranges.\n*   `hwBacked`: (Optional) Boolean. Enables hardware-backed cryptographic keys (e.g., with a TPM).\n*   `cacheDir`: (Optional) String. Directory for storing TLS certificates, OCSP responses, etc. Defaults to a system cache directory.\n*   `defaultServerName`: (Optional) String. Server name to use when SNI is not provided by the client.\n*   `logFilter`: (Optional) Object. Controls what gets logged (connections, requests, errors).\n*   `groups`: (Optional) List of `Group` objects. Defines user groups for access control.\n*   `backends`: (Required) List of `Backend` objects. Defines the services TLSPROXY will forward traffic to.\n*   `oidc`: (Optional) List of `ConfigOIDC` objects. Defines OpenID Connect identity providers.\n*   `saml`: (Optional) List of `ConfigSAML` objects. Defines SAML identity providers.\n*   `passkey`: (Optional) List of `ConfigPasskey` objects. Defines Passkey managers.\n*   `pki`: (Optional) List of `ConfigPKI` objects. Defines local Certificate Authorities.\n*   `sshCertificateAuthorities`: (Optional) List of `ConfigSSHCertificateAuthority` objects. Defines local SSH Certificate Authorities.\n*   `tlsCertificates`: (Optional) List of `TLSCertificate` objects. Specifies pre-existing TLS certificates to use.\n*   `bwLimits`: (Optional) List of `BWLimit` objects. Defines named bandwidth limit groups.\n*   `webSockets`: (Optional) List of `WebSocketConfig` objects. Defines WebSocket endpoints.\n\nSee the [GoDoc](https://pkg.go.dev/github.com/c2FmZQ/tlsproxy/proxy#Config) for complete and up-to-date documentation.\n\n### Backend Configuration (`Backend` Object)\n\nEach `Backend` object defines a service and its behavior:\n\n*   `serverNames`: (Required) List of strings. DNS names for this service.\n*   `mode`: (Required) String. Controls how the proxy communicates with the backend. Valid values include `TCP`, `TLS`, `TLSPASSTHROUGH`, `QUIC`, `HTTP`, `HTTPS`, `LOCAL`, `CONSOLE`.\n*   `addresses`: (Optional) List of strings. Backend server addresses (e.g., `192.168.1.10:80`).\n*   `documentRoot`: (Optional) String. Directory for serving static files (only if `addresses` is empty).\n*   `clientAuth`: (Optional) Object. Configures TLS client authentication.\n    *   `acl`: (Optional) List of strings. Restricts client identities (email, subject, DNS, URI).\n    *   `rootCAs`: (Optional) List of strings. CA names or PEM-encoded certificates for client verification.\n    *   `addClientCertHeader`: (Optional) List of strings. Specifies which client certificate fields to add to `X-Forwarded-Client-Cert` header.\n*   `sso`: (Optional) Object. Configures Single Sign-On for the backend.\n    *   `provider`: String. Name of an OIDC or SAML provider.\n    *   `rules`: List of `SSORule` objects. Defines path-matching rules for SSO enforcement.\n    *   `htmlMessage`: String. HTML message displayed on permission denied screen (not escaped).\n    *   `setUserIdHeader`: Boolean. Sets `x-tlsproxy-user-id` header with user's email.\n    *   `generateIdTokens`: Boolean. Generates ID tokens for authenticated users.\n    *   `localOIDCServer`: Object. Configures a local OpenID Provider.\n*   `exportJwks`: (Optional) String. Path to export the proxy's JSON Web Key Set.\n*   `alpnProtos`: (Optional) List of strings. ALPN protocols supported by this backend.\n*   `backendProto`: (Optional) String. Protocol for forwarding HTTPS requests to the backend (e.g., `http/1.1`, `h2`, `h3`).\n*   `insecureSkipVerify`: (Optional) Boolean. Disables backend server TLS certificate verification (use with caution).\n*   `forwardServerName`: (Optional) String. ServerName to send in TLS handshake with backend.\n*   `forwardRootCAs`: (Optional) List of strings. CA names or PEM-encoded certificates for backend verification.\n*   `forwardTimeout`: (Optional) Duration. Connection timeout to backend servers.\n*   `forwardHttpHeaders`: (Optional) Map of strings. HTTP headers to add to forwarded requests.\n*   `forwardECH`: (Optional) Object. ECH parameters for connecting to the backend.\n*   `pathOverrides`: (Optional) List of `PathOverride` objects. Defines different backend parameters for specific path prefixes.\n*   `proxyProtocolVersion`: (Optional) String. Enables PROXY protocol on this backend (`v1` or `v2`).\n*   `sanitizePath`: (Optional) Boolean. Sanitizes request path before forwarding (defaults to `true`).\n*   `serverCloseEndsConnection`: (Optional) Boolean. Closes TCP connection when server closes its end.\n*   `clientCloseEndsConnection`: (Optional) Boolean. Closes TCP connection when client closes its end.\n*   `halfCloseTimeout`: (Optional) Duration. Timeout for half-closed TCP connections.\n\n#### SSORule Object\n\nThe `SSORule` object allows for fine-grained control over SSO enforcement based on request paths. Each rule in the `rules` list is evaluated in order, and the first matching rule is applied.\n\n*   `paths`: (Optional) List of strings. A list of path prefixes to which this rule applies. If empty, the rule matches all paths.\n*   `exceptions`: (Optional) List of strings. A list of path prefixes that are exempt from this rule.\n*   `forceReAuth`: (Optional) Duration. A time duration after which the user must re-authenticate, even if their session is still valid.\n*   `acl`: (Optional) List of strings. A list of email addresses or domains (e.g., `bob@example.com`, `@example.com`) that are allowed access. If not provided, all authenticated users are allowed.\n*   `scopes`: (Optional) List of strings. A list of scopes that the user must have to be granted access.\n\n**Example:**\n\n```yaml\nsso:\n  provider: \"my-oidc-provider\"\n  rules:\n    - paths:\n      - \"/admin/\"\n      forceReAuth: \"1h\"\n      acl:\n      - \"admin@example.com\"\n    - paths:\n      - \"/public/\"\n      exceptions:\n      - \"/public/login\"\n    - acl:\n      - \"@example.com\"\n```\n\nIn this example:\n1.  Access to `/admin/` requires re-authentication every hour and is restricted to `admin@example.com`.\n2.  All paths under `/public/` are subject to SSO, except for `/public/login`.\n3.  All other paths are accessible to any authenticated user from the `@example.com` domain.\n\n#### LocalOIDCServer Object\n\nThe `localOIDCServer` object allows `tlsproxy` to act as an OpenID Connect (OIDC) provider, issuing tokens to authenticated users. This is useful for services that can authenticate using OIDC.\n\nWhen `localOIDCServer` is configured, `tlsproxy` exposes the following endpoints:\n*   `/.well-known/openid-configuration`\n*   `/authorization`\n*   `/token`\n*   `/jwks`\n*   `/device/authorization`\n*   `/device/verification`\n\nThe paths can be prefixed using the `pathPrefix` field.\n\n*   `pathPrefix`: (Optional) String. A prefix for the OIDC endpoints.\n*   `tokenLifetime`: (Optional) Duration. The lifetime of the OIDC tokens. Defaults to 10 minutes.\n*   `clients`: (Required) List of `LocalOIDCClient` objects. Defines the OIDC clients that are allowed to connect.\n*   `rewriteRules`: (Optional) List of `LocalOIDCRewriteRule` objects. Defines rules to rewrite claims in the ID token.\n*   `scopes`: (Optional) List of strings. A list of scopes that may be requested by clients.\n\n##### LocalOIDCClient Object\n\n*   `id`: (Required) String. The OIDC client ID.\n*   `secret`: (Required) String. The OIDC client secret.\n*   `redirectUri`: (Required) List of strings. The OIDC redirect URIs.\n*   `acl`: (Optional) List of strings. A list of email addresses or domains (e.g., `bob@example.com`, `@example.com`) that are allowed to use this client.\n\n##### LocalOIDCRewriteRule Object\n\n*   `inputClaim`: (Required) String. The name of the claim to use as input.\n*   `outputClaim`: (Required) String. The name of the claim to create or overwrite.\n*   `regex`: (Required) String. A regular expression to match against the input claim's value.\n*   `value`: (Required) String. The new value for the output claim. Can use capture groups from the regex.\n\n**Example:**\n\n```yaml\nsso:\n  provider: \"my-sso-provider\"\n  localOIDCServer:\n    tokenLifetime: \"1h\"\n    clients:\n      - id: \"my-app\"\n        secret: \"a-very-secret-string\"\n        redirectUri:\n          - \"https://my-app.example.com/oauth2/callback\"\n        acl:\n          - \"@example.com\"\n    rewriteRules:\n      - inputClaim: \"email\"\n        outputClaim: \"preferred_username\"\n        regex: \"^([^@]+)@.+$\"\n        value: \"$1\"\n```\nIn this example:\n1.  The local OIDC server will issue tokens with a lifetime of 1 hour.\n2.  The client `my-app` is allowed to authenticate, and only users with an email address ending in `@example.com` can use it.\n3.  A `preferred_username` claim will be added to the ID token, containing the local part of the user's email address.\n\n#### TrustedIssuer Object\n\nThe `TrustedIssuer` object defines an external identity provider whose tokens are accepted by `tlsproxy`. This is useful for distributed authentication where multiple proxies trust each other's user identity tokens.\n\n*   `issuer`: (Required) String. The expected \"iss\" claim value (e.g., \"https://auth.example.com/\").\n*   `jwksUri`: (Required) String. The URL to fetch the JSON Web Key Set (JWKS).\n\n**Example:**\n\n```yaml\nsso:\n  provider: \"my-oidc-provider\"\n\noidc:\n  - name: \"my-oidc-provider\"\n    discoveryUrl: \"https://accounts.google.com/.well-known/openid-configuration\"\n    ...\n    trustedIssuers:\n      - issuer: \"https://other-proxy.example.com/\"\n        jwksUri: \"https://other-proxy.example.com/.sso/jwks\"\n```\n\n\n### Identity Provider Configuration\n\n*   **`ConfigOIDC` (OpenID Connect):**\n    *   `name`: String. Internal name.\n    *   `discoveryUrl`: String. Discovery URL.\n    *   `authorizationEndpoint`: String. Authorization endpoint.\n    *   `scopes`: List of strings. Scopes to request (e.g., `openid`, `email`, `profile`).\n    *   `hostedDomain`: String. Restricts login to a specific domain (Google only).\n    *   `tokenEndpoint`: String. Token endpoint.\n    *   `userinfoEndpoint`: String. Userinfo endpoint.\n    *   `redirectUrl`: String. OAuth2 redirect URL.\n    *   `clientId`: String. Client ID.\n    *   `clientSecret`: String. Client Secret.\n    *   `domain`: String. Domain for user identities.\n    *   `trustedIssuers`: List of `TrustedIssuer` objects. Defines external issuers whose tokens are accepted when using this provider.\n\n    **Example (Google OpenID Connect):**\n\n    ```yaml\n    oidc:\n    - name: \"google\"\n      discoveryUrl: \"https://accounts.google.com/.well-known/openid-configuration\"\n      redirectUrl: \"https://login.example.com/oidc/google\"\n      clientId: \"\u003cYOUR CLIENT ID\u003e\"\n      clientSecret: \"\u003cYOUR CLIENT SECRET\u003e\"\n      hostedDomain: \"example.com\" # Optional: Restrict to a specific Google Workspace domain\n    ```\n\n*   **`ConfigSAML` (SAML):**\n    *   `name`: String. Internal name.\n    *   `ssoUrl`: String. SSO URL.\n    *   `entityId`: String. Entity ID.\n    *   `certs`: String. PEM-encoded certificates.\n    *   `acsUrl`: String. ACS URL.\n    *   `domain`: String. Domain for user identities.\n    *   `trustedIssuers`: List of `TrustedIssuer` objects. Defines external issuers whose tokens are accepted when using this provider.\n\n    **Example (Google Workspace SAML):**\n\n    ```yaml\n    saml:\n    - name: \"google-saml\"\n      ssoUrl: \"https://accounts.google.com/o/saml2/idp?idpid=\u003cYOUR APP ID\u003e\"\n      entityId: \"https://login.example.com/\"\n      certs: |\n        -----BEGIN CERTIFICATE-----\n        ...\n        -----END CERTIFICATE-----\n      acsUrl: \"https://login.example.com/saml\"\n    ```\n\n*   **`ConfigPasskey` (Passkey):**\n    *   `name`: String. Internal name.\n    *   `identityProvider`: String. Name of another identity provider for initial authentication.\n    *   `refreshInterval`: Duration. Re-authentication interval.\n    *   `endpoint`: String. URL for passkey authentication.\n    *   `domain`: String. Domain for user identities.\n    *   `trustedIssuers`: List of `TrustedIssuer` objects. Defines external issuers whose tokens are accepted when using this provider.\n\n    **Example (Passkey with Google OpenID Connect for initial authentication):**\n\n    ```yaml\n    passkey:\n    - name: \"passkey\"\n      identityProvider: \"google\" # Name of the OIDC provider for initial authentication\n      endpoint: \"https://login.example.com/passkey\"\n      domain: \"example.com\"\n    ```\n\n### Group and Member Objects\n\nThe `groups` section in the configuration allows for the creation of user groups for access control. These groups can be used in `sso` and `clientAuth` rules.\n\n#### `Group` Object\n\n*   `name`: (Required) String. The name of the group.\n*   `members`: (Optional) List of `Member` objects.\n\n#### `Member` Object\n\nA member can be identified in one of three ways:\n*   `email`: String. The email address of the user. This is used for SSO authentication.\n*   `x509`: String. The X.509 subject of a client certificate. This is used for TLS client authentication.\n*   `group`: String. The name of another group. This allows for nested groups.\n\n**Example:**\n\n```yaml\ngroups:\n- name: admins\n  members:\n  - email: \"admin@example.com\"\n  - x509: \"SUBJECT:CN=admin\"\n- name: users\n  members:\n  - email: \"user1@example.com\"\n  - x509: \"SUBJECT:CN=user1\"\n  - group: \"admins\" # All admins are also users.\n\nbackends:\n- serverNames:\n  - \"sso.example.com\"\n  sso:\n    provider: \"my-sso-provider\"\n    rules:\n    - acl:\n      - \"users\" # Only members of the 'users' group can access.\n- serverNames:\n  - \"client-auth.example.com\"\n  clientAuth:\n    rootCAs:\n    - \"my-ca\"\n    acl:\n    - \"admins\" # Only members of the 'admins' group can access.\n```\n\n\n### PKI Configuration (`ConfigPKI`)\n\nDefines a local Certificate Authority:\n\n*   `name`: String. Name of the CA.\n*   `keyType`: String. Cryptographic key type (e.g., `ecdsa-p256`, `rsa-2048`).\n*   `issuingCertificateUrls`: List of strings. URLs for CA's X509 certificate.\n*   `crlDistributionPoints`: List of strings. URLs for Certificate Revocation List.\n*   `ocspServers`: List of strings. URLs for OCSP.\n*   `endpoint`: String. URL for certificate management.\n*   `admins`: List of strings. Users allowed to perform administrative tasks.\n\n### SSH Certificate Authority Configuration (`ConfigSSHCertificateAuthority`)\n\nDefines a local SSH Certificate Authority:\n\n*   `name`: String. Name of the CA.\n*   `keyType`: String. Cryptographic key type.\n*   `publicKeyEndpoint`: String. URL where CA's public key is published.\n*   `certificateEndpoint`: String. URL where certificates are issued.\n*   `maximumCertificateLifetime`: Duration. Maximum certificate lifetime.\n\n### Bandwidth Limit Configuration (`BWLimit`)\n\nDefines named bandwidth limits:\n\n*   `name`: String. Name of the group.\n*   `ingress`: Float. Ingress limit in bytes per second.\n*   `egress`: Float. Egress limit in bytes per second.\n\n### WebSocket Configuration (`WebSocketConfig`)\n\nDefines WebSocket endpoints:\n\n*   `endpoint`: String. WebSocket endpoint URL.\n*   `address`: String. Backend address for WebSocket connections.\n*   `scopes`: List of strings. Scopes for access control.\n\n### ECH Configuration (`ECH` Object)\n\nThe `ech` object configures Encrypted Client Hello (ECH). When enabled, `tlsproxy` acts as a Client-Facing Server for all backends.\n\n*   `publicName`: (Required) String. The public name of the ECH configuration.\n*   `interval`: (Optional) Duration. The time interval between key/config rotations.\n*   `endpoint`: (Optional) String. The local endpoint where `tlsproxy` will publish the current ECH ConfigList.\n*   `webhooks`: (Optional) List of strings. A list of webhook URLs to call when the ECH config is updated.\n*   `cloudflare`: (Optional) List of `Cloudflare` objects. Configures Cloudflare DNS records to update when the ECH ConfigList changes.\n\nSee the [GoDoc](https://pkg.go.dev/github.com/c2FmZQ/tlsproxy/proxy#ECH) for more details.\n\n**Example:**\n\n```yaml\nech:\n  publicName: \"www.example.com\"\n  interval: \"1h\"\n  endpoint: \"https://www.example.com/.well-known/ech-config\"\n```\n\n### ForwardECH Configuration (`BackendECH` Object)\n\nThe `forwardECH` object configures ECH for connections to backend servers.\n\n*   `echConfigList`: (Optional) String. A static, base64-encoded ECH Config list to use with the backend.\n*   `echPublicName`: (Optional) String. The public name of the backend server's ECH config.\n*   `requireECH`: (Optional) Boolean. If true, connections to the backend will not be attempted without an ECH Config List.\n\nSee the [GoDoc](https://pkg.go.dev/github.com/c2FmZQ/tlsproxy/proxy#BackendECH) for more details.\n\n**Example:**\n\n```yaml\nbackends:\n- serverNames:\n  - \"frontend.example.com\"\n  mode: \"https\"\n  addresses:\n  - \"backend.example.com:443\"\n  forwardECH:\n    echPublicName: \"backend.example.com\"\n    requireECH: true\n```\n\n## 4. Usage\n\nTo run TLSPROXY, use the `tlsproxy` executable with the `--config` flag pointing to your configuration file:\n\n```console\n./tlsproxy --config=config.yaml\n```\n\n**Command-line Flags:**\n\n*   `--config \u003cfile\u003e`: Specifies the path to the configuration YAML file.\n*   `--revoke-all-certificates \u003creason\u003e`: Revokes all cached certificates. `reason` can be `unspecified`, `keyCompromise`, `superseded`, or `cessationOfOperation`.\n*   `--passphrase \u003cpassphrase\u003e`: The passphrase to encrypt TLS keys on disk. Can also be set via `TLSPROXY_PASSPHRASE` environment variable.\n*   `--shutdown-grace-period \u003cduration\u003e`: Graceful shutdown period (e.g., `1m`, `30s`).\n*   `--use-ephemeral-certificate-manager`: (For testing) Uses an ephemeral certificate manager.\n*   `--stdout`: Logs output to STDOUT.\n*   `--quiet`: Suppresses logging after startup.\n*   `-v`: Shows the version information.\n\n## 5. Common Use Cases\n\nThis section provides practical examples for common TLSPROXY use cases.\n\n### 5.1. Basic HTTP/HTTPS Proxying\n\n#### 5.1.1. HTTP Mode (HTTPS to HTTP)\n\nIn this mode, TLSPROXY terminates HTTPS connections and forwards requests to a backend HTTP server. This is useful for adding TLS encryption to existing HTTP services without modifying the backend.\n\n```yaml\nbackends:\n- serverNames:\n  - www.example.com\n  mode: http\n  addresses:\n  - 192.168.1.1:80\n```\n\n#### 5.1.2. HTTPS Mode (HTTPS to HTTPS)\n\nThis mode is used when the backend server already supports HTTPS. TLSPROXY terminates the client-side HTTPS connection and establishes a new HTTPS connection to the backend.\n\n```yaml\nbackends:\n- serverNames:\n  - secure.example.com\n  mode: https\n  addresses:\n  - 192.168.1.2:443\n  # insecureSkipVerify: true # Use with caution, disables backend cert verification\n```\n\n### 5.2. TCP Proxying\n\n#### 5.2.1. TCP Mode (TLS to Plain TCP)\n\nTLSPROXY terminates TLS connections and forwards the decrypted data to a plain TCP backend. This is commonly used for services like IMAP, SMTP, or SSH that don't natively support TLS.\n\n```yaml\nbackends:\n- serverNames:\n  - mail.example.com\n  mode: tcp\n  addresses:\n  - 192.168.1.3:143 # IMAP\n```\n\n#### 5.2.2. TLSPASSTHROUGH Mode (TLS Passthrough)\n\nIn this mode, TLSPROXY acts as a simple TCP proxy, forwarding the raw TLS connection directly to the backend without decrypting it. The backend server must handle its own TLS termination.\n\n```yaml\nbackends:\n- serverNames:\n  - passthrough.example.com\n  mode: TLSPASSTHROUGH\n  addresses:\n  - 192.168.1.4:8443\n```\n\n### 5.3. SSH Proxying with `tlsclient`\n\nYou can use `tlsclient` to proxy SSH connections through TLSPROXY, allowing you to secure SSH traffic with TLS and leverage TLSPROXY's features like client authentication.\n\n**TLSPROXY Configuration (`config.yaml`):**\n\n```yaml\nbackends:\n- serverNames:\n  - ssh.example.com\n  mode: tcp\n  addresses:\n  - 192.168.1.5:22\n  alpnProtos:\n  - ssh\n```\n\n**SSH Client Configuration (`~/.ssh/config`):**\n\n```ssh-config\nHost ssh.example.com\n  ProxyCommand /path/to/tlsclient -alpn=ssh %h:443\n```\n\nThen, you can connect using `ssh user@ssh.example.com`.\n\n### 5.4. Setting up an SSH Certificate Authority (CA)\n\nTLSPROXY can act as an SSH Certificate Authority, issuing short-lived SSH user certificates. This is particularly useful in conjunction with SSO for managing access to SSH servers.\n\n```yaml\nsshCertificateAuthorities:\n- name: \"EXAMPLE SSH CA\"\n  # Optional: Publish the CA's public key.\n  publicKeyEndpoint:\n  - https://ssh.example.com/ca\n  # Users can request their own certificate.\n  certificateEndpoint: https://ssh.example.com/cert\n```\n\n### 5.5. Getting SSH Certificates\n\nOnce an SSH CA is configured in TLSPROXY, users can obtain SSH certificates through a web interface. Navigate to the `certificateEndpoint` (e.g., `https://ssh.example.com/cert`) in your browser. You will be prompted to enter your SSH public key, and TLSPROXY will issue a signed certificate if you are authorized.\n\nAlternatively, the [`examples/ssh/get-ssh-cert.sh`](./examples/ssh/get-ssh-cert.sh) script can be used to obtain a certificate from the command line.\n\n### 5.6. Setting up PKI (Public Key Infrastructure)\n\nTLSPROXY can also function as a general-purpose PKI, issuing X.509 certificates for clients and backend services.\n\n```yaml\npki:\n- name: \"EXAMPLE CA\"\n  # Optional: Publish the CA's certificate(s).\n  issuingCertificateUrls:\n  - https://pki.example.com/ca.pem\n  # Optional: Publish the CA's Revocation List.\n  crlDistributionPoints:\n  - https://pki.example.com/crl.pem\n  # Optional: Enable OCSP (Online Certificate Status Protocol).\n  ocspServers:\n  - https://pki.example.com/ocsp\n  # Users can manage their own certificates with this endpoint.\n  endpoint: https://pki-internal.example.com/certs\n  # Optional: Admins can revoke anybody's certificates.\n  admins:\n  - bob@example.com\n```\n\nThis example configures a local Certificate Authority (CA) named \"EXAMPLE CA\". This CA can be used to issue X.509 certificates for client and backend authentication within your environment.\n\nHere is a breakdown of the configuration:\n*   `issuingCertificateUrls`: Specifies the URL where the CA's public certificate is published. Relying parties can use this to verify certificates issued by this CA.\n*   `crlDistributionPoints`: Defines the URL for the Certificate Revocation List (CRL), allowing clients to check for revoked certificates.\n*   `ocspServers`: Provides the endpoint for the Online Certificate Status Protocol (OCSP), offering a real-time method for checking certificate validity.\n*   `endpoint`: Sets up a web interface at `https://pki-internal.example.com/certs` where authenticated users can request and manage their own certificates.\n*   `admins`: Grants administrative privileges to `bob@example.com`, allowing this user to perform actions like revoking any user's certificate.\n\nYou can then use this CA to enforce client certificate-based authorization for a backend. In the following example, only clients presenting a valid certificate issued by \"EXAMPLE CA\" for the identity `user@example.com` are allowed access.\n\n```yaml\nbackends:\n- serverNames:\n  - \"client-auth.example.com\"\n  mode: \"https\"\n  addresses:\n  - \"192.168.1.10:443\"\n  clientAuth:\n    rootCAs:\n    - \"EXAMPLE CA\"\n    acl:\n    - \"EMAIL:user@example.com\"\n```\n\n### 5.7. Serving Static Files\n\nTLSPROXY can serve static files directly from a local directory, acting as a simple web server.\n\n```yaml\nbackends:\n- serverNames:\n  - static.example.com\n  mode: local\n  documentRoot: /var/www/htdocs\n```\n\n### 5.8. QUIC/HTTP3 Proxying\n\nTLSPROXY supports proxying QUIC and HTTP/3 traffic. Ensure `enableQUIC` is set to `true` in your top-level configuration.\n\n```yaml\nbackends:\n- serverNames:\n  - quic.example.com\n  mode: QUIC\n  addresses:\n  - 192.168.1.6:4443\n```\n\n## 6. Advanced Topics\n\nFor more detailed information on specific features and advanced configurations, refer to the following documentation:\n\n*   [Hardware-backed keys (TPM)](https://github.com/c2FmZQ/tlsproxy/blob/main/docs/TPM.md)\n*   [QUIC/HTTP3](https://github.com/c2FmZQ/tlsproxy/blob/main/docs/QUIC.md)\n*   [Authentication Flows (OIDC, SAML, Passkeys)](https://github.com/c2FmZQ/tlsproxy/blob/main/docs/authentication.md)\n*   [PROXY Protocol](https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt)\n*   [GoDoc for proxy package](https://pkg.go.dev/github.com/c2FmZQ/tlsproxy/proxy#section-documentation)\n\n\n## 7. Support and Community\n\n*   **Report an issue:** If you find a bug or have a feature request, please open an issue on [GitHub Issues](https://github.com/c2FmZQ/tlsproxy/issues).\n*   **Ask a question:** For general questions and discussions, please use [GitHub Discussions](https://github.com/c2FmZQ/tlsproxy/discussions).\n*   **Report a security vulnerability:** If you discover a security vulnerability, please report it privately by following the instructions in [SECURITY.md](./SECURITY.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc2fmzq%2Ftlsproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fc2fmzq%2Ftlsproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc2fmzq%2Ftlsproxy/lists"}