Upgrade guide
0.27.0
Breaking
Deprecated JWT endpoint
The /.pomerium/jwt endpoint is now deprecated and disabled by default. (To temporarily opt out of this deprecation, set the runtime flag pomerium_jwt_endpoint
to true. This flag will be removed in a future release.)
This endpoint was originally added for single-page web apps to get information about the currently signed-in user, but for this use case it is not necessary to receive this information as a signed JWT.
Furthermore, this endpoint is incompatible with the desired security properties for the Pomerium JWT. We intend for the Pomerium JWT to represent that a specific request to an upstream service was duly authorized by Pomerium. The JWTs issued by the /.pomerium/jwt endpoint do not satisfy this property.
There is a new /.pomerium/user endpoint to provide the same user data, but as a plaintext JSON response. If you are using the Pomerium JavaScript SDK, version 1.1.0 includes a new getBrowserUser()
method to replace the existing verifyBrowserUser()
method.
Upgrading Pomerium Zero deployments in Kubernetes
For Pomerium Zero deployments in Kubernetes, we updated the Kubernetes manifest to use a Deployment instead of a StatefulSet. Before you upgrade, you need to delete your existing StatefulSet with a command like:
kubectl delete statefulset/pomerium -n pomerium-zero
Once you’ve removed your StatefulSet, run the following command to update Pomerium in Kubernetes:
kubectl apply -k github.com/pomerium/pomerium/k8s/zero
0.26.0
Routes port matching
Pomerium’s route matching behavior has changed with regards to port numbers in incoming requests. Previously, when matching an incoming request against the defined routes, Pomerium would require that the request’s Host
(or :authority
) header match the route’s from
URL including any port number. This can cause problems in deployments with a NAT with port mapping in front of Pomerium.
As of v0.26, if a Pomerium route’s from
URL does not include an explicit port number, the matching behavior is more lenient: the route will match an incoming request with any port number. For example, take a route with the from
URL https://app.example.com
. Incoming requests with a host header of app.example.com
, app.example.com:443
, and app.example.com:1234
would all match this route.
However, if you specify a port number explicitly in the from
URL, then incoming requests must include the same port number in the host header in order to match that route.
You can temporarily revert this change in behavior by setting the runtime flag match_any_incoming_port
to false.
Host header rewrite behavior
Pomerium will now consistently rewrite the host header of an incoming request to match the host and port specified in the route to
URL. (Previously Pomerium would never include a port number even if specified, and Pomerium would not rewrite the host header for any to
URLs with a host of localhost
or an IP address.) The new behavior is intended to be more consistent and predictable.
Please set the Preserve Host Header option for any routes where Pomerium should not rewrite the host header.
Improved session refresh reliability
We’ve updated the way Pomerium refreshes OAuth access tokens in order to improve reliability. Previously, Pomerium could fall behind on access token refresh, leading to users being prompted to sign in again before their Pomerium session should have expired. This may result in a higher rate of requests to your configured identity provider.
If you suspect this is causing any problems for your deployment, you can temporarily revert to the previous implementation by setting the runtime flag legacy_identity_manager
to true.
Deprecations
Support for the deprecated client_ca
config file key (and CLIENT_CA
environment variable) is now removed. Please update any remaining usage to downstream_mtls.ca
or the DOWNSTREAM_MTLS_CA
environment variable. See https://www.pomerium.com/docs/reference/downstream-mtls-settings#ca for more information about this option.
0.25.0
Breaking
Base64-encoded Certificates
Previously, the certificates
key supported base64-encoded certificates as a value (this option was not documented). We've removed support for base64-encoded certificates for this setting and now require that you only use the certificate file location. To avoid incompatibilities between versions, please update these values accordingly.
Note: The certificates
key is distinct from the certificate
key. The certificate
key setting still supports base64-encoded certificates; the certificates
list does not.
Remove Debug Option
We've removed support for the Debug setting, which changed the format of logs from JSON to a pretty-print format. If you prefer to review logs in a pretty-print format, you can use a command-line processing tool like jq
.