Skip to main content
Version: vNext (upcoming release)

UDP over HTTP Support

Starting in v0.29, Pomerium can be used to protect UDP systems with the same consistent authorization policy. This is achieved by tunneling UDP over HTTP with the help of a client side command built into pomerium-cli.

Internally, Pomerium uses CONNECT-UDP to establish the UDP tunnel.

Configure UDP Routes​

UDP configuration is simple. Just specify the correct scheme and ports in your route to and from fields.

Example:

routes:
  - from: udp+https://time.corp.example.com:13
    to: udp://time.internal.example.com:13
    policy:
      - allow:
          or:
            - email:
                is: contractor@not-example.com
            - claim/groups: 'datascience@example.com'

When creating UDP routes, note the following:

  • When configuring a UDP route, any HTTP specific settings such as regex_rewrite_pattern or set_request_headers have no effect.
  • The port defined in from does not dictate what port the tunneled traffic uses. This will always be the port defined by address in your Pomerium configuration (443 by default). The port instead differentiates multiple routes to the same hostname for different services.

Connect to UDP Routes​

While HTTP routes can be consumed with just a normal browser, pomerium-cli or Pomerium Desktop must serve as a proxy for UDP routes.

To connect, you normally need just the external hostname and port of your UDP route:

$ pomerium-cli udp udp.localhost.pomerium.io:1234
2023/10/02 11:19:59 listening on 127.0.0.1:52046

By default, pomerium-cli will start a listener on loopback on a random port.

On first connection, you will be sent through a standard Pomerium HTTP authentication flow. After completing this, your UDP connection should be established!

Advanced capabilities​

Listen configuration​

You may specify an optional address and port for the udp command to listen on.

Client Certificates​

If Pomerium is configured to require client certificates, you will also need to provide a client certificate and private key when invoking the pomerium-cli command.

You can specify these either by using PEM files, or (new in v0.23.0) by searching for a certificate in the system trust store (on macOS and Windows only).

To specify a client certificate and key using PEM files:

pomerium-cli udp --client-cert cert.pem --client-key key.pem  route.corp.example.com:1234

To search for a client certificate in the system trust store:

pomerium-cli udp --client-cert-from-store route.corp.example.com:1234

This will search the Keychain (on macOS) or the Windows certificate store (on Windows) for a client certificate and private key, based on the trusted CA names advertised by Pomerium in the TLS handshake.

If you need to select between multiple matching client certificates, you can additionally filter based on the Distinguished Name of the certificate's Issuer and/or the certificate Subject.

For example, to filter for a certificate directly issued by a CA with the Common Name "My Trusted CA":

pomerium-cli udp --client-cert-from-store --client-cert-issuer "CN=My Trusted CA" route.corp.example.com:1234

Or, to filter for a certificate whose Subject contains the Organizational Unit Name "My Department":

pomerium-cli udp --client-cert-from-store --client-cert-subject "OU=My Department" route.corp.example.com:1234

See the reference page for more details about the certificate name filter syntax.