New

• authenticate: session expiry now matches identity provider's @desimone (#416)

v0.5.1

Fixed

• Fixes forward-auth configurations for nginx and traefik.

v0.5.0

Lots of great stuff in this release, but be sure to follow the upgrade guide at the end of this document as there are several breaking changes!

New

• Session state is now route-scoped. Each managed route uses a transparent, signed JSON Web Token (JWT) to assert identity.
• Managed routes no longer need to be under the same subdomain! Access can be delegated to any route, on any domain.
• Programmatic access now also uses JWT tokens. Access tokens are now generated via a standard oauth2 token flow, and credentials can be refreshed for as long as is permitted by the underlying identity provider.
• User dashboard now pulls in additional user context fields (where supported) like the profile picture, first and last name, and so on.

Security

• Some identity providers (Okta, Onelogin, and Azure) previously used mutable signifiers to set and assert group membership. Group membership for all providers now use globally unique and immutable identifiers when available.

Changed

• Azure AD identity provider now uses globally unique and immutable ID for group membership.
• Okta no longer uses tokens to retrieve group membership. Group membership is now fetched using Okta's HTTP API. Group membership is now determined by the globally unique and immutable ID field.
• Okta now requires an additional set of credentials to be used to query for group membership set as a service account.
• URLs are no longer validated to be on the same domain-tree as the authenticate service. Managed routes can live on any domain.
• OneLogin no longer uses tokens to retrieve group membership. Group membership is now fetched using OneLogin's HTTP API. Group membership is now determined by the globally unique and immutable ID field.

Removed

• Force refresh has been removed from the dashboard.
• Previous programmatic authentication endpoints (/api/v1/token) has been removed and is no longer supported.

Upgrade Guide

Breaking

Subdomain requirement dropped

• Pomerium services and managed routes are no longer required to be on the same domain-tree root. Access can be delegated to any route, on any domain (that you have access to, of course).

Azure AD

• Azure Active Directory now uses the globally unique and immutableID instead of group name to attest a user's group membership. Please update your policies to use group ID instead of group name.

Okta

• Okta no longer uses tokens to retrieve group membership. Group membership is now fetched using Okta's API.
• Okta's group membership is now determined by the globally unique and immutable ID field. Please update your policies to use group ID instead of group name.
• Okta now requires an additional set of credentials to be used to query for group membership set as a service account.

OneLogin

• OneLogin group membership is now determined by the globally unique and immutable ID field. Please update your policies to use group ID instead of group name.

Force Refresh Removed

Force refresh has been removed from the dashboard. Logging out and back in again should have the equivalent desired effect.

Programmatic Access API changed

Previous programmatic authentication endpoints (/api/v1/token) has been removed and has been replaced by a per-route, oauth2 based auth flow. Please see updated programmatic documentation how to use the new programmatic access api.

Forward-auth route change

Previously, routes were verified by taking the downstream applications hostname in the form of a path (e.g. ${fwdauth}/.pomerium/verify/httpbin.some.example) variable. The new method for verifying a route using forward authentication is to pass the entire requested url in the form of a query string (e.g. ${fwdauth}/.pomerium/verify?url=https://httpbin.some.example) where the routed domain is the value of the uri key.

Note that the verification URL is no longer nested under the .pomerium endpoint.

For example, in nginx this would look like:

-    nginx.ingress.kubernetes.io/auth-url: https://fwdauth.corp.example.com/.pomerium/verify/httpbin.corp.example.com?no_redirect=true
-    nginx.ingress.kubernetes.io/auth-signin: https://fwdauth.corp.example.com/.pomerium/verify/httpbin.corp.example.com
+    nginx.ingress.kubernetes.io/auth-url: https://fwdauth.corp.example.com/verify?uri=$scheme://$host$request_uri
+    nginx.ingress.kubernetes.io/auth-signin: https://fwdauth.corp.example.com?uri=$scheme://$host$request_uri

v0.4.2

Security

• Fixes vulnerabilities fixed in 1.13.2 including CVE-2019-17596.

v0.4.1

UPGRADING FROM 0.4.0

Breaking

Previously, routes were verified by taking the downstream applications hostname in the form of a path (e.g. ${fwdauth}/.pomerium/verify/httpbin.some.example) variable. The new method for verifying a route using forward authentication is to pass the entire requested url in the form of a query string (e.g. ${fwdauth}/.pomerium/verify?url=https://httpbin.some.example) where the routed domain is the value of the uri key.

Note that the verification URL is no longer nested under the .pomerium endpoint.

For example, in nginx this would look like:

-    nginx.ingress.kubernetes.io/auth-url: https://fwdauth.corp.example.com/.pomerium/verify/httpbin.corp.example.com?no_redirect=true
-    nginx.ingress.kubernetes.io/auth-signin: https://fwdauth.corp.example.com/.pomerium/verify/httpbin.corp.example.com
+    nginx.ingress.kubernetes.io/auth-url: https://fwdauth.corp.example.com/verify?uri=$scheme://$host$request_uri
+    nginx.ingress.kubernetes.io/auth-signin: https://fwdauth.corp.example.com?uri=$scheme://$host$request_uri

Fixed

• Fixed an issue where requests handled by forward-auth would not be redirected back to the underlying route after successful authentication and authorization. [GH-363]
• Fixed an issue where requests handled by forward-auth would add an extraneous query-param following sign-in causing issues in some configurations. [GH-366]

Upgrade Guide

Since 0.3.0

Breaking

Removed Authenticate Internal URL

The authenticate service no longer uses gRPC to do back channel communication. As a result, AUTHENTICATE_INTERNAL_URL/authenticate_internal_url is no longer required.

No default certificate location

In previous versions, if no explicit certificate pair (in base64 or file form) was set, Pomerium would make a last ditch effort to check for certificate files (cert.key/privkey.pem) in the root directory. With the introduction of insecure server configuration, we've removed that functionality. If there settings for certificates and insecure server mode are unset, pomerium will give a appropriate error instead of a failed to find/open certificate error.

Authorize service health-check is non-http

The Authorize service will no longer respond to HTTP-based healthcheck queries when run as a distinct service (vs all-in-one). As an alternative, you can used on TCP based checks. For example, if using Kubernetes:

---
readinessProbe:
  tcpSocket:
    port: 443
  initialDelaySeconds: 5
  periodSeconds: 10
livenessProbe:
  tcpSocket:
    port: 443
  initialDelaySeconds: 15
  periodSeconds: 20

Non-breaking changes

All-in-one

If service mode (SERVICES/services) is set to all, gRPC communication with the authorize service will by default occur over localhost, on port :5443.

Changes

New

• Allow setting request headers on a per route basis in policy. [GH-308]
• Support "forward-auth" integration with third-party ingresses and proxies. nginx, nginx-ingress, and Traefik are currently supported. [GH-324]
• Add insecure transport / TLS termination support. [GH-328]
• Add setting to override a route's TLS Server Name. [GH-297]
• Pomerium's session can now be passed as a bearer-auth header or query string in addition to as a session cookie.
• Add host to the main request logger middleware. [GH-308]
• Add AWS cognito identity provider settings. [GH-314]

Security

• The user's original intended location before completing the authentication process is now encrypted and kept confidential from the identity provider. [GH-316]
• Under certain circumstances, where debug logging was enabled, pomerium's shared secret could be leaked to http access logs as a query param. [GH-338]

Fixed

• Fixed an issue where CSRF would fail if multiple tabs were open. [GH-306]
• Fixed an issue where pomerium would clean double slashes from paths. [GH-262]
• Fixed a bug where the impersonate form would persist an empty string for groups value if none set. [GH-303]
• Fixed HTTP redirect server which was not redirecting the correct hostname.

Changed

• The healthcheck endpoints (/ping) now returns the http status 405 StatusMethodNotAllowed for non-GET requests.
• Authenticate service no longer uses gRPC.
• The global request logger now captures the full array of proxies from X-Forwarded-For, in addition to just the client IP.
• Options code refactored to eliminate global Viper state. [GH-332]
• Pomerium will no longer default to looking for certificates in the root directory. [GH-328]
• Pomerium will validate that either insecure_server, or a valid certificate bundle is set. [GH-328]

Removed

• Removed AUTHENTICATE_INTERNAL_URL/authenticate_internal_url which is no longer used.

Security

• Fixes vulnerabilities fixed in Go 1.13.1 including CVE-2019-16276.

v0.3.0

New

• GRPC Improvements. [GH-261] / [GH-69]

  • Enable WaitForReady to allow background retries through transient failures
  • Expose a configurable timeout for backend requests to Authorize and Authenticate
  • Enable DNS round_robin load balancing to Authorize and Authenticate services by default

• Add ability to set client certificates for downstream connections. [GH-259]

Fixed

• Fixed non-amd64 based docker images.[GH-284]
• Fixed an issue where stripped cookie headers would result in a cookie full of semi-colons (Cookie: ;;;). [GH-285]
• HTTP status codes now better adhere to RFC7235. In particular, authentication failures reply with 401 Unauthorized while authorization failures reply with 403 Forbidden. [GH-272]

Changed

• Pomerium will now strip _csrf cookies in addition to session cookies. [GG-285]

• Disabled gRPC service config. [GH-280]

• A policy's custom certificate authority can set as a file or a base64 encoded blob(tls_custom_ca/tls_custom_ca_file). [GH-259]

• Remove references to service named ports and instead use their numeric equivalent. [GH-266]

v0.2.1

SECURITY

• Fixes vulnerabilities fixed in Go 1.12.8 including CVE-2019-9512, CVE-2019-9514 and CVE-2019-14809.

New

Telemetry [GH-35]

• Tracing [GH-230] aka distributed tracing, provides insight into the full lifecycles, aka traces, of requests to the system, allowing you to pinpoint failures and performance issues.

  • Add Jaeger support. [GH-230]

• Metrics provide quantitative information about processes running inside the system, including counters, gauges, and histograms.

  • Add informational metrics. [GH-227]

  • GRPC Metrics Implementation. [GH-218]

    • Additional GRPC server metrics and request sizes
    • Improved GRPC metrics implementation internals
    • The GRPC method label is now 'grpc_method' and GRPC status is now grpc_client_status and grpc_server_status

  • HTTP Metrics Implementation. [GH-220]

    • Support HTTP request sizes on client and server side of proxy
    • Improved HTTP metrics implementation internals
    • The HTTP method label is now http_method, and HTTP status label is now http_status

Changed

• GRPC version upgraded to v1.22 [GH-219]
• Add support for large cookie sessions by chunking. [GH-211]
• Prefer curve X25519 to P256 for TLS connections. [GH-233]
• Pomerium and its services will gracefully shutdown on interrupt signal. [GH-230]
• Google now prompts the user to select a user account (by adding select_account to the sign in url). This allows a user who has multiple accounts at the authorization server to select amongst the multiple accounts that they may have current sessions for.

FIXED

• Fixed potential race condition when signing requests. [GH-240]

PLEASE REVIEW THE UPGRADE GUIDE BEFORE UPDATING!

v0.1.0

NEW

• Add programmatic authentication support. [GH-177]
• Add Prometheus format metrics endpoint. [GH-35]
• Add policy setting to enable self-signed certificate support. [GH-179]
• Add policy setting to skip tls certificate verification. [GH-179]

CHANGED

• Policy to and from settings must be set to valid HTTP URLs including schemes and hostnames (e.g. http.corp.domain.example should now be https://http.corp.domain.example).
• Proxy's sign out handler {}/.pomerium/sign_out now accepts an optional redirect_uri parameter which can be used to specify a custom redirect page, so long as it is under the same top-level domain. [GH-183]
• Policy configuration can now be empty at startup. [GH-190]
• Websocket support is now set per-route instead of globally. [GH-204]
• Pomerium will error if a session cookie is over 4096 bytes, instead of failing silently. [GH-212]

FIXED

• Fixed HEADERS environment variable parsing. [GH-188]
• Fixed Azure group lookups. [GH-190]
• If a session is too large (over 4096 bytes) Pomerium will no longer fail silently. [GH-211]
• Internal URLs like dashboard now start auth process to login a user if no session is found. [GH-205].
• When set,CookieDomain lets a user set the scope of the user session. CSRF cookies will still always be scoped at the individual route level. [GH-181]

PLEASE REVIEW THE UPGRADE GUIDE BEFORE UPDATING!

v0.0.5

NEW

• Add ability to detect changes and reload policy configuration files. [GH-150]
• Add user dashboard containing information about the current user's session. [GH-123]
• Add functionality allowing users to initiate manual refresh of their session. This is helpful when a user's access control details are updated but their session hasn't updated yet. To prevent abuse, manual refresh is gated by a cooldown (REFRESH_COOLDOWN) which defaults to five minutes. [GH-73]
• Add Administrator (super user) account support (ADMINISTRATORS). [GH-110]
• Add feature that allows Administrators to impersonate / sign-in as another user from the user dashboard. [GH-110]
• Add docker images and builds for ARM. [GH-95]
• Add support for public, unauthenticated routes. [GH-129]

CHANGED

• Add Request ID to error pages. [GH-144]
• Refactor configuration handling to use spf13/viper bringing a variety of additional supported storage formats.[GH-115]
• Changed config AUTHENTICATE_INTERNAL_URL to be a URL containing both a valid hostname and schema. [GH-153]
• User state is now maintained and scoped at the domain level vs at the route level. [GH-128]
• Error pages contain a link to sign out from the current user session. [GH-100]
• Removed LifetimeDeadline from sessions.SessionState.
• Removed favicon specific request handling. [GH-131]
• Headers are now configurable via the HEADERS configuration variable. [GH-108]
• Refactored proxy and authenticate services to share the same session state cookie. [GH-131]
• Removed instances of extraneous session state saves. [GH-131]
• Changed default behavior when no session is found. Users are now redirected to login instead of being shown an error page.[GH-131]
• Updated routes such that all http handlers are now wrapped with a standard set of middleware. Headers, request id, loggers, and health checks middleware are now applied to all routes including 4xx and 5xx responses. [GH-116]
• Changed docker images to be built from distroless. This fixed an issue with nsswitch [GH-97], includes ca-certificates and limits the attack surface area of our images. [GH-101]
• Changed HTTP to HTTPS redirect server to be user configurable via HTTP_REDIRECT_ADDR. [GH-103]
• Content-Security-Policy hash updated to match new UI assets.

FIXED

• Fixed websocket support. [GH-151]
• Fixed an issue where policy and routes were being pre-processed incorrectly. [GH-132]
• Fixed an issue where golint was not being found in our docker image. [GH-121]

Since 0.0.4

This page contains the list of deprecations and important or breaking changes for pomerium v0.0.4 compared to v0.0.5. Please read it carefully.

Breaking: POLICY_FILE removed

Usage of the POLICY_FILE envvar is no longer supported. Support for file based policy configuration has been shifted into the new unified config file.

Important: Configuration file support added

• Pomerium now supports an optional -config flag. This flag specifies a file from which to read all configuration options. It supports yaml, json, toml and properties formats.

• All options which can be specified via MY_SETTING style envvars can now be specified within your configuration file as key/value. The key is generally the same as the envvar name, but lower cased. See Reference Documentation for exact names.

• Options precedence is environmental variables > configuration file > defaults

• The options file supports a policy key, which contains policy in the same format as POLICY_FILE. To convert an existing policy.yaml into a config.yaml, just move your policy under a policy key.

  Old:

  - from: httpbin.corp.beyondperimeter.com
    to: http://httpbin
    allowed_domains:
      - pomerium.io
    cors_allow_preflight: true
    timeout: 30s
  

  New:

  policy:
    - from: httpbin.corp.beyondperimeter.com
      to: http://httpbin
      allowed_domains:
        - pomerium.io
      cors_allow_preflight: true
      timeout: 30s
  

Authenticate Internal Service Address

The configuration variable Authenticate Internal Service URL must now be a valid URL type and contain both a hostname and valid https schema.

v0.0.4

CHANGED

• HTTP Strict Transport Security is included by default and set to one year. [GH-92]
• HTTP now redirects to HTTPS. [GH-92]
• Removed extraneous AUTHORIZE_INTERNAL_URL config option since authorization has no publica http handlers, only a gRPC service endpoint. [GH-93]
• Removed PROXY_ROOT_DOMAIN config option which is now inferred from AUTHENTICATE_SERVICE_URL. Only callback requests originating from a URL on the same sub-domain are permitted. [GH-83]
• Removed REDIRECT_URL config option which is now inferred from AUTHENTICATE_SERVICE_URL (e.g. https://$AUTHENTICATE_SERVICE_URL/oauth2/callback). [GH-83]

FIXED

• Fixed a bug in the Google provider implementation where the refresh_token. Updated the google implementation to use the new prompt=consent oauth2 parameters. Reported and fixed by @chemhack [GH-81]

DOCUMENTATION

• Added synology tutorial. [GH-96]
• Added certificates documentation. [GH-79]

FEATURES:

• Authorization : The authorization module adds support for per-route access policy. In this release we support the most common forms of identity based access policy: allowed_users, allowed_groups, and allowed_domains. In future versions, the authorization module will also support context and device based authorization policy and decisions. See website documentation for more details.

• Group Support : The authenticate service now retrieves a user's group membership information during authentication and refresh. This change may require additional identity provider configuration; all of which are described in the updated docs. A brief summary of the requirements for each IdP are as follows:

  • Google requires the Admin SDK to enabled, a service account with properly delegated access, and IDP_SERVICE_ACCOUNT to be set to the base64 encoded value of the service account's key file.
  • Okta requires a groups claim to be added to both the id_token and access_token. No additional API calls are made.
  • Microsoft Azure Active Directory requires the application be given an additional API permission, Directory.Read.All.
  • Onelogin requires the groups was supplied during authentication and that groups parameter has been mapped. Group membership is validated on refresh with the user-info api endpoint.

• WebSocket Support : With Go 1.12 pomerium automatically proxies WebSocket requests.

CHANGED:

• Add LOG_LEVEL config setting that allows for setting the desired minimum log level for an event to be logged. [GH-74]
• Changed POMERIUM_DEBUG config setting to just do console-pretty printing. No longer sets log level. [GH-74]
• Updated generate_wildcard_cert.sh to generate a elliptic curve 256 cert by default.
• Updated env.example to include a POLICY setting example.
• Added IDP_SERVICE_ACCOUNT to env.example .
• Removed PROXY_ROOT_DOMAIN settings which has been replaced by POLICY.
• Removed ALLOWED_DOMAINS settings which has been replaced by POLICY. Authorization is now handled by the authorization service and is defined in the policy configuration files.
• Removed ROUTES settings which has been replaced by POLICY.
• Add refresh endpoint ${url}/.pomerium/refresh which forces a token refresh and responds with the json result.
• Group membership added to proxy headers (x-pomerium-authenticated-user-groups) and (x-pomerium-jwt-assertion).
• Default Cookie lifetime (COOKIE_EXPIRE) changed from 7 days to 14 hours ~ roughly one business day.
• Moved identity (authenticate/providers) into its own internal identity package as third party identity providers are going to authorization details (group membership, user role, etc) in addition to just authentication attributes.
• Removed circuit breaker package. Calls that were previously wrapped with a circuit breaker fall under gRPC timeouts; which are gated by relatively short timeouts.
• Session expiration times are truncated at the second.
• Removed gitlab provider. We can't support groups until this gitlab bug is fixed.
• Request context is now maintained throughout request-flow via the context package enabling timeouts, request tracing, and cancellation.

FIXED:

• http.Server and httputil.NewSingleHostReverseProxy now uses pomerium's logging package instead of the standard library's built in one. [GH-58]