v0.3.1

• Dependencies were upgraded. Notably, this should fixed the unhelpful error messages when the SMTP connection fails due to TLS errors, for example.

• This release adds experimental JSON responses for /auth and /confirm, when requested with Accept: application/json, allowing a Relying Party to proxy these requests and implement custom UI for part of the authentication flow. (Notably, the email contents and redirect_uri may still present broker UI.) Note that this feature is currently undocumented.

v0.3.0

Breaking changes

• Email address normalization has changed slightly. This can affect your users! (See the below section for details.)
• The scope query parameter must now contain at least openid.
• The JWT email_verified claim is now a boolean. (Used to be incorrectly set to a copy of the email address.)
• TOML configuration has been ‘flattened’, and environment configuration has changed slightly to match. Existing configuration will continue to work, but the broker will log deprecation warnings. (See the below section for details.)

New features

• In addition to the existing Redis support, this release adds an SQLite storage backend option.
• It is now possible to automate key rotation. This is now the default if neither keytext nor keyfiles are specified. (See the below section on how to migrate from manual keys to rotating keys.)
• Ed25519 can optionally be enabled, which is implemented using a non-standard OpenID Connect extension. (Currently undocumented.)

Email normalisation changes

Previously, the broker allowed an Identity Provider (IdP) to perform additional normalization on the email address. This turned out to be confusing as well as problematic if an IdP changed its implementation, causing user logins to suddenly become invalid.

Portier now disallows any additional normalization performed by IdPs, and instead only applies the basic steps outlined in our email address normalization specification. The outcome of these steps is always consistent, regardless of IdP changes.

As a result of these changes, user identifiers may change when the broker is upgraded. This especially affects users of GMail with dots in their email addresses. As an example, a user who logs in as John.Doe@gmail.com would previously be assigned an identifier johndoe@gmail.com, but will now be assigned john.doe@gmail.com.

Configuration format changes

The changes in configuration documented here are implemented with backwards compatibility. Existing configuration will continue to work, but the broker will log deprecation warnings.

TOML configuration files have been ‘flattened’. To migrate existing configuration:

• Remove all section headers, except domain_overrides
• Rename smtp : {server,username,password} → smtp_{server,username,password}
• Rename redis : url → redis_url
• Rename limit : per_email → limit_per_email
• Rename google : client_id → google_client_id

The following environment variables have also been renamed:

• BROKER_IP → BROKER_LISTEN_IP
• BROKER_PORT → BROKER_LISTEN_PORT

For general documentation on the configuration format, see the configuration template.

Migrating to automatic key rotation

The broker can now automatically rotate keys. Manual key management is still supported, but automatic rotation will be the default configuration going forward.

If desired, you can switch from manual key management to rotating keys by performing the following steps:

• Stop the broker process, or otherwise suspend access to the broker. (For example, on Heroku use: heroku maintenance:on)
• Replace your broker binaries with the new version.
• Perform any desired configuration changes for the new version.
  • See the section on ‘configuration format changes’ above.
  • If you’d like to use SQLite instead of Redis, this may be a good moment switch.
• Remove any of the following from configuration, but make sure to keep your current PEM private key around for the migration:
  • keytext in TOML config
  • keyfiles in TOML config
  • BROKER_KEYTEXT environment variable
  • BROKER_KEYFILES environment variable
• Use the broker --import-key flag to load a PEM private key into storage. For example:
  • If using TOML config: portier-broker ./config.toml --import-key ./private-key.pem
  • If using only environment variables: portier-broker --import-key ./private-key.pem
  • The imported key will continue to be used for another day from the time of import, before it is rotated. (Or whatever duration keys_ttl is set to.)
• Restart the broker process and resume access to the broker.

As a side note, the exact order of applying the configuration change to your broker is not very important. When using Redis storage, active workers will immediately pick up on key changes performed by --import-keys. When using SQLite storage, simply ensure the broker process is (re)started at some point after --import-keys.

The most important detail above is that access to the broker is suspended during the migration, to prevent clients from accidentally caching a wrong set of keys that happened to be active during the migration.

v0.2.0

Initial prototype of custom Identity Providers, including discovery using WebFinger.

v0.1.0

Initial prototype release, containing authentication with an email loop or through Google.