DOCSEARCHbyAlgolia
Submit Docs

Pomerium Documentation

website·Indexed 35 days ago

https://www.pomerium.com/docs/

Documentation for Pomerium, a zero-trust access solution. Covers Pomerium Core (self-managed) and Pomerium Zero (managed), including authentication via Identity Providers (IdP), Single Sign-On (SSO), and the Pomerium Policy Language (PPL). Includes detailed guides on Model Context Protocol (MCP) support for securing AI agents, native SSH access, non-HTTP protocol tunneling, and configuration for routes, timeouts, and identity headers.

Tokens
36.3K
Snippets
181
Records
277
Agent score
72%

What's inside Pomerium

  1. Overview of Pomerium Native SSH Access

    Pomerium acts as a native SSH reverse proxy that adds OAuth authentication and policy enforcement to standard SSH connections. It is protocol-aware, meaning it does not require custom clients, tunnels, or specialized server software. SSH traffic flows through the Pomerium data plane on a configurable port, separate from HTTP traffic. When a user connects, Pomerium validates their identity via an IdP, evaluates policies, and generates a short-lived SSH certificate to authenticate the user to the upstream server.

  2. Overview of MCP App Architecture

    MCP Apps use the @modelcontextprotocol/ext-apps SDK to render interactive UI components (widgets) inside MCP hosts like ChatGPT, Claude, VS Code, and Goose. The architecture consists of two main components:

    1. MCP Server: Handles tool execution and returns structured data. It must be reachable via a public URL and is typically auth-gated (requiring a Bearer token for tool calls).
    2. Widget Assets: React-based UI components rendered in a sandboxed iframe by the host. These must be publicly accessible because MCP hosts cannot forward authentication credentials to the iframe.

  3. Overview of Pomerium Policy Language (PPL)

    Pomerium Policy Language (PPL) is a YAML-based declarative notation used to create fine-grained authorization policies for routes. A policy consists of rules that determine whether to allow or deny access based on specific conditions.

    Key evaluation logic:

    • deny always takes precedence over allow.
    • Access is granted if at least one allow rule matches AND no deny rules match.

  4. Overview of MCP Upstream OAuth

    Upstream OAuth in Pomerium allows MCP clients to interact with servers that require third-party authentication (e.g., Notion, Linear, Google) without the client ever seeing upstream credentials. Pomerium handles the OAuth flow and proxies requests to the MCP server with a valid upstream access token in the Authorization: Bearer header.

    Clients hold a Pomerium-issued External Token (TE), while Pomerium manages the Internal Token (TI) used for the upstream provider.

  5. Use Pomerium as a Secure MCP Gateway

    Pomerium acts as a secure gateway for Model Context Protocol (MCP) servers. By placing an internal MCP server behind Pomerium, external clients (such as Claude, ChatGPT, or VS Code) can access the server securely. Pomerium manages TLS termination, authentication, and authorization, allowing the internal server to remain isolated from the public internet and focus solely on business logic.

  6. Implement Zero Trust with Pomerium

    Pomerium implements a Zero Trust security model, which assumes the network perimeter is compromised. Instead of relying on a firewall, it protects every connection on a per-request basis by continuously verifying identity, device posture, and context before granting access.

  7. Understand Pomerium's continuous request validation

    Pomerium implements a zero-trust security model where every single request is re-validated. This validation is based on three primary factors: user identity, device posture, and other contextual factors. This continuous re-checking ensures that resources remain protected even if the network perimeter has been compromised.

  8. Secure non-HTTP protocols using Pomerium tunneling

    Pomerium allows you to secure and authenticate TCP- and UDP-based services by tunneling them over HTTP. This enables the use of an identity provider to control access to services that do not natively support HTTP authentication. Common use cases include administrative connections (SSH, RDP), data services (Redis, MySQL, Postgres), and UDP-based protocols (e.g., time servers, game servers).

  9. Understand Pomerium's Authentication (AuthN) and Authorization (AuthZ) flow

    Pomerium separates identity verification from permission enforcement:

    • Authentication (AuthN): Confirms the user's or device's identity. Pomerium delegates this to external Identity Providers (IdPs) like Google or Okta, which issue a JSON Web Token (JWT).
    • Authorization (AuthZ): Determines if the authenticated user has permission to access a specific resource. Pomerium compares the claims within the JWT against policies defined using the Pomerium Policy Language (PPL).

  10. Install Pomerium Core via standalone binary

    Pomerium Core can be installed by downloading the official tarball for the target operating system and architecture from GitHub Releases. Once extracted, the pomerium binary can be executed with a configuration file.
    ARCH=[amd64 or arm64]
OS=[linux or darwin]
VERSION=[desired version]
curl -L https://github.com/pomerium/pomerium/releases/download/${VERSION}/pomerium-${OS}-${ARCH}.tar.gz | tar -z -x

./pomerium -config config.yaml

  11. Use Pomerium for Kubernetes API Server Access

    Pomerium can act as a proxy for requests to the Kubernetes API server, allowing any supported IdP to be used for authentication regardless of the environment. This provides centralized access policy, consistent group membership support, and a global audit trail without requiring a VPN.

  12. Understand Pomerium Multi-Cluster Architecture

    Pomerium supports a multi-cluster architecture to ensure redundancy and independent scaling. In this setup, a Load Balancer distributes incoming client traffic across multiple independent Pomerium clusters. Each cluster is self-contained, consisting of its own Proxy, Authorize, Authenticate, and Databroker services, as well as its own dedicated Postgres instance (typically configured with a Master and Replica for data durability).