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 formatThe 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
andphone
default OIDC scopes and additional values forprofile
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
andUserEmailChange
events in the UI
7dc4794
Images
Postgres
ghcr.io/sebadob/rauthy:0.20.0
SQLite
ghcr.io/sebadob/rauthy:0.20.0-lite