Upgrade guide
The release notes for each version list what changed and any steps an upgrade needs:
- Ory Polis open source: GitHub releases
- Ory Polis Enterprise License: Ory Polis OEL changelog, which also describes what stays compatible within a release line
Enterprise features need an Ory Polis Enterprise License image
Identity federation, branding, products, YugabyteDB, per-connection and additional ACS URLs for SAML connections, OpenTelemetry
traces and logs and FIPS 140-3 mode are available only in the Ory Polis Enterprise License images, polis-oel and
polis-oel-fips, which need no license key. Traces and logs are exported once an OTLP endpoint is set, and FIPS 140-3 mode is
active in polis-oel-fips only. Earlier open source and CSL images also ran these features when POLIS_LICENSE_KEY was set.
After the upgrade, those images don't include them:
- the Identity Federation API (
/api/v1/identity-federation, the Admin Portal's identity federation API) and the federation endpoints apps sign in through (/api/identity-federation/*,/api/federated-saml/sso, the IdP metadata) answer403, so sign-ins through Identity Federation apps stop working - the Admin Portal branding API and the product settings API answer
403, and the Admin Portal and setup pages use the default branding - creating or updating a SAML connection or a setup link with
acsUrlId,acsUrlHostoradditionalAcsUrlsanswers403, and so does a SAML response posted to/api/oauth/saml/<acsUrlId> - Polis and its migrations refuse to start with
DB_TYPE=yugabytedb - traces and logs are no longer exported, while metrics are
- Polis refuses to start in FIPS mode
Nothing is deleted. Identity Federation apps, branding and product settings stay in the database and work again with an Ory Polis Enterprise License image.
To keep using these features, switch to polis-oel, or polis-oel-fips for FIPS mode, instead of upgrading the open source or
CSL image. It runs against the same database with the same schema, so no migration is needed.
Polis no longer reads POLIS_LICENSE_KEY or BOXYHQ_LICENSE_KEY, and the Ory Polis Enterprise License Helm chart no longer has
polis.licenseKey. Remove them from your configuration; leaving them set does nothing. The npm library no longer takes the
polisLicenseKey option, so remove it from the options you pass, or the TypeScript build fails.
DynamoDB, MongoDB and Redis moved to driver packages
DB_ENGINE=dynamodb, DB_ENGINE=mongo and DB_ENGINE=redis are no longer accepted and Ory Polis refuses to start with them.
These databases are supported through the @boxyhq/polis-driver-dynamodb, @boxyhq/polis-driver-mongodb and
@boxyhq/polis-driver-redis packages, which are not part of the image: build an image that installs the package, then set
DB_ENGINE=custom and DB_DRIVER to the package name. The packages read and write the same data as the built-in drivers did, so
no data migration is needed. For DynamoDB, DB_DYNAMODB_REGION, DB_DYNAMODB_RCUS and DB_DYNAMODB_WCUS move to
DB_DRIVER_OPTIONS. External databases has the steps for each database, and the FIPS 140-3 image
loads no external drivers.
Exact SAML audience matching
Ory Polis accepts a SAML response only when its Audience is exactly one of the connection's two SP entity IDs:
- the SP entity ID: the connection's
samlAudienceOverrideif it has one, and otherwiseSAML_AUDIENCE(samlAudiencein the npm library) - the SP entity ID followed by
/and the tenant and product identifier, which the SSO connection setup page shows for IdPs that need a unique entity ID per app
Both keep working. Earlier releases also accepted any Audience that only started with the SP entity ID, such as
https://saml.boxyhq.com/ with a trailing slash, or the entity ID shown for a different tenant or product. A SAML connection
whose IdP sends such a value stops working after the upgrade, and SAML logins through it fail with Invalid audience.
The setup page builds the entity ID it shows from SAML_AUDIENCE, even for a connection with samlAudienceOverride. For such a
connection, the second SP entity ID is the override followed by the same / and identifier, so the value the setup page shows is
not accepted. Use the override, or replace SAML_AUDIENCE at the start of the value the setup page shows with the override.
To find affected connections before you upgrade, compare the Entity ID, Audience URI, or Audience Restriction in each customer's
SAML app with the connection's two SP entity IDs. It must be identical to one of them, including case and any trailing slash.
After you upgrade, failed logins appear under Enterprise SSO > SSO Traces in the Admin Portal with the error
Invalid audience.
To fix a connection, have the customer set the Entity ID in their SAML app to one of the two SP entity IDs exactly. If the IdP
can't be changed, set samlAudienceOverride on the connection to the value the IdP sends instead. Ory Polis then also uses that
value as the issuer of the SAML authentication requests it sends to that IdP.
The notes below cover upgrades between older versions and are kept for reference.
Upgrading to v1.44.0
The npm library imports jose and openid-client dynamically because both packages are ES modules. If you bundle your
server-side code (for example with Next.js), the bundler can leave them out. To keep them, add dummy imports of jose and
openid-client to your code and, for Next.js, list them in outputFileTracingIncludes. Later releases import both packages
statically, so the workaround is no longer needed there.
Upgrading to v1.25.0
The namespace column length has been increased to 256 characters to support larger values.
This change affects all the instances with sql as the db engine. If you are not running manual migration then the namespace
column will be dropped and populated again. It is highly advisable to back up your data before upgrading.
Upgrading to v1.21.0
Google DSync Connections will be supported on the back of following changes related to Authorization. These will ease the process of surfacing up the OAuth endpoints for Google SCIM.
- Removed
DSYNC_GOOGLE_REDIRECT_URI,GOOGLE_REDIRECT_URIenv vars for Ory Polis service. - Removed
dsync.providers.google.callbackUrlfrom npm. - Ory Polis npm will take in new options -
dsync.providers.google.authorizePathanddsync.providers.google.callbackPath. These will be used alongsideexternalUrlto construct the full path
Upgrading to v1.14.0
We have changed the schema bit to introduce a new column called namespace to speed up scans. You will have to run the migration
scripts if you are manually managing migrations. For example PlanetScale where auto migrations are not supported due to a
difference between MySQL and PlanetScale.
Upgrading to v1.11.0
We have patched the SSO connection (/api/v1/connections, now /api/v1/sso) DELETE handler to accept payload (client/Secret or
tenant/product/strategy) as part of query parameters. Earlier, the payload was expected to be part of the body which is
non-standard and is no longer supported in Next.js.
Upgrading to v1.9.7
We discovered and fixed a database connection leak introduced in v1.9.1, if you are using versions 1.9.1 to 1.9.6 then please upgrade to v1.9.7
Upgrading to v1.8.0
- We support bringing your own database (BYOD), this is a very tricky feature to support and we are still iterating on the schema which works as seamlessly as possible across the range of databases we support. Unfortunately, not everything goes smoothly here and we have encountered some length issues on newer versions of MySQL and MariaDB. The best way forward was to change the schema of the keys we use from length 1500 to 250 which is compatible with the newer versions. As a result, this will break your updates if you are using MySQL, MariaDB, or MS SQL Server. If you encounter this please reach out and we'll guide you through the update process. If you haven't gone into production yet then please update to v1.8.0 before you deploy it to production.
Upgrading to v1.3.10
- For users of the Ory Polis npm library,
directorySynchas been renamed todirectorySyncController.
Upgrading to v1.3.6
samlSPConfig.get()is now async since we introduced a global certificate instead of per tenant certificate to ease the SAML setup process.
Upgrading to v1.3.0
- Landed support for OpenID Identity Providers.
- Landed new API (
/api/v1/connections, now/api/v1/sso) to support setting up both SAML/OIDC SSO Connections.
Note: The previous API for SAML configuration,
/api/v1/saml/config, was deprecated in this release and has since been removed. Use/api/v1/ssoinstead.
- Renamed env variable
PRE_LOADED_CONFIGtoPRE_LOADED_CONNECTIONfor Ory Polis service. In the case of npmpreLoadedConfigbecomespreLoadedConnection. - Make sure to set the value for
oidcPathin case you are using the npm.
Backups
Please remember to take backups before upgrading Ory Polis. We cannot stress how important this step is, although we take precautions to avoid bugs they sometimes do slip by us. Having backups will not only help you recover from these rare events but should be part of your disaster recovery process. If you need any help with this please do not hesitate to reach out to us.
