Breaking

This update is not backwards-compatible with any previous version. It will modify the database under the hood
which makes it incompatible with any previous version. If you need to downgrade for whatever reason, you will
only be able to do this by applying a database backup from an older version.
Testing has been done and everything was fine in tests. However, if you are using Rauthy in production, I recommend
taking a database backup, since any version <= v0.19 will not be working with a v0.20+ database.

IMPORTANT Upgrade Notes

If you are upgrading from any earlier version, there is a manual action you need to perform, before you can
start v0.20.0. If this has not been done, it will simply panic early and not start up. Nothing will get damaged.

The internal encryption of certain values has been changed. Rauthy now uses cryptr to handle these things,
like mentioned below as well.

However, to make working with encryption keys easier and provide higher entropy, the format has changed.
You need to convert your currently used ENC_KEYS to the new format:

Option 1: Use cryptr CLI

1. Install cryptr - https://github.com/sebadob/cryptr

If you have Rust available on your system, just execute:

cargo install cryptr --features cli --locked

Otherwise, pre-built binaries do exist:

Linux: https://github.com/sebadob/cryptr/raw/main/out/cryptr_0.2.2

Windows: https://github.com/sebadob/cryptr/raw/main/out/cryptr_0.2.2.exe

2. Execute:

cryptr keys convert legacy-string

3. Paste your current ENC_KEYS into the command line.

For instance, if you have

ENC_KEYS="bVCyTsGaggVy5yqQ/S9n7oCen53xSJLzcsmfdnBDvNrqQ63r4 q6u26onRvXVG4427/3CEC8RJWBcMkrBMkRXgx65AmJsNTghSA"

in your config, paste

bVCyTsGaggVy5yqQ/S9n7oCen53xSJLzcsmfdnBDvNrqQ63r4 q6u26onRvXVG4427/3CEC8RJWBcMkrBMkRXgx65AmJsNTghSA

If you provide your ENC_KEYS via a Kubernetes secret, you need to do a base64 decode first.
For instance, if your secret looks something like this

ENC_KEYS: YlZDeVRzR2FnZ1Z5NXlxUS9TOW43b0NlbjUzeFNKTHpjc21mZG5CRHZOcnFRNjNyNCBxNnUyNm9uUnZYVkc0NDI3LzNDRUM4UkpXQmNNa3JCTWtSWGd4NjVBbUpzTlRnaFNB

Then decode via shell or any tool your like:

echo -n YlZDeVRzR2FnZ1Z5NXlxUS9TOW43b0NlbjUzeFNKTHpjc21mZG5CRHZOcnFRNjNyNCBxNnUyNm9uUnZYVkc0NDI3LzNDRUM4UkpXQmNNa3JCTWtSWGd4NjVBbUpzTlRnaFNB | base64 -d

... and paste the decoded value into cryptr

4. cryptr will output the correct format for either usage in config or as kubernetes secret again

5. Paste the new format into your Rauthy config / secret and restart.

Option 2: Manual

Rauthy expects the ENC_KEYS now base64 encoded, and instead of separated by whitespace it expects them to
be separated by \n instead.
If you don't want to use cryptr you need to convert your current keys manually.

For instance, if you have

ENC_KEYS="bVCyTsGaggVy5yqQ/S9n7oCen53xSJLzcsmfdnBDvNrqQ63r4 q6u26onRvXVG4427/3CEC8RJWBcMkrBMkRXgx65AmJsNTghSA"

in your config, you need to convert the enc key itself, the value after the /, to base64, and then separate
them with \n.

For instance, to convert bVCyTsGaggVy5yqQ/S9n7oCen53xSJLzcsmfdnBDvNrqQ63r4, split off the enc key part
S9n7oCen53xSJLzcsmfdnBDvNrqQ63r4 and encode it with base64:

echo -n 'S9n7oCen53xSJLzcsmfdnBDvNrqQ63r4' | base64

Then combine the result with the key id again to:

bVCyTsGaggVy5yqQ/UzluN29DZW41M3hTSkx6Y3NtZmRuQkR2TnJxUTYzcjQ=

Do this for every key you have. The ENC_KEYS should then look like this in the end:

ENC_KEYS="
bVCyTsGaggVy5yqQ/UzluN29DZW41M3hTSkx6Y3NtZmRuQkR2TnJxUTYzcjQ=
q6u26onRvXVG4427/M0NFQzhSSldCY01rckJNa1JYZ3g2NUFtSnNOVGdoU0E=
"

Important:
Make sure to not add any newline characters or spaces when copying values around when doing the bas64 encoding!

Encrypted SQLite backups to S3 storage

Rauthy can now push encrypted SQLite backups to a configured S3 bucket.
The local backups to data/backups/ do still exist. If configured, Rauthy will now push backups from SQLite
to an S3 storage and encrypt them on the fly. All this happens with the help of cryptr
which is a new crate of mine. Resource usage is minimal, even if the SQLite file would be multiple GB's big.
The whole operation is done with streaming.

Auto-Restore SQLite backups

Rauthy can now automatically restore SQLite backups either from a backup inside data/backups/ locally, or
fetch an encrypted backup from an S3 bucket. You only need to set the new RESTORE_BACKUP environment variable
at startup and Rauthy will do the rest. No manually copying files around.
For instance, a local backup can be restored with setting RESTORE_BACKUP=file:rauthy-backup-1703243039 and an
S3 backup with RESTORE_BACKUP=s3:rauthy-0.20.0-1703243039.cryptr.

Test S3 config at startup

To not show unexpected behavior at runtime, Rauthy will initialize and test a configured S3 connection
at startup. If anything is not configured correctly, it will panic early. This way, when Rauthy starts
and the tests are successful, you know it will be working during the backup process at night as well, and
it will not crash and throw errors all night long, if you just had a typo somewhere.

Migration to spow

The old (very naive) Proof-of-Work (PoW) mechanism for bot and spam protection has been migrated to make use
of the spow crate, which is another new project of mine.
With this implementation, the difficulty for PoW's a client must solve can be scaled up almost infinitely,
while the time is takes to verify a PoW on the server side will always be O(1), no matter hoch high the
difficulty was. spow uses a modified version of the popular Hashcat PoW algorithm, which is also being used
in the Bitcoin blockchain.

Separate users cache

A typical Rauthy deployment will have a finite amount of clients, roles, groups, scopes, and so on.
The only thing that might scale endlessly are the users. Because of this, the users are now being cached
inside their own separate cache, which can be configured and customized to fit the deployment's needs.
You can now set the upper limit and the lifespan for cached user's. This is one of the first upcoming
optimizations, since Rauthy gets closer to the first v1.0.0 release:

E-Mails as lowercase only

Up until now, it was possible to register the same E-Mail address multiple times with using uppercase characters.
E-Mail is case-insensitive by definition though. This version does a migration of all currently existing E-Mail addresses
in the database to lowercase only characters. From that point on, it will always convert any address to lowercase only
characters to avoid confusion and conflicts.
This means, if you currently have the same address in your database with different casing, you need to resolve this
issue manually. The migration function will throw an error in the console at startup, if it finds such a conflict.

# The max cache size for users. If you can afford it memory-wise, make it possible to fit
# all active users inside the cache.
# The cache size you provide here should roughly match the amount of users you want to be able
# to cache actively. Depending on your setup (WebIDs, custom attributes, ...), this number
# will be multiplied internally  by 3 or 4 to create multiple cache entries for each user.
# default: 100
CACHE_USERS_SIZE=100

# The lifespan of the users cache in seconds. Cache eviction on updates will be handled automatically.
# default: 28800
CACHE_USERS_LIFESPAN=28800

Additional claims available in ID tokens

The scope profile now additionally adds the following claims to the ID token (if they exist for the user):

• locale
• birthdate

The new scope address adds:

• address in JSON format

  The new scope phone adds:

• phone

Changes

• new POST /events API endpoint which serves archived events
  d5d4b01
• new admin UI section to fetch and filter archived events.
  ece73bb
• backend + frontend dependencies have been updated to the latest versions everywhere
• The internal encryption handling has been changed to a new project of mine called cryptr.
  This makes the whole value encryption way easier, more stable and future-proof, because values have their own
  tiny header data with the minimal amount of information needed. It not only simplifies encryption key rotations,
  but also even encryption algorithm encryptions really easy in the future.
  d6c224e
  c3df3ce
• Push encrypted SQLite backups to S3 storage
  fa0e496
• S3 connection and config test at startup
  701c785
• Auto-Restore SQLite backups either from file or S3
  65bbfea
• Migrate to spow
  ff579f6
• Pre-Compute CSP's for all HTML content at build-time and get rid of the per-request nonce computation
  8fd2c99
• noindex, nofollow globally via headers and meta tag -> Rauthy as an Auth provider should never be indexed
  38a2a52
• push users into their own, separate, configurable cache
  3137927
• Convert to lowercase E-Mail addresses, always, everywhere
  a137e96
  2467227
• add additional user values matching OIDC default claims
  fca0c13
• add address and phone default OIDC scopes and additional values for profile
  3d497a2

Bugfixes

• A visual bugfix appeared on Apple systems because of the slightly bigger font size. This made
  the live events look a bit ugly and characters jumping in a line where they should never end up.
  3b56b50
• An incorrect URL has been returned for the end_session_endpoint in the OIDC metadata
  3caabc9
• Make the ItemTiles UI componend used for roles, groups, and so on, wrap nicely on smaller screens
  6f83e4a
• Show the corresponding E-Mail address for UserPasswordReset and UserEmailChange events in the UI
  7dc4794

Images

Postgres

ghcr.io/sebadob/rauthy:0.20.0

SQLite

ghcr.io/sebadob/rauthy:0.20.0-lite