README
¶
Pomerium builds secure, clientless connections to internal web apps and services without a corporate VPN.
Pomerium is:
- Easier because you don’t have to maintain a client or software.
- Faster because it’s deployed directly where your apps and services are. No more expensive data backhauling.
- Safer because every single action is verified for trusted identity, device, and context.
It’s not a VPN alternative – it’s the trusted, foolproof way to protect your business.
Docs
For comprehensive docs, and tutorials see our documentation.
Integration Tests
To run the integration tests locally, first build a local development image:
./scripts/build-dev-docker.bash
Next go to the integration/clusters folder and pick a cluster, for example google-single, then use docker-compose to start the cluster. We use an environment variable to specify the dev docker image we built earlier:
cd integration/clusters/google-single
env POMERIUM_TAG=dev docker-compose up -V
Once that's up and running you can run the integration tests from another terminal:
go test -count=1 -v ./integration/...
If you need to make a change to the clusters themselves, there's a tpl folder that contains jsonnet files. Make a change and then rebuild the clusters by running:
go run ./integration/cmd/pomerium-integration-tests/ generate-configuration
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package authenticate is a pomerium service that handles user authentication and refersh (AuthN).
|
Package authenticate is a pomerium service that handles user authentication and refersh (AuthN). |
|
events
Package events defines authentication flow event types.
|
Package events defines authentication flow event types. |
|
Package authorize is a pomerium service that is responsible for determining if a given request should be authorized (AuthZ).
|
Package authorize is a pomerium service that is responsible for determining if a given request should be authorized (AuthZ). |
|
evaluator
Package evaluator contains rego evaluators for evaluating authorize policy.
|
Package evaluator contains rego evaluators for evaluating authorize policy. |
|
evaluator/opa
Package opa implements the policy evaluator interface to make authorization decisions.
|
Package opa implements the policy evaluator interface to make authorization decisions. |
|
internal/store
Package store contains a datastore for authorization policy evaluation.
|
Package store contains a datastore for authorization policy evaluation. |
|
cmd
|
|
|
pomerium
Package main contains pomerium
|
Package main contains pomerium |
|
Package config is a configuration abstraction that facilitates enabling Pomerium settings forvarious encoding types (JSON/YAML/ENVARS) and methods.
|
Package config is a configuration abstraction that facilitates enabling Pomerium settings forvarious encoding types (JSON/YAML/ENVARS) and methods. |
|
envoyconfig
Package envoyconfig contains a Builder for building Envoy configuration from Pomerium configuration.
|
Package envoyconfig contains a Builder for building Envoy configuration from Pomerium configuration. |
|
envoyconfig/filemgr
Package filemgr defines a Manager for managing files for the controlplane.
|
Package filemgr defines a Manager for managing files for the controlplane. |
|
Package databroker is a pomerium service that handles the storage of user session state.
|
Package databroker is a pomerium service that handles the storage of user session state. |
|
examples
|
|
|
cmd/pomerium-integration-tests
Package main contains the pomerium integration tests
|
Package main contains the pomerium integration tests |
|
flows
Package flows has helper functions for working with pomerium end-user use-case flows.
|
Package flows has helper functions for working with pomerium end-user use-case flows. |
|
forms
Package forms has helper functions for working with HTML forms.
|
Package forms has helper functions for working with HTML forms. |
|
backends/httpdetails
Module
|
|
|
backends/ws-echo
Module
|
|
|
internal
|
|
|
atomicutil
Package atomicutil contains functions for working with the atomic package.
|
Package atomicutil contains functions for working with the atomic package. |
|
authenticateflow
Package authenticateflow implements the core authentication flow.
|
Package authenticateflow implements the core authentication flow. |
|
autocert
Package autocert implements automatic management of TLS certificates.
|
Package autocert implements automatic management of TLS certificates. |
|
chanutil
Package chanutil implements methods for working with channels.
|
Package chanutil implements methods for working with channels. |
|
contextkeys
Package contextkeys defines common context keys shared between packages
|
Package contextkeys defines common context keys shared between packages |
|
controlplane
Package controlplane contains the HTTP and gRPC base servers and the xDS gRPC implementation for envoy.
|
Package controlplane contains the HTTP and gRPC base servers and the xDS gRPC implementation for envoy. |
|
controlplane/xdsmgr
Package xdsmgr implements a resource discovery manager for envoy.
|
Package xdsmgr implements a resource discovery manager for envoy. |
|
databroker
Package databroker contains a data broker implementation.
|
Package databroker contains a data broker implementation. |
|
deterministicecdsa
Package deterministicecdsa contains the original ecdsa.GenerateKey before it was made non-deterministic.
|
Package deterministicecdsa contains the original ecdsa.GenerateKey before it was made non-deterministic. |
|
encoding
Package encoding defines interfaces shared by other packages that convert data to and from byte-level and textual representations.
|
Package encoding defines interfaces shared by other packages that convert data to and from byte-level and textual representations. |
|
encoding/jws
Package jws represents content secured with digitalsignatures using JSON-based data structures as specified by rfc7515
|
Package jws represents content secured with digitalsignatures using JSON-based data structures as specified by rfc7515 |
|
encoding/mock
Package mock implements a mock implementation of MarshalUnmarshaler.
|
Package mock implements a mock implementation of MarshalUnmarshaler. |
|
errgrouputil
Package errgrouputil contains methods for working with errgroup code.
|
Package errgrouputil contains methods for working with errgroup code. |
|
events
Package events contains a manager for dispatching and receiving arbitrary events.
|
Package events contains a manager for dispatching and receiving arbitrary events. |
|
fileutil
Package fileutil provides file utility functions, complementing the lower level abstractions found in the standard library.
|
Package fileutil provides file utility functions, complementing the lower level abstractions found in the standard library. |
|
handlers
Package handlers contains HTTP handlers used by Pomerium.
|
Package handlers contains HTTP handlers used by Pomerium. |
|
handlers/webauthn
Package webauthn contains handlers for the WebAuthn flow in authenticate.
|
Package webauthn contains handlers for the WebAuthn flow in authenticate. |
|
hashutil
Package hashutil provides NON-CRYPTOGRAPHIC utility functions for hashing.
|
Package hashutil provides NON-CRYPTOGRAPHIC utility functions for hashing. |
|
httputil
Package httputil provides HTTP utility functions, complementing the more common ones in the net/http package
|
Package httputil provides HTTP utility functions, complementing the more common ones in the net/http package |
|
httputil/reproxy
Package reproxy contains a handler for re-proxying traffic through the http controlplane.
|
Package reproxy contains a handler for re-proxying traffic through the http controlplane. |
|
identity
Package identity provides support for making OpenID Connect (OIDC) and OAuth2 authenticated HTTP requests with third party identity providers.
|
Package identity provides support for making OpenID Connect (OIDC) and OAuth2 authenticated HTTP requests with third party identity providers. |
|
identity/identity
Package identity is a package to avoid a dependency cycle.
|
Package identity is a package to avoid a dependency cycle. |
|
identity/manager
Package manager contains an identity manager responsible for refreshing sessions and creating users.
|
Package manager contains an identity manager responsible for refreshing sessions and creating users. |
|
identity/oauth
Package oauth provides support for making OAuth2 authorized and authenticated HTTP requests, as specified in RFC 6749.
|
Package oauth provides support for making OAuth2 authorized and authenticated HTTP requests, as specified in RFC 6749. |
|
identity/oauth/apple
Package apple implements OpenID Connect for apple
|
Package apple implements OpenID Connect for apple |
|
identity/oauth/github
Package github implements OAuth2 based authentication for github
|
Package github implements OAuth2 based authentication for github |
|
identity/oidc
Package oidc implements a generic OpenID Connect provider.
|
Package oidc implements a generic OpenID Connect provider. |
|
identity/oidc/auth0
Package auth0 implements OpenID Connect for auth0
|
Package auth0 implements OpenID Connect for auth0 |
|
identity/oidc/azure
Package azure implements OpenID Connect for Microsoft Azure
|
Package azure implements OpenID Connect for Microsoft Azure |
|
identity/oidc/cognito
Package cognito provides support for AWS Cognito
|
Package cognito provides support for AWS Cognito |
|
identity/oidc/gitlab
Package gitlab implements OpenID Connect for Gitlab
|
Package gitlab implements OpenID Connect for Gitlab |
|
identity/oidc/google
Package google implements OpenID Connect for Google and GSuite.
|
Package google implements OpenID Connect for Google and GSuite. |
|
identity/oidc/okta
Package okta implements OpenID Connect for okta
|
Package okta implements OpenID Connect for okta |
|
identity/oidc/onelogin
Package onelogin implements OpenID Connect for OneLogin
|
Package onelogin implements OpenID Connect for OneLogin |
|
identity/oidc/ping
Package ping implements OpenID Connect for Ping
|
Package ping implements OpenID Connect for Ping |
|
log
Package log provides a global logger for zerolog.
|
Package log provides a global logger for zerolog. |
|
middleware
Package middleware provides a standard set of middleware for pomerium.
|
Package middleware provides a standard set of middleware for pomerium. |
|
middleware/responsewriter
Package responsewriter contains helper functions that useful for hooking into various parts of a response.
|
Package responsewriter contains helper functions that useful for hooking into various parts of a response. |
|
registry
Package registry implements a service registry server.
|
Package registry implements a service registry server. |
|
registry/inmemory
Package inmemory implements an in-memory registry.
|
Package inmemory implements an in-memory registry. |
|
retry
Package retry provides a retry loop with exponential back-off while watching arbitrary signal channels for side effects.
|
Package retry provides a retry loop with exponential back-off while watching arbitrary signal channels for side effects. |
|
scheduler
Package scheduler contains a priority queue based on time.
|
Package scheduler contains a priority queue based on time. |
|
sessions
Package sessions handles the storage, management, and validation of pomerium user sessions.
|
Package sessions handles the storage, management, and validation of pomerium user sessions. |
|
sessions/cookie
Package cookie provides a cookie based implementation of session store and loader.
|
Package cookie provides a cookie based implementation of session store and loader. |
|
sessions/header
Package header provides a request header based implementation of a session loader.
|
Package header provides a request header based implementation of a session loader. |
|
sessions/mock
Package mock provides a mock implementation of session store and loader.
|
Package mock provides a mock implementation of session store and loader. |
|
sessions/queryparam
Package queryparam provides a query param based implementation of a both as session store and loader.
|
Package queryparam provides a query param based implementation of a both as session store and loader. |
|
sets
Package sets contains set data structures.
|
Package sets contains set data structures. |
|
signal
Package signal provides mechanism for notifying multiple listeners when something happened.
|
Package signal provides mechanism for notifying multiple listeners when something happened. |
|
syncutil
Package syncutil contains methods for working with sync code.
|
Package syncutil contains methods for working with sync code. |
|
telemetry
Package telemetry contains metrics and tracing constructs
|
Package telemetry contains metrics and tracing constructs |
|
telemetry/metrics
Package metrics contains support for OpenCensus distributed metrics.
|
Package metrics contains support for OpenCensus distributed metrics. |
|
telemetry/requestid
Package requestid has functions for working with x-request-id in http/gRPC requests.
|
Package requestid has functions for working with x-request-id in http/gRPC requests. |
|
telemetry/trace
Package trace contains support for OpenCensus distributed tracing.
|
Package trace contains support for OpenCensus distributed tracing. |
|
tests/xdserr
Package xdserr to load test configuration updates
|
Package xdserr to load test configuration updates |
|
tests/xdserr/cmd
Package main contains the xdserr cmd
|
Package main contains the xdserr cmd |
|
testutil
Package testutil contains helper functions for unit tests.
|
Package testutil contains helper functions for unit tests. |
|
tripper
Package tripper provides utility functions for working with the http.RoundTripper interface.
|
Package tripper provides utility functions for working with the http.RoundTripper interface. |
|
urlutil
Package urlutil provides utility functions for working with go urls.
|
Package urlutil provides utility functions for working with go urls. |
|
version
Package version enables setting build-time version using ldflags.
|
Package version enables setting build-time version using ldflags. |
|
zero/analytics
Package analytics collects active user metrics and reports them to the cloud dashboard
|
Package analytics collects active user metrics and reports them to the cloud dashboard |
|
zero/api
Package zero contains the pomerium zero configuration API client
|
Package zero contains the pomerium zero configuration API client |
|
zero/apierror
Package apierror provides a consistent way to handle errors from API calls
|
Package apierror provides a consistent way to handle errors from API calls |
|
zero/bootstrap
Package bootstrap fetches the very initial configuration for Pomerium Core to start.
|
Package bootstrap fetches the very initial configuration for Pomerium Core to start. |
|
zero/cmd
Package cmd implements the pomerium zero command.
|
Package cmd implements the pomerium zero command. |
|
zero/connect-mux
Package mux provides the way to listen for updates from the cloud
|
Package mux provides the way to listen for updates from the cloud |
|
zero/controller
Package controller implements Pomerium managed mode
|
Package controller implements Pomerium managed mode |
|
zero/grpcconn
Package grpcconn provides a gRPC client with authentication
|
Package grpcconn provides a gRPC client with authentication |
|
zero/leaser
Package leaser groups all Zero services that should run within a lease.
|
Package leaser groups all Zero services that should run within a lease. |
|
zero/reconciler
Package reconciler syncs the state of resource bundles between the cloud and the databroker.
|
Package reconciler syncs the state of resource bundles between the cloud and the databroker. |
|
zero/reporter
Package reporter periodically submits metrics back to the cloud.
|
Package reporter periodically submits metrics back to the cloud. |
|
zero/token
Package token provides a thread-safe cache of a authorization token that may be used across http and grpc clients
|
Package token provides a thread-safe cache of a authorization token that may be used across http and grpc clients |
|
pkg
|
|
|
cmd/pomerium
Package pomerium houses the main pomerium CLI command.
|
Package pomerium houses the main pomerium CLI command. |
|
contextutil
Package contextutil contains functions for working with contexts.
|
Package contextutil contains functions for working with contexts. |
|
counter
Package counter implements linear counter estimator
|
Package counter implements linear counter estimator |
|
cryptutil
Package cryptutil provides cryptographic utility functions, complementing the lower level abstractions found in the standard library.
|
Package cryptutil provides cryptographic utility functions, complementing the lower level abstractions found in the standard library. |
|
derivecert
Package derivecert is used to deterministically generate TLS certificate authority and certificates out of pre-shared key
|
Package derivecert is used to deterministically generate TLS certificate authority and certificates out of pre-shared key |
|
derivecert/config
Package config implements derived certs in the Pomerium Configuration
|
Package config implements derived certs in the Pomerium Configuration |
|
encoding/base58
Package base58 provides an API for working with modified base58 and Base58Check encodings.
|
Package base58 provides an API for working with modified base58 and Base58Check encodings. |
|
envoy
Package envoy creates and configures an envoy server.
|
Package envoy creates and configures an envoy server. |
|
envoy/files
Package files contains files for use with envoy.
|
Package files contains files for use with envoy. |
|
fanout
Package fanout implements a fan-out pattern that allows publishing messages to multiple subscribers
|
Package fanout implements a fan-out pattern that allows publishing messages to multiple subscribers |
|
grpc
Package grpc provides gRPC utility functions, complementing the more common ones in the github.com/grpc/grpc-go package
|
Package grpc provides gRPC utility functions, complementing the more common ones in the github.com/grpc/grpc-go package |
|
grpc/config
Package config contains protobuf definitions for config.
|
Package config contains protobuf definitions for config. |
|
grpc/crypt
Package crypt contains cryptographic protobuf messages.
|
Package crypt contains cryptographic protobuf messages. |
|
grpc/databroker
Package databroker contains databroker protobuf definitions.
|
Package databroker contains databroker protobuf definitions. |
|
grpc/databroker/mock_databroker
Package mock_databroker is a generated GoMock package.
|
Package mock_databroker is a generated GoMock package. |
|
grpc/device
Package device contains protobuf types for devices.
|
Package device contains protobuf types for devices. |
|
grpc/identity
Package identity contains protobuf types for identity management.
|
Package identity contains protobuf types for identity management. |
|
grpc/session
Package session contains protobuf types for sessions.
|
Package session contains protobuf types for sessions. |
|
grpc/user
Package user contains protobuf types for users.
|
Package user contains protobuf types for users. |
|
grpcutil
Package grpcutil contains functions for interacting with gRPC.
|
Package grpcutil contains functions for interacting with gRPC. |
|
hpke
Package hpke contains functions for working with Hybrid Public Key Encryption.
|
Package hpke contains functions for working with Hybrid Public Key Encryption. |
|
hpke/handlers
Package handlers provides http handlers for HPKE.
|
Package handlers provides http handlers for HPKE. |
|
httputil
Package httputil contains additional functionality for working with http.
|
Package httputil contains additional functionality for working with http. |
|
logutil
Package logutil contains functionality for working with logs.
|
Package logutil contains functionality for working with logs. |
|
metrics
Package metrics declares metrics names and labels that pomerium exposes as constants that could be referred to from other projects
|
Package metrics declares metrics names and labels that pomerium exposes as constants that could be referred to from other projects |
|
netutil
Package netutil contains various functions that help with networking.
|
Package netutil contains various functions that help with networking. |
|
policy
Package policy contains an implementation of the Pomerium Policy Language.
|
Package policy contains an implementation of the Pomerium Policy Language. |
|
policy/criteria
Package criteria contains all the pre-defined criteria as well as a registry to add new criteria.
|
Package criteria contains all the pre-defined criteria as well as a registry to add new criteria. |
|
policy/generator
Package generator converts Pomerium Policy Language into Rego.
|
Package generator converts Pomerium Policy Language into Rego. |
|
policy/parser
Package parser contains a parser for Pomerium Policy Language.
|
Package parser contains a parser for Pomerium Policy Language. |
|
policy/rules
Package rules contains useful pre-defined rego AST rules.
|
Package rules contains useful pre-defined rego AST rules. |
|
protoutil
Package protoutil contains functions for working with protobuf types.
|
Package protoutil contains functions for working with protobuf types. |
|
slices
Package slices contains functions for working with slices.
|
Package slices contains functions for working with slices. |
|
storage
Package storage provide generic interface to interact with storage backend.
|
Package storage provide generic interface to interact with storage backend. |
|
storage/inmemory
Package inmemory contains an in-memory implementation of the databroker backend.
|
Package inmemory contains an in-memory implementation of the databroker backend. |
|
storage/postgres
Package postgres contains an implementation of the storage.Backend backed by postgres.
|
Package postgres contains an implementation of the storage.Backend backed by postgres. |
|
storage/storagetest
Package storagetest contains test cases for use in verifying the behavior of a storage.Backend implementation.
|
Package storagetest contains test cases for use in verifying the behavior of a storage.Backend implementation. |
|
webauthnutil
Package webauthnutil contains types and functions for working with the webauthn package.
|
Package webauthnutil contains types and functions for working with the webauthn package. |
|
zero/cluster
Package cluster provides primitives to interact with the openapi HTTP API.
|
Package cluster provides primitives to interact with the openapi HTTP API. |
|
zero/connect
Package connect provides the way to listen for updates from the cloud
|
Package connect provides the way to listen for updates from the cloud |
|
Package proxy is a pomerium service that provides reverse proxying of internal routes.
|
Package proxy is a pomerium service that provides reverse proxying of internal routes. |
|
Package ui contains the user info dashboard ui.
|
Package ui contains the user info dashboard ui. |
Click to show internal directories.
Click to hide internal directories.