Introduction
There has not been any third party security audit for this project.
Use this software at your own risk!
This project is currently pre v1.0, which means, even though it is not expected, breaking changes might come with new versions.
What it is
Rauthy is an OpenID Connect (OIDC) Provider and Single Sign-On solution written in Rust.
Secure by default
It tries to be as secure as possible by default while still providing all the options needed to be compatible with
older systems. For instance, if you create a new OIDC client, it activates ed25519
as the default algorithm for
token signing and S256 PKCE flow. This will not work with old clients, which do not support it, but you can of course
deactivate this to your liking.
MFA and Passwordless Login
- Option: Password + Security Key (without User Verification):
Rauthy provides FIDO 2 / Webauthn login flows. If you once logged in on a new client with your username + password, you will get an encrypted cookie which will allow you to log in without a password from that moment on. You only need to have a FIDO compliant Passkey being registered for your account. - Option: Passkey-Only Accounts:
Since v0.16, Rauthy supports Passkey-Only-Accounts. You basically just provide your E-Mail address and log in with your FIDO 2 Passkey. Your account will not even have / need a password. This login flow is restricted though to only those passkeys, that can provide User Verification (UV) to always have at least 2FA security.
Fast and efficient
The main goal was to provide an SSO solution like Keycloak and others while using a way lower footprint
and being more efficient with resources. For instance, Rauthy can easily run a fully blown SSO provider on just a
Raspberry Pi. It makes extensive use of caching to be as fast as possible in cases where your database is further
away or just a bit slower, because it is maybe running on an SBC from an SD card. Most things are even cached
for several hours (config options will come in the future) and special care has been taken into account in case of cache
eviction and invalidation.
A Rauthy deployment with the embedded SQLite, filled caches and a small set of clients and users configured typically
only uses between 17 and 22 MB of memory! This is pretty awesome when comparing it to other existing solutions
out there. If a password from a login is hashed, the memory consumption will of course go up way higher than this
depending on your configured Argon2ID parameters, which you got fully under control. If you use it with an external
Postgres, the memory consumption of Rauthy itself will even be a bit lower, since it does not need to care about SQLite.
For achieving this speed and efficiency, some additional design tradeoffs werde made. For instance, some things you
configure statically via config file and not dynamically via UI, while most of them are configured once and then never
touched again.
Highly Available
Even though it makes extensive use of caching, you can run it in HA mode. It uses its own embedded distributed HA cache
called redhac, which cares about cache eviction on remote hosts.
You can choose between a SQLite for single instance deployments and a Postgres, if you need HA. MySQL support might
come in the future.
Nice UI
Unlike many other options, rauthy
does have a nice Admin UI which can be used to basically do almost any operation you
might need to administrate the whole application and its users. Some Screenshots and further introduction will follow
in the future.
Client Branding
You have a simple way to create some kind of branding or stylized look for the Login page for each client.
The whole color theme can be changed and each client can have its own custom logo.
Additionally, if you modify the branding for the default rauthy
client, it will not only change the look for the Login
page, but also for the Account and Admin page.
Events and Auditing
Since v0.17, Rauthy implements an Event-System. Events are generated in all kinds of scenarios. They can be sent via
E-Mail, Matrix or Slack, depending on the severity and the configured level. You will see them in the Admin UI in real
time, or you can subscribe to the events stream and externally handle them depending on your own business logic.
Brute-Force and basic DoS protection
Rauthy has brute force and basic DoS protection for the login endpoint. Your timeout will be artificially delayed after
enough invalid logins. It does auto-balacklist IP's that exceeded too many invalid logins, with automatic
expiry of the blacklisting. You can, if you like, manually blacklist certain IP's as well via the Admin UI.
Already in production
Rauthy is already being used in production, and it works with all typical OIDC clients (so far). It was just not an
open source project for quite some time.
Keycloak was a rough inspiration in certain places and if something is working with Keycloak, it does with rauthy
too
(again, so far).
Features List
- Fully working OIDC provider
- SQLite or Postgres as database
- Fast and efficient with minimal footprint
- Highly configurable
- Secure default values
- True passwordless accounts with E-Mail + Magic Link + Passkey
- Account conversions between traditional password and Passkey only
- Supports DPoP tokens for decentralized login flows
- Supports ephemeral, dynamic clients for decentralized login flows
-
Can serve a basic
webid
document for decentralized logins - OpenID Connect Dynamic Client Registration
- Upstream Authentication Providers (Login with ...)
- OAuth 2.0 Device Authorization Grant flow
- Admin UI
- Account UI for each user with self-service
- Simple per client branding for the login page
- All End-User facing sites support i18n server-side translation
- Custom roles
- Custom groups
- Custom scopes
- Custom user attributes
- User attribute binding to custom scopes
- Configurable password policy
-
Dedicated
forward_auth
endpoint, in addition to the existing userinfo, with support for configurable trusted auth headers - Admin API Keys with fine-grained access rights
- Events and alerting system
- Optional event notifications via: E-Mail, Matrix, Slack
- Configurable E-Mail templates for NewPassword + ResetPassword events
- Optional event persistence
- Admin UI component for archived / persisted events
- Optional Force MFA for the Admin UI
- Optional Force MFA for each individual client
- Additional encryption inside the database for the most critical entries
- Automatic database backups with configurable retention and auto-cleanup (SQLite only)
- auto-encrypted backups (SQLite)
- pushing SQLite backups to S3 storage
- auto-restore SQLite backups from file and s3
- High-Availability
- HA cache layer with its own (optional) mTLS connection
- Username enumeration prevention
- Login / Password hashing rate limiting
- Session client peer IP binding
- IP blacklisting feature
- Auto-IP blacklisting for login endpoints
- Argon2ID with config helper UI utility
- Housekeeping schedulers and cron jobs
- JSON Web Key Set (JWKS) autorotation feature
- Optional open user registration
- Optional user registration domain restriction
- App version update checker
-
Prometheus
/metrics
endpoint on separate port - SwaggerUI documentation
- No-Setup migrations between different databases (Yes, even between SQLite and Postgres)
Getting Started
Rauthy v0.14
and beyond uses differnt container images for the different target databases.
Until and including v0.13
, rauthy used the Any
driver from sqlx. However, this
driver has quite a few problems since sqlx 0.7, and I decided to migrate away from it, because the future of it seems
too uncertain to me.
- The "normal" container images can be used for Postgres
- The
*-lite
images use an embedded SQLite - The
DB_MIGRATE_FROM
(explained later) can be used with any combination of image / database
At the time of writing, you can run Rauthy either with Docker or inside Kubernetes.
All the examples in this documentation are using the *-lite
images and therefore SQLite. If you want to use Postgres
in production, you need to use the "default" container images.
Docker
Testing / Local Evaluation
For getting a first look at Rauthy, you can start it with docker (or any other container runtime) on your localhost.
The image contains a basic default config which is sufficient for local testing. Rauthy has pretty strict cookie
settings and not all browsers treat localhost
as being secure, therefore you should allow insecure cookies for
testing locally:
docker run --rm \
-e COOKIE_MODE=danger-insecure \
-p 8080:8080 \
--name rauthy \
ghcr.io/sebadob/rauthy:0.23.1-lite
This will start the container in interactive mode with an in-memory SQLite database. Just take a look at the log at the logs to see the URL and first password.
If you want to test a bit more in depth, you can change to an on-disk database easily:
docker run -d \
-e COOKIE_MODE=danger-insecure \
-e DATABASE_URL=sqlite:data/rauthy.db \
-p 8080:8080 \
--name rauthy \
ghcr.io/sebadob/rauthy:0.23.1-lite
The second command does not start in interactive mode and it does not delete the container on exit.
This means the data will be persisted, as long as the container itself is no erased and you can shutdown and
restart to your liking without using test data.
To see the logs and the new admin password, take a look with
docker logs -f rauthy
To delete the container, if you do not need it anymore, execute
docker stop rauthy && docker rm rauthy
To proceed, go to First Start
Production Setup
For going to production or to test more in-depth, you need to apply a config that matches your environment.
The first thing you might want to do is to add a volume mount for the database.
The second thing is to provide a more custom config.
Rauthy can either be configured via environment variables only, or you can provide a config file.
You can add environment variables to the startup command with the -e
option, like shown in the on-disk SQLite
command.
A better approach, when you have a bigger config file, would be to have all of them in a config file.
The following commands will work on Linux and Mac OS (even though not tested on Mac OS). If you are on Windows,
you might replace the pwd
command and just paste in the path directly. Since I am no Windows user myself, I
cannot provide tested commands in this case.
1. We want to create a new directory for rauthy's persistent data
mkdir rauthy
2. Add the new config file.
This documentation is in an early version and remote links are not available yet, they will be added at a later
point. For now, create a new file and paste the reference config
vim rauthy/rauthy.cfg
3. Create a sub-directory for the Database files
mkdir rauthy/data
The rauthy container by default runs everything with user:group 10001:10001 for security reasons.
To make this work with the default values, you have 2 options:
- Change the access rights:
chmod 0640 rauthy/rauthy.cfg
chmod 0700 -R rauthy/data
sudo chown -R 10001:10001 rauthy
- The other solution, if you do not have sudo rights, would be to change the owner of the whole directory.
chmod a+w rauthy/data
This will make the directory writeable for everyone, so rauthy can create the database files inside the container with 10001:10001 again.
The safest approach would be to change the owner and group for these files on the host system. This needs sudo
to edit the config, which may be a bit annoying, but at the same time it makes sure, that you can only read
the secrets inside it with sudo
too.
4. Adopt the config to your liking.
Make sure to adjust the volume mount for the sqlite directory in step 5, if it differs from sqlite:data/rauthy.db
5. Start the container with volume mounts
docker run -d \
-v $(pwd)/rauthy/rauthy.cfg:/app/rauthy.cfg \
-v $(pwd)/rauthy/data:/app/data \
-p 8080:8080 \
--name rauthy \
ghcr.io/sebadob/rauthy:0.23.1-lite
6. Restrict DB files access even more
After rauthy has done the first start, you could harden the access rights of the SQLite files even more.
This would make sure, that no one without sudo
could just copy and read in the SQLite in some other place.
Just execute once more:
sudo chmod 0700 -R rauthy/data
7. You can now proceed with the First Start steps.
Kubernetes
At the time of writing, there is no Helm Chart or Kustomize files available yet. The whole setup is pretty simple on purpose though, so it should not be a big deal to get it running inside Kubernetes.
Single Instance
Since rauthy uses pretty aggressive caching for different reasons, you cannot just have a single deployment and
scale up the replicas without enabling HA_MODE
. How to deploy a HA version is described below.
The steps to deploy on Kubernetes are pretty simple.
- Create namespace
- Create and apply the config
- Create and apply secrets
- Create and apply the stateful set
Create Namespace
For the purpose of this documentation, we assume that rauthy will be deployed in the rauthy
namespace.
If this is not the case for you, change the following commands accordingly.
kubectl create ns rauthy
Create and apply the config
This documentation will manage the Kubernetes files in a folder called rauthy
.
mkdir rauthy && cd rauthy
Create the config file, paste the reference config and adjust it to your needs.
There is no "nice 1-liner" available yet.
echo 'apiVersion: v1
kind: ConfigMap
metadata:
name: rauthy-config
namespace: rauthy
data:
rauthy.cfg: |+
PASTE CONFIG HERE - WATCH THE INDENTATION' > config.yaml
Open the config with your favorite editor and paste the reference config in place.
Make sure to watch the indentation.
Do not include sensitive information like for instance the ENC_KEYS inside the normal Config.
Use the secrets from the next step for this.
If you use SQLite, you can include the DATABASE_URL in the config, since it does not contain a password, but
never do this for Postgres!
Create and apply secrets
touch secrets.yaml
Paste the following content into the secrets.yaml
file:
apiVersion: v1
kind: Secret
metadata:
name: rauthy-secrets
namespace: rauthy
type: Opaque
data:
# The CACHE_AUTH_TOKEN is only needed for a deployment with HA_MODE == true
# Secret token, which is used to authenticate the cache members
#CACHE_AUTH_TOKEN:
# The database driver will be chosen at runtime depending on the given DATABASE_URL format. Examples:
# Sqlite: 'sqlite:data/rauthy.db' or 'sqlite::memory:'
# Postgres: 'postgresql://User:PasswordWithoutSpecialCharacters@localhost:5432/DatabaseName'
DATABASE_URL:
# Format: "key_id/enc_key another_key_id/another_enc_key" - the enc_key itself must be exactly 32 characters long and
# and should not contain special characters.
# The ID must match '[a-zA-Z0-9]{2,20}'
ENC_KEYS:
# Needed for sending E-Mails for password resets and so on
SMTP_PASSWORD:
The secrets need to be base64 encoded. If you are on Linux, you can do this in the shell easily. If not, use
any tool you like.
Make sure that things like CACHE_AUTH_TOKEN
(only needed with HA_MODE == true
) and ENC_KEYS
are generated
in a secure random way.
The DATABASE_URL
with SQLite, like used in this example, does not contain sensitive information, but we will
create it as a secret anyway to have an easier optional migration to postgres later on.
echo 'sqlite:data/rauthy.db' | base64
Generate a new encryption key with ID in the correct format.
echo "$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c8)/$(cat /dev/urandom | head -c32 | base64)" | base64
Paste the base64 String in the secrets for ENC_KEYS
.
To extract the ENC_KEY_ID
, which needs to be added to the config from Step 2:
echo -n PasteTheGeneratedBase64Here | base64 -d | cut -d/ -f1
And finally, the SMTP_PASSWORD
echo 'PasteYourSMTPPasswordHere' | base64
Paste all the generated secrets into the secrets.yaml
file and the ENC_KEY_ID
into the config.yaml
from the step
before.
Create and apply the stateful set
touch sts.yaml
Paste the following content into the sts.yaml
file:
apiVersion: v1
kind: Service
metadata:
name: rauthy
namespace: rauthy
spec:
selector:
app: rauthy
ports:
# If you use the HA feature later on, the port over which the cache layer does
# communicate.
- name: cache
port: 8000
targetPort: 8000
# Assuming that this example file will run behind a Kubernetes ingress and does
# use HTTP internally.
- name: http
port: 8080
targetPort: 8080
# Uncomment, if you change to direct HTTPS without a reverse proxy
#- name: https
# port: 8443
# targetPort: 8443
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: rauthy
namespace: rauthy
labels:
app: rauthy
spec:
serviceName: rauthy
# Do not just scale up replicas without a proper HA Setup
replicas: 1
selector:
matchLabels:
app: rauthy
template:
metadata:
labels:
app: rauthy
spec:
securityContext:
fsGroup: 10001
containers:
- name: rauthy
image: ghcr.io/sebadob/rauthy:0.23.1-lite
imagePullPolicy: IfNotPresent
securityContext:
# User ID 10001 is actually built into the container at the creation for
# better security
runAsUser: 10001
runAsGroup: 10001
allowPrivilegeEscalation: false
ports:
- containerPort: 8000
# You may need to adjust this, if you decide to start in https only mode
# or use another port
- containerPort: 8080
- containerPort: 8443
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: rauthy-secrets
key: DATABASE_URL
- name: ENC_KEYS
valueFrom:
secretKeyRef:
name: rauthy-secrets
key: ENC_KEYS
- name: SMTP_PASSWORD
valueFrom:
secretKeyRef:
name: rauthy-secrets
key: SMTP_PASSWORD
volumeMounts:
- mountPath: /app/data
name: rauthy-data
readOnly: false
- mountPath: /app/rauthy.cfg
subPath: rauthy.cfg
name: rauthy-config
readOnly: true
readinessProbe:
httpGet:
# You may need to adjust this, if you decide to start in https only
# mode or use another port
scheme: HTTP
port: 8080
#scheme: HTTPS
#port: 8443
path: /auth/v1/ping
initialDelaySeconds: 1
periodSeconds: 10
livenessProbe:
httpGet:
# You may need to adjust this, if you decide to start in https only
# mode or use another port
scheme: HTTP
port: 8080
#scheme: HTTPS
#port: 8443
path: /auth/v1/health
initialDelaySeconds: 1
periodSeconds: 30
resources:
requests:
# Tune the memory requests value carefully. Make sure, that the
# pods request at least:
# `ARGON2_M_COST` / 1024 * `MAX_HASH_THREADS` Mi
# With SQLite: for small deployments, add additional ~20-30Mi for
# "the rest", for larger ones ~50-70 Mi should be enough.
memory: 64Mi
# The CPU needs to be adjusted during runtime. This heavily
# depends on your use case.
cpu: 100m
limits:
# Be careful with the memory limit. You must make sure, that the
# (very costly) password hashing has enough memory available. If not,
# the application will crash. You do not really need a memory limit,
# since Rust is not a garbage collected language. Better take a close
# look at what the container actually needs during
# prime time and set the requested resources above properly.
#memory:
# A CPU limit may make sense in case of DDoS attacks or something
# like this, if you do not have external rate limiting or other
# mechanisms. Otherwise, `MAX_HASH_THREADS` is the main mechanism
# to limit resources.
cpu: 1000m
volumes:
- name: rauthy-config
configMap:
name: rauthy-config
volumeClaimTemplates:
- metadata:
name: rauthy-data
spec:
accessModes:
- "ReadWriteOnce"
resources:
requests:
storage: 128Mi
#storageClassName: provideIfYouHaveMultipleOnes
Ingress
This example assumes, that the deployment will run behind a Kubernetes ingress resource of your choice.
It uses Traefik with the IngressRoute
CRD.
Nevertheless, the ingress is really simple, and it should be very easy to adopt anything else.
Create the ingress.yaml
touch ingress.yaml
Paste the following content into the ingress.yaml
file and adjust to your needs
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: rauthy-https
namespace: rauthy
spec:
entryPoints:
- websecure
routes:
- match: Host(`auth.example.com`)
kind: Rule
services:
- name: rauthy
port: 8080
Deploy
We are now ready to deploy:
kubectl apply -f .
And then to observe the deployment:
kubectl -n rauthy get pod -w
You can now proceed with the First Start steps.
Production Setup
Config
Going to production does not need too many additional steps.
TLS Certificates
The thing you need will be valid TLS certificates, of course. To get these, there are a lot of existing mechanisms.
If you use an internal Certificate Authority (CA), you do have you own tools to work with this anyway. If, however, you
want to use something like Let's Encrypt, I suggest to use the
cert-manager, which is easy and straight forward to use.
An example, how to add a certificate for the Traefik IngressRoute from above:
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: rauthy-https
namespace: rauthy
spec:
entryPoints:
- websecure
tls:
# Paste the name of the TLS secret here
secretName: secret-name-of-your-tls-certificate
routes:
- match: Host(`auth.example.com`)
kind: Rule
services:
- name: rauthy
port: 8080
You may want to add an HTTPS redirect as well:
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: https-only
namespace: rauthy
spec:
redirectScheme:
scheme: https
permanent: true
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: rauthy-https
namespace: rauthy
spec:
entryPoints:
- web
routes:
- match: Host(`auth.example.com`)
kind: Rule
middlewares:
- name: https-only
services:
- name: rauthy
port: 8080
Additional steps
There are a few more things to do when going into production, but these are the same for Kubernetes and Docker and will be explained in later chapters.
You can now proceed with the First Start steps.
First Start
Initial admin password and login
With the very first start of rauthy, or better with an empty database, when rauthy is starting, it does not only create all the necessary schemas and initial data, but also some sensitive information will be generated safely. This includes a set of Json Web Keys (JWKS) for the token signing and some secrets.
The most important of these newly generated secrets is the default admin user's password.
When this is securely generated with the very first start, it will be logged into the console. This will only
happen once and never again.
Logs with docker
docker logs -f rauthy
Logs with Kubernetes
kubectl -n rauthy logs -f rauthy-0
If you do a Kubernets HA deployment directly, only the Pod rauthy-0
will log the initial password.
If you missed this log entry, you will not be able to log in.
If this is the case, you can delete the database / volume and just restart rauthy.
The log message contains a link to the accounts page, where you then should log in to immediately set a new password.
Follow the link, use as the default admin admin@localhost.de
and as password the copied value from the log.
- When logged into the account, click
EDIT
andCHANGE PASSWORD
to set a new password - Log out of the account and try to log in to the admin ui with the new password
Custom rauthy admin user
It is a good idea, to either keep the admin@localhost.de
as a fallback user with just a very long password, or
disable it, after a custom admin has been added.
When logged in to the admin UI, you can add a new user. When the SMTP
settings are correctly configured in the config,
which we can test right now, you will receive an E-Mail with the very first password reset.
If you do not receive an E-Mail after the first user registration, chances are you may have a problem with the SMTP
setup.
To debug this, you can set LOG_LEVEL=debug
in the config and then watch the logs after a restart.
rauthy_admin
user role
The role, which allows a user to access the admin UI, is the rauthy_admin
.
If the user has this role assigned, he will be seen as an admin.
Under the hood, rauthy itself uses the OIDC roles and groups in the same way, as all clients would do. This means you
should not neither delete the rauthy
default client, nor the rauthy_admin
role. There are mechanisms to prevents
this happening by accident via UI, but you could possibly do this via a direct API call.
There are some anti-lockout mechanisms in place in the backend, which will be executed with every start, but being
careful at this point is a good idea anyway.
Argon 2 Setup
Even though the options and tools in the Admin UI should be fully documented, I wanted to mention argon2id tuning here anyway.
Rauthy uses the argon2id hashing algorithm for passwords. This is the most expensive and compute-heavy operation
beging done by the application and the variables need to be tuned for every deployment to provide the best compromise
of security, resource usage and user experience.
The default values are way too low for a real production deployment. They should only be used for testing.
The Admin UI provides a utility which helps you find the values for your deployment quickly. What and how to do is described in the Admin UI itself, I just want to guide you to this utility especially, since it is an important step security wise.
When you are logged in to the Admin UI, please navigate to Config
-> Argon2 Parameters
to find your values.
After they have been found, apply them to the rauthy config and restart the deployment.
Keep in mind, that if you run the application in a way, where memory is limited, for instance inside Kubernetes with
resource limits set too low, that it will crash, if either ARGON2_M_COST
is set too high or the memory limit too low.
There is one additional, really important config variable need to be taken into account for the tuning.
Since this operation is really ressource intense, you can limit the amount of threads, which can run in parallel doing
hashing operations. This is really important when we think about constrained memory again.
MAX_HASH_THREADS
limits the maximum amount of parallel password hashes at the exact same time to never exceed system
memory while still allowing a good amount of memory.
The default value is 2.
The rule is simple: Allow as many resources as possible for hashing to have the maximum amount of security, while restricting it as much as necessary.
For smaller deployments, set MAX_HASH_THREADS=1
, which will technically allows only one user login at the exact same
time. This value makes an external rate limiting for the login obsolete (while you may add some for the others).
FIDO 2 / WebAuthn
Passkey Only Accounts
Since v0.16.0, Rauthy provides the ability to optionally create Passkey only accounts.
These accounts do not have any password at all. The user can lo gin via E-Mail and then providing the MFA
FIDO 2 Passkey. Only keys and systems with additional user verification (UV) will be accepted for these accounts.
This makes sure, that they are 2FA / MFA secured (depending on the device) all the time.
You can choose the account type either during the initial password reset link you get via E-Mail, or you can convert a traditional password account to a passkey only account in your account view, if you have at least one Passkey with additional UV registered.
Passkey only accounts provide a few benefits:
- no need to remember or store any passwords
- way easier and faster logging in
- always 2FA / MFA
- strongest type of authentication
- no need to satisfy password policies
- no need to reset your password after it has been expired
Passkey only accounts cannot use the traditional password reset E-Mails.
This is a drawback and a benefit at the same time:
No way to take over an account if the E-Mail account has been compromised, but at the same time the user
relies on an Admin to reset the MFA devices, if no backup exists or all are lost.
Android has finally added support for biometric UV in September 2023.
This has made is possible to implement this feature into Rauthy without sacrificing security.
However, at the time of writing (09.10.2023), only biometric UV is supported and PIN UV is about to come in the near future.
If you want to register an Android device for a Passkey only account, but you are using for instance Yubikeys with PIN UV, you can do the following trick to get it done (works only with the latest Play store version):
- Create a password for your account, if it does not exist yet
- Remove all registered passkeys
- Log in to your account view on your Android device and another device that works with your Yubikey
- With both devices logged in at the same time:
- Register a new passkey with Android and choose "this device", which will create a Passkey flow with your fingerprint
- Register the Yubikey on the other device
- You should now have 2 Passkeys: Android + Yubikey
- Navigate to the Password page inside your account on any device and convert it to Passkey only
- You should now be able to log in on your Android device with Passkey only and with your Yubikey
Config
You should use FIDO 2 in production for 2FA / MFA. To make sure it works, you need to check your the config.
Set / check some variables in your config, to make sure it works correctly.
RP_ID
This usually is the 'Relaying Party (RP) ID', which should be your effective domain name. For the above example, since our application is available under 'auth.example.com', this should also be:
RP_ID=auth.example.com
When the RP_ID
changes, already registered devices will stop working and users cannot log in anymore!
Be very careful, if you want / need to do this in production.
RP_ORIGIN
The seconds important variable for FIDO 2 is the RP_ORIGIN
. This needs to be set to the URL containing the effective
domain name.
The RP_ORIGIN
must always include the port number, even it is just the default 443 for HTTPS.
In this example, assuming rauthy will be available at port 443, correct would be:
RP_ORIGIN=https://auth.example.com:443
RP_NAME
This variable can be set to anything "nice".
This may be shown to the user in a way like "RP_BNAE
requests your security key ...". If this is shown depends on the
OS and the browser the client uses. Firefox, for instance, does not show this at the time of writing.
You can change the RP_NAME
later on without affecting the validation of already registered keys.
WEBAUTHN_RENEW_EXP
For all non Passkey only accounts, Rauthy will always prompt a user at least once for the password on a new machine, even with active passkeys. The keys are used either as a strong second factor, when they do not work with a PIN, or bump up the whole login to real MFA, if the OS / Browser / Key does support this.
When a user as logged in successfully on a new device and active 2FA / MFA, he will get an encrypted cookie.
The lifetime of this cookie can be configured with WEBAUTHN_RENEW_EXP
.
The default of this value is 2160 hours.
As long as this cookie is present and can be decrypted by the backend, the user can log in from this very device with his FIDO 2 key only, which makes a very good user experience for the whole login flow. The E-Mail will already be filled automatically and only a single click on the login button is necessary.
Encryption
In the Getting Started, we have set up the ENC_KEYS
and ENC_KEY_ACTIVE
.
The ENC_KEYS
defines the static keys used for additional data encryption in a few places. This values may contain
multiple keys, if you want to rotate them at some point without breaking the decryption of all already existing secrets.
ENC_KEY_ACTIVE
defines the key inside ENC_KEYS
which will be used as the default. This means that all new / current
encryptions performed by the backend will use the key with the given ID.
Key Rotation
1. Add a new key to the ENC_KEYS
in you secrets
You must not remove a current key, before the migration has been done via the UI.
If the old key is gone, the migration will fail.
2. Generate a new key + id
echo "$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c8)/$(cat /dev/urandom | head -c32 | base64)"
The part before the first /
is the ENC_KEY_ID
and the part afterwards is the key base64 encoded.
You might set the new ENC_KEY_ACTIVE
to the newly generated key ID.
Keep in mind, you need to ADD this to your existing keys and not just replace them! If you just replace them, almost all things will break and fall apart.
The final format of the ENC_KEYS
should look something like this, for instance:
ENC_KEYS="
Wx1zrbLF/5vTaB7LdUSg1aTecmqHJOu2+RnU6zgTwNkDQU52Y3JM=
6uf5QebA/9DsKMoq8A+Gn2WQrTcSpz5sg751yYs3IJlkw3dn0rII=
"
In this example, if the first key should be the new active default, set your ENC_KEY
ACTIVE` to
ENC_KEY_ACTIVE=Wx1zrbLF
If you are inside Kubernetes and (hopefully) use a Kubernetes secret for this, you need to base64 encode the whole
value: echo 'PutTheWholeValueHere' | base64
3. Set the ENC_KEY_ACTIVE
to the ID of your newly generated key
This will make sure, that all new encryptions will use the new key. If you do not care about removing the old keys,
because you maybe just want to rotate because its good practice, the secrets will migrate "by themselves" over time.
If Rauthy finds any secrets during its normal operation, that have been encrypted with an older key than the current
ENC_KEY_ACTIVE
, it will re-encrypt these secrets and update the values.
This means, you may just stop at this point, if this is good enough for you.
4. Migrate Keys
If you however want to trigger a re-encryption of all existing secrets on purpose, there is a small tool in the Admin UI which helps you with this.
Log in to the Admin UI and navigate to Config
-> Encryption Keys
.
You will see the currently recognized keys and the currently active ID.
You can then make sure, that the ID you want to migrate secrets to is selected and execute the migrations.
Please keep in mind, that if you have a lot of data, it might take a few seconds to perform this operation.
This will migrate all encrypted data for existing OIDC clients and all JWKs used for JWT token singing with the new
key.
5. Remove old keys
After a successful migration via the UI tool, you may remove old keys from the ENC_KEYS
value.
The MFA cookies, which are set for a client with an active security after a successful login, are encrypted with the
ENC_KEY_ACTIVE
too. This means, if you remove something from the ENC_KEYS
which was used to encrypt one of these
MFA cookies, the user will be prompted for the password again, even if the cookie has not expired yet.
Database Migrations
You can migrate easily between SQLite and Postgres, or just between different instances of them.
Let's say you started out by evaluating Rauthy with a SQLite and a single instance deployment. Later on, you want to migrate to a HA setup, which requires you to use a Postgres.
Solution: MIGRATE_DB_FROM
If you set the MIGRATE_DB_FROM
in Rauthy's config, it will perform a migration at the next restart.
The way it works is the following:
- At startup, have a look if
MIGRATE_DB_FROM
is configured - If yes, then connect to the given database
- At the same time, connect to the database specified in the
DATABASE_URL
- Overwrite all existing data in
DATABASE_URL
with the data from theMIGRATE_DB_FROM
database - Close the connection to
MIGRATE_DB_FROM
- Use the
DATABASE_URL
as the new database and start normal operation
MIGRATE_DB_FROM
overwrites any data in the target database! Be very careful with this option.
If you do not remove the MIGRATE_DB_FROM
after the migration has been done, it will overwrite the target again with
the next restart of the application. Remove the config variable immediately after the migration has finished.
v0.14 and beyond: if you want to migrate to a different database, for instance from SQLite to Postgres, you need to switch to the correct rauthy image as well. Rauthy v0.14 and beyond has different container images for the databases.
The easiest to do is to just set MIGRATE_DB_FROM
as an environmant variable, which is easier and quicker to remove
again afterwards.
Backups
SQLite
If Rauthy is using a SQLite, it does automatic backups, which can be configured with:
# Cron job for automatic data store backups (default: "0 0 4 * * * *")
# sec min hour day_of_month month day_of_week year
BACKUP_TASK="0 0 4 * * * *"
# The name for the data store backups. The current timestamp will always be appended automatically.
# default: rauthy-backup-
BACKUP_NAME="rauthy-backup-"
# All backups older than the specified hours will be cleaned up automatically (default: 720)
BACKUP_RETENTION_LOCAL=24
All these backups are written inside the pod / container into /app/data/backup
.
The database itself will be saved in /app/data
by default.
This difference makes it possible, that you could add a second volume mount to the container.
You then have the database itself on a different disk than the backups, which is the most simple and straight forward
approach to have a basic backup strategy.
The SQLite backups are done with VACUUM
, which means you can just use the backups as a normal database again.
This makes it possible, to just use the Database Migration feature to apply backups very easily.
Postgres
If you are using Postgres as the main database, Rauthy does not do any backups.
There are a lot of way better tools out there to handle this task.
High Availability
Rauthy is capable of running in a High Availability Mode (HA).
Some values, like authentication codes for instance, do live in the cache only. Additionally, there might come an option with a future version which offers a special in-memory only mode in some situations.
Because of this, all instances create and share a single HA cache layer, which means at the same time, that you cannot just scale up the replicas infinitely. The optimal amount of replicas for a HA mode would be 3, or if you need even higher resilience 5. More replicas should work just fine, but this has never been really tested and the performance will degrade at some point.
To achieve the HA caching layer embedded directly into the application, I created a library (or crate in Rust terms)
called redhac
.
This crate will create each a gRPC server and a client part and each node will connect to all other ones. Once quorum
has been reached, a leader will be elected, which then will execute all insert requests by default to avoid overlaps
or inconsistencies and to guarantee a configured level of safety. Different so called AckLevel
are available, like
Quorum
, Once
and Leader
in addition to a direct cache put without any safeties.
Rauthy uses different levels in different situations to provide real HA and sync all caches between the pods. This
means that you can loose a pod and still have the in-cache-only values available on the other ones.
This syncing of the cache is the reason why write performance will degrade, if you scale up too many replicas, which should not really be necessary anyway. The best HA performance will be achieved with 3 replicas and then scaling up the resources for each pod before adding more replicas.
Configuration
The way to configure the HA_MODE
is optimized for a Kubernetes deployment but may seem a bit odd at the same time,
if you deploy somewhere else. You need to the following values in the config file:
HA_MODE
The first one is easy, just set HA_MODE=true
HA_HOSTS
The HA_HOSTS
is working in a way, that it is really easy inside Kubernetes to configure it, as long as a
StatefulSet is used for the deployment.
The way a cache node finds its members is by the HA_HOSTS
and its own HOSTNAME
.
In the HA_HOSTS
, add every cache member. For instance, if you want to use 3 replicas in HA mode which are running
and are deployed as a StatefulSet with the name rauthy
again:
HA_HOSTS="http://rauthy-0.rauthy:8000, http://rauthy-1.rauthy:8000, http://rauthy-2.rauthy:8000"
The way it works:
- A node gets its own hostname from the OS
This is the reason, why you use a StatefulSet for the deployment, even without any volumes attached. For StatefulSet calledrauthy
, the replicas will always have the namesrauthy-0
,rauthy-1
, ..., which are at the same time the hostnames inside the pod. - Find "me" inside the
HA_HOSTS
variable
If the hostname cannot be found in theHA_HOSTS
, the application will panic and exit because of a misconfiguration. - Use the port from the "me"-Entry that was found for the server part
This means you do not need to specify the port in another variable which eliminates the risk of having inconsistencies or a bad config in that case. - Extract "me" from the
HA_HOSTS
, take the leftover nodes as all cache members and connect to them - Once a quorum has been reached, a leader will be elected
From that point on, the cache will start accepting requests - If the leader is lost - elect a new one - No values will be lost
- If quorum is lost, the cache will be invalidated
This happens for security reasons to provide cache inconsistencies. Better invalidate the cache and fetch the values fresh from the DB or other cache members than working with possibly invalid values, which is especially true in an authn / authz situation.
If you are in an environment where the described mechanism with extracting the hostname would not work, for instance
you want a HA deployment with just different docker hosts, you can set the HOSTNAME_OVERWRITE
for each instance to
match one of the HA_HOSTS
entries.
CACHE_AUTH_TOKEN
You need to set a secret for the CACHE_AUTH_TOKEN
which was left out in the
Getting Started
Just create a secret and add it in the same way:
echo "$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c48)" | base64
TLS
If you are using a service mesh like for instance linkerd which creates mTLS connections between all pods by default, you can use the HA cache with just plain HTTP, since linkerd will encapsulate the traffic anyway.
You may then set
CACHE_TLS=false
to disable the use of TLS certificates between cache member.
However, if you do not have encryption between pods by default, I would highly recommend, that you use TLS.
TLS
If you do have TLS certificates from another source already, skip directly to Config.
Generating Certificates
We are using another project of mine called Nioca for an easy creation of a fully functioning and production ready private Root Certificate Authority (CA).
I suggest to use docker
for this task. Otherwise, you can use the nioca
binary directly on any linux machine.
If you want a permanent way of generating certificates for yourself, take a look at Rauthy's justfile
and copy
and adjust the recipes create-root-ca
and create-end-entity-tls
to your liking.
If you just want to get everything started quickly, follow these steps:
Create an alias for the docker
command
alias nioca='docker run --rm -it -v ./:/ca -u $(id -u ${USER}):$(id -g ${USER}) ghcr.io/sebadob/nioca'
To see the full feature set for more customization than mentioned below:
nioca x509 -h
Generate full certificate chain
To make your browser happy, your need to have at least one --alt-name-dns
for the URL of your application.
You can define as many of them as you like.
nioca x509 \
--cn 'Rauthy Default' \
--o 'Rauthy OIDC' \
--alt-name-dns localhost \
--alt-name-dns redhac.local \
--usages-ext server-auth \
--usages-ext client-auth \
--stage full \
--clean
You will be asked 6 times (yes, 6) for an at least 16 character password:
- The first 3 times, you need to provide the encryption password for your Root CA
- The last 3 times, you should provide a different password for your Intermediate CA
When everything was successful, you will have a new folder named x509
with sub folders root
, intermediate
and end_entity
in your current one.
From these, you will need the following files:
cp x509/intermediate/ca-chain.pem . && \
cp x509/end_entity/$(cat x509/end_entity/serial)/cert-chain.pem . && \
cp x509/end_entity/$(cat x509/end_entity/serial)/key.pem .
- You should have 3 files in
ls -l
:
ca-chain.pem
cert-chain.pem
key.pem
Config
The reference config contains a TLS
section with all the values you can set.
For this example, we will be using the same certificates for both the internal cache mTLS connections and the public facing HTTPS server.
Cache
The cache layer (optionally) creates an mTLS connection and validates client certificates, if they are configured.
To enable TLS at all, set
CACHE_TLS=true
By default, redhac
expects certificates to be in /app/tls/
with the common name / SNI redhac.local
.
The certificates need to be in the PEM format and you can provide different certificates for the server and client part,
if you like.
If this differs from your setup, you can set the following config variables:
# The path to the server TLS certificate PEM file (default: tls/redhac.local.cert.pem)
CACHE_TLS_SERVER_CERT=tls/cert-chain.pem
# The path to the server TLS key PEM file (default: tls/redhac.local.key.pem)
CACHE_TLS_SERVER_KEY=tls/key.pem
# If not empty, the PEM file from the specified location will be added as the CA certificate chain for validating
# the servers TLS certificate (default: tls/ca-chain.cert.pem)
CACHE_TLS_CA_SERVER=tls/ca-chain.pem
# The path to the client mTLS certificate PEM file (default: tls/redhac.local.cert.pem)
CACHE_TLS_CLIENT_CERT=tls/cert-chain.pem
# The path to the client mTLS key PEM file (default: tls/redhac.local.key.pem)
CACHE_TLS_CLIENT_KEY=tls/key.pem
# If not empty, the PEM file from the specified location will be added as the CA certificate chain for validating
# the clients mTLS certificate (default: tls/ca-chain.cert.pem)
CACHE_TLS_CA_CLIENT=tls/ca-chain.pem
# The domain / CN the client should validate the certificate against. This domain MUST be inside the
# 'X509v3 Subject Alternative Name' when you take a look at the servers certificate with the openssl tool.
# default: redhac.local
CACHE_TLS_CLIENT_VALIDATE_DOMAIN=redhac.local
# Can be used, if you need to overwrite the SNI when the client connects to the server, for instance if you are behind
# a loadbalancer which combines multiple certificates. (default: "")
#CACHE_TLS_SNI_OVERWRITE=
Server
The TLS configuration for the REST API is much simpler.
By default, rauthy will expect a certificate and a key file in /app/tls/tls.key
and /app/tls/tls.crt
, which is the
default naming for a Kubernetes TLS secret. The expected format is PEM, but you could provide the key in DER format too,
if you rename the file-ending to *.der
.
You can change the default path for the files with the config variables TLS_CERT
and TLS_KEY
.
Kubernetes
If you did not follow the above procedure to generate the CA and certificates, you may need to rename the files in the following command, to create the Kubernetes secrets.
Secrets - REST API
kubectl -n rauthy create secret tls rauthy-tls --key="key.pem" --cert="cert-chain.pem"
Secrets - redhac
cache
kubectl -n rauthy create secret tls redhac-tls-server --key="key.pem" --cert="cert-chain.pem" && \
kubectl -n rauthy create secret generic redhac-server-ca --from-file ca-chain.pem
We create the redhac-tls-server
here with the exact same values. If you really want to harden your setup in production,
you should provide a different set of certificates for the internal mTLS connection.
Config Adjustments - REST API
We need to configure the newly created Kubernetes secrets in the std.yaml
from the
Kubernetes setup.
- In the
spec.template.spec.volumes
section, we need to mount the volumes from secrets:
REST API:
- name: rauthy-tls
secret:
secretName: rauthy-tls
redhac
cache:
- name: redhac-tls-server
secret:
secretName: redhac-tls-server
- name: redhac-server-ca
secret:
secretName: redhac-server-ca
- In the
spec.template.spec.containers.[rauthy].volumeMounts
section, add::
REST API:
- mountPath: /app/tls/
name: rauthy-tls
readOnly: true
redhac
cache:
- mountPath: /app/tls/redhac/certs
name: redhac-tls-server
readOnly: true
- mountPath: /app/tls/redhac/ca
name: redhac-server-ca
readOnly: true
After having modified the config from above and the sts.yaml
now, just apply both:
kubectl apply -f config.yaml
kubectl apply -f sts.yaml
The rauthy
pods should restart now and TLS is configured.
Upstream Authentication Providers
This section is about upstream authentication providers, for instance things like Sign in with Github.
This feature can be considered "in beta state" and the only setup guide is for Github for now.
Additional ones may come, when people are using other providers and give feedback or actually contribute to these docs.
Github Provider
To set up Github as an upstream provider for Rauthy, you have pretty little things to do.
Rauthy includes a Template for Github already, which makes this whole process pretty simple.
Create an OAuth App
- Log in to your Github account
- Navigate to Settings -> Developer Settings -> OAuth Apps -> Register a new application
- Provide any name for your application. This is not important for the flow, only for your users to recognize
- Homepage URL should be the URL of your Rauthy deployment
Authorization callback URL
is the only really important one here. For instance, if your Rauthy instance would live athttps://iam.example.com
, your callback URL would behttps://iam.example.com/auth/v1/providers/callback
- Don't enable Device Flow and
Register application
On the following page, you can upload a logo and so on, but the important information is:
Client ID
Generate a new client secret
Both of these values need to be inserted into Rauthy's Admin UI in the next step, so lets open this in a new tab.
Rauthy Provider Config
- Log in to your Rauthy Admin UI, navigate to
Providers
and add a new provier. - Choose
Github
as theType
and leave the Custom Root CA and insecure TLS unchecked.
- The template pre-populates most of the inputs already for you. The only information you need to add here is
Client ID
-> copyClient ID
from the Github OAuth App page inside hereClient Secret
-> on Github,Generate a new client secret
and copy & paste the value- you may edit the
Client Name
if you want something else thanGithub
- Leave the rest untouched and hit
Save
- You should expand the saved Github provider in the Rauthy UI again after saving and upload a Logo for the Client.
Currently, Rauthy does not provide default Logos, though these might be added at some point. Just
UPLOAD LOGO
from your local disk.
Finish
That's it. Now log out and try to log in to your Account view. You should see your new upstream provider on the Login page.
Reference Config
This shows a full example config with (hopefully) every value nicely described.
When you go into production, make sure that you provide the included secrets / sensistive information in this file in an appropriate way. With docker, you can leave them inside this file, but when deploying with Kubernetes, extract these values, create Kubernetes Secrets and provide them as environment variables.
#####################################
############## ACCESS ###############
#####################################
# If the User Registration endpoint should be accessible by anyone.
# If not, an admin must create each new user. (default: false)
#OPEN_USER_REG=true
# If set to true, the `/userinfo` endpoint will do additional validations.
# The non-strict mode will fetch the user by id from the `sub` claim and make
# sure it still exists and is enabled. The strict validation will do additional
# database fetches and validates every possible value.
# Additionally, it will look up a possibly linked user device from the `did` claim
# and make sure it still exists. It will also extract the `client_id` the token
# has been originally issued for from the `azp` claim, fetch it and make sure it
# still exists and is enabled.
# If you don't need the extra validations, you can set this to `false` to
# save some resources, if your clients to a lot of `/userinfo` lookups.
# default: true
USERINFO_STRICT=true
# Can be used when 'OPEN_USER_REG=true' to restrict the domains
# for a registration. For instance, set it to
# 'USER_REG_DOMAIN_RESTRICTION=gmail.com' to allow only
# registrations with 'user@gmail.com' (default: '')
#USER_REG_DOMAIN_RESTRICTION=some-domain.com
# If set to 'true', this will validate the remote peer IP address with
# each request and compare it with the IP which was used during the initial
# session creation / login. If the IP is different, the session will be
# rejected. This is a security hardening and prevents stolen access credentials,
# for instance if an attacker might have copied the encrypted session cookie
# and the XSRF token from the local storage from a user. However, this event
# is really unlikely, since it may only happen if an attacker has direct access
# to the machine itself.
#
# If your users are using mobile networks and get new IP addresses all the time,
# this means they have to do a new login each time. This is no big deal at all with
# Webauthn / FIDO keys anyway and should not be a reason to deactivate this feature.
#
# Caution: If you are running behind a reverse proxy which does not provide the
# X-FORWARDED-FOR header correctly, or you have the PROXY_MODE in this config
# disabled, this feature will not work. You can validate the IPs for each session
# in the Admin UI. If these are correct, your setup is okay.
#
# (default: true)
#SESSION_VALIDATE_IP=true
# By default, Rauthy will log a warning into the logs, if an active password
# reset form is being access multiple times from different hosts. You can set
# this to `true` to actually block any following request after the initial one.
# This hardens the security of the password reset form a bit more, but will
# create problems with E-Mail providers like Microsoft, which cans the customers
# E-Mails and even uses links inside, which make them unusable with this set to
# true.
# This feature works by setting an encrypted cookie to the host whichever opens
# the password reset form for the very first time. All subsequent requests either
# need to provide that cookie or would otherwise be rejected.
#PASSWORD_RESET_COOKIE_BINDING=true
# Can be set to extract the remote client peer IP from a custom header name
# instead of the default mechanisms. This is needed when you are running
# behind a proxy which does not set the `X-REAL-IP` or `X-FORWARDED-FOR` headers
# correctly, or for instance when you proxy your requests through a CDN like
# Cloudflare, which adds custom headers in this case.
# For instance, if your requests are proxied through cloudflare, your would
# set `CF-Connecting-IP`.
PEER_IP_HEADER_NAME="CF-Connecting-IP"
# You can enable authn/authz headers which would be added to the response
# of the `/auth/v1/forward_auth` endpoint. With `AUTH_HEADERS_ENABLE=true`,
# the headers below will be added to authenticated requests. These could
# be used on legacy downstream applications, that don't support OIDC on
# their own.
# However, be careful when using this, since this kind of authn/authz has
# a lot of pitfalls out of the scope of Rauthy.
AUTH_HEADERS_ENABLE=true
# Configure the header names being used for the different values.
# You can change them to your needs, if you cannot easily change your
# downstream apps.
# default: x-forwarded-user
AUTH_HEADER_USER=x-forwarded-user
# default: x-forwarded-user-roles
AUTH_HEADER_ROLES=x-forwarded-user-roles
# default: x-forwarded-user-groups
AUTH_HEADER_GROUPS=x-forwarded-user-groups
# default: x-forwarded-user-email
AUTH_HEADER_EMAIL=x-forwarded-user-email
# default: x-forwarded-user-email-verified
AUTH_HEADER_EMAIL_VERIFIED=x-forwarded-user-email-verified
# default: x-forwarded-user-family-name
AUTH_HEADER_FAMILY_NAME=x-forwarded-user-family-name
# default: x-forwarded-user-given-name
AUTH_HEADER_GIVEN_NAME=x-forwarded-user-given-name
# default: x-forwarded-user-mfa
AUTH_HEADER_MFA=x-forwarded-user-mfa
# You can set different security levels for Rauthy's cookies.
# The safest option would be 'host', but may not be desirable when
# you host an application on the same origin behind a reverse proxy.
# In this case you might want to restrict to 'secure', which will then
# take the COOKIE_PATH from below into account.
# The last option is 'danger-insecure' which really should never be used
# unless you are just testing on localhost and you are using Safari.
#COOKIE_MODE=host
# If set to 'true', Rauthy will bind the cookie to the `/auth` path.
# You may want to change this only for very specific reasons and if
# you are in such a situation, where you need this, you will know it.
# Otherwise don't change this value.
# default: true
#COOKIE_SET_PATH=true
# The "catch all" route handler on `/` will compare the request path
# against a hardcoded list of common scan targets from bots and attackers.
# If the path matches any of these targets, the IP will be blacklisted
# preemptively for the set time in minutes.
# You can disable it with setting it to `0`.
# default: 1440
#SUSPICIOUS_REQUESTS_BLACKLIST=1440
# This will emit a log with level of warning if a request to `/` has
# been made that has not been caught by any of the usual routes and
# and handlers. Apart from a request to just `/` which will end in
# a redirect to `/auth/v1`, all additional path's will be logged.
# This can help to improve the internal suspicious blocklist in the
# future.
# default: false
#SUSPICIOUS_REQUESTS_LOG=false
#####################################
############# BACKUPS ###############
#####################################
# Cron job for automatic data store backups (default: "0 0 4 * * * *")
# sec min hour day_of_month month day_of_week year
#BACKUP_TASK="0 0 4 * * * *"
# The name for the data store backups. The current timestamp
# will always be appended automatically. (default: rauthy-backup-)
#BACKUP_NAME="rauthy-backup-"
# All backups older than the specified hours will be cleaned up
# automatically (default: 720)
#BACKUP_RETENTION_LOCAL=720
# The following section will only be taken into account, when
# SQLite is used as the main database. If you use Postgres, you
# should use Postgres native tooling like for instance `pgbackrest`
# to manage your backups.
# If S3 access is configured, your SQLite backups will be encrypted
# and pushed into the configured bucket.
#S3_URL=
#S3_REGION=
#S3_PATH_STYLE=false
#S3_BUCKET=my_s3_bucket_name
#S3_ACCESS_KEY=
#S3_ACCESS_SECRET=
#S3_DANGER_ACCEPT_INVALID_CERTS=false
# Restores the given backup
#
# CAUTION: Be very careful with this option - it will overwrite
# any existing database! The best way to use this option is to
# provide it as an environment variable for a single start up
# and then remove it directly after success.
#
# This only works when you are using a SQLite database!
# If you are running on Postgres, you must use Postgres-native
# tooling to handle your backups.
#
# You can either restore a local backup, or an encrypted one
# from S3 storage.
#
# For restoring from a local backup, provide the folder name
# of the backup you want to restore. Local SQLite backups are
# always in `./data/backup/rauthy-backup-TIMESTAMP/` folders.
# You only provide the backup folder name itself, in this case
# it would be `rauthy-backup-TIMESTAMP` like this:
# RESTORE_BACKUP=file:rauthy-backup-TIMESTAMP
#
# If you want to restore an encrypted backup from S3 storage,
# you must provide the object name in the configured bucket.
# For instance, let's say we have an object named
# `rauthy-0.20.0-1703243039.cryptr` in our bucket, then the
# format would be:
# RESTORE_BACKUP=s3:rauthy-0.20.0-1703243039.cryptr
#
#RESTORE_BACKUP=
#####################################
############ BOOTSTRAP ##############
#####################################
# If set, the email of the default admin will be changed
# during the initialization of an empty production database.
#BOOTSTRAP_ADMIN_EMAIL=admin@localhost.de
# If set, this plain text password will be used for the
# initial admin password instead of generating a random
# password.
#BOOTSTRAP_ADMIN_PASSWORD_PLAIN="123SuperSafe"
# If set, this will take the argon2id hashed password
# during the initialization of an empty production database.
# If both BOOTSTRAP_ADMIN_PASSWORD_PLAIN and
# BOOTSTRAP_ADMIN_PASSWORD_ARGON2ID are set, the hashed version
# will always be prioritized.
#BOOTSTRAP_ADMIN_PASSWORD_ARGON2ID='$argon2id$v=19$m=32768,t=3,p=2$xr23OhOHw+pNyy3dYKZUcA$CBO4NpGvyi6gvrb5uNrnsS/z/Ew+IuS0/gVqFmLKncA'
# You can provide an API Key during the initial prod database
# bootstrap. This key must match the format and pass validation.
# You need to provide it as a base64 encoded JSON in the format:
#
# ```
# struct ApiKeyRequest {
# /// Validation: `^[a-zA-Z0-9_-/]{2,24}$`
# name: String,
# /// Unix timestamp in seconds in the future (max year 2099)
# exp: Option<i64>,
# access: Vec<ApiKeyAccess>,
# }
#
# struct ApiKeyAccess {
# group: AccessGroup,
# access_rights: Vec<AccessRights>,
# }
#
# enum AccessGroup {
# Blacklist,
# Clients,
# Events,
# Generic,
# Groups,
# Roles,
# Secrets,
# Sessions,
# Scopes,
# UserAttributes,
# Users,
# }
#
# #[serde(rename_all = "lowercase")]
# enum AccessRights {
# Read,
# Create,
# Update,
# Delete,
# }
# ```
#
# You can use the `api_key_example.json` from `/` as
# an example. Afterwards, just `base64 api_key_example.json | tr -d '\n'`
#BOOTSTRAP_API_KEY="ewogICJuYW1lIjogImJvb3RzdHJhcCIsCiAgImV4cCI6IDE3MzU1OTk2MDAsCiAgImFjY2VzcyI6IFsKICAgIHsKICAgICAgImdyb3VwIjogIkNsaWVudHMiLAogICAgICAiYWNjZXNzX3JpZ2h0cyI6IFsKICAgICAgICAicmVhZCIsCiAgICAgICAgImNyZWF0ZSIsCiAgICAgICAgInVwZGF0ZSIsCiAgICAgICAgImRlbGV0ZSIKICAgICAgXQogICAgfSwKICAgIHsKICAgICAgImdyb3VwIjogIlJvbGVzIiwKICAgICAgImFjY2Vzc19yaWdodHMiOiBbCiAgICAgICAgInJlYWQiLAogICAgICAgICJjcmVhdGUiLAogICAgICAgICJ1cGRhdGUiLAogICAgICAgICJkZWxldGUiCiAgICAgIF0KICAgIH0sCiAgICB7CiAgICAgICJncm91cCI6ICJHcm91cHMiLAogICAgICAiYWNjZXNzX3JpZ2h0cyI6IFsKICAgICAgICAicmVhZCIsCiAgICAgICAgImNyZWF0ZSIsCiAgICAgICAgInVwZGF0ZSIsCiAgICAgICAgImRlbGV0ZSIKICAgICAgXQogICAgfQogIF0KfQ=="
# The secret for the above defined bootstrap API Key.
# This must be at least 64 alphanumeric characters long.
# You will be able to use that key afterwards with setting
# the `Authorization` header:
#
# `Authorization: API-Key <your_key_name_from_above>$<this_secret>`
#BOOTSTRAP_API_KEY_SECRET=twUA2M7RZ8H3FyJHbti2AcMADPDCxDqUKbvi8FDnm3nYidwQx57Wfv6iaVTQynMh
#####################################
############## CACHE ################
#####################################
# If the cache should start in HA mode or standalone
# accepts 'true|false', defaults to 'false'
#HA_MODE=false
# The connection strings (with hostnames) of the HA instances
# as a CSV.
# Format: 'scheme://hostname:port'
#HA_HOSTS="http://rauthy-0.rauthy:8000, http://rauthy-1.rauthy:8000, http://rauthy-2.rauthy:8000"
# Overwrite the hostname which is used to identify each cache member.
# Useful in scenarios, where for instance all members are on the same host with
# different ports or for testing.
#HOSTNAME_OVERWRITE="rauthy-0.rauthy:8080"
## Define buffer sizes for channels between the components
# Buffer for client requests on the incoming stream - server
# side (default: 128)
# Make sense to have the CACHE_BUF_SERVER set to:
# `(number of total HA cache hosts - 1) * CACHE_BUF_CLIENT`
# In a non-HA deployment, set the same size for both
#CACHE_BUF_SERVER=128
# Buffer for client requests to remote servers for all cache
# operations (default: 128)
#CACHE_BUF_CLIENT=128
# 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
# Secret token, which is used to authenticate the cache members
#CACHE_AUTH_TOKEN=SomeSuperSecretAndVerySafeToken1337
## Connections Timeouts
# The Server sends out keepalive pings with configured timeouts
# The keepalive ping interval in seconds (default: 5)
#CACHE_KEEPALIVE_INTERVAL=5
# The keepalive ping timeout in seconds (default: 5)
#CACHE_KEEPALIVE_TIMEOUT=5
# The timeout for the leader election. If a newly saved leader
# request has not reached quorum after the timeout, the leader
# will be reset and a new request will be sent out.
# CAUTION:
# This should not be lower than CACHE_RECONNECT_TIMEOUT_UPPER,
# since cold starts and elections will be problematic in that
# case.
# value in seconds, default: 15
#CACHE_ELECTION_TIMEOUT=15
# These 2 values define the reconnect timeout for the HA Cache
# Clients. The values are in ms and a random between these 2
# will be chosen each time to avoid conflicts and race conditions
# (default: 2500)
#CACHE_RECONNECT_TIMEOUT_LOWER=2500
# (default: 5000)
#CACHE_RECONNECT_TIMEOUT_UPPER=5000
#####################################
############ DATABASE ###############
#####################################
# The database driver will be chosen at runtime depending on
# the given DATABASE_URL format. Examples:
# Sqlite: 'sqlite:data/rauthy.db' or 'sqlite::memory:'
# Postgres: 'postgresql://User:PasswordWithoutSpecialCharacters@localhost:5432/DatabaseName'
#
# NOTE: The password in this case should be alphanumeric. Special
# characters could cause problems in the connection string.
#
# CAUTION:
# To make the automatic migrations work with Postgres15, when
# you do not want to just use the `postgres` user, You need
# to have a user with the same name as the DB / schema. For
# instance, the following would work without granting extra
# access to the `public` schema which is disabled by default
# since PG15:
#
# database: rauthy
# user: rauthy
# schema: rauthy with owner rauthy
#
#DATABASE_URL=sqlite::memory:
#DATABASE_URL=sqlite:data/rauthy.db
#DATABASE_URL=postgresql://rauthy:123SuperSafe@localhost:5432/rauthy
# Max DB connections - irrelevant for SQLite (default: 5)
#DATABASE_MAX_CONN=5
# If specified, the current Database, set with DATABASE_URL,
# will be DELETED and OVERWRITTEN with a migration from the
# given database with this variable. Can be used to migrate
# between different databases.
#
# !!! USE WITH CARE !!!
#MIGRATE_DB_FROM=sqlite:data/rauthy.db
# Disables the housekeeping schedulers (default: false)
#SCHED_DISABLE=true
# The interval in minutes in which the scheduler for expired
# users should run. If this finds expired users, it invalidates
# all existing sessions and refresh tokens for this user.
# default: 60
#SCHED_USER_EXP_MINS=60
# The threshold in minutes after which time the user expiry
# scheduler should automatically clean up expired users.
# If not set at all, expired users will never be cleaned up
# automatically.
# default: disabled / not set
#SCHED_USER_EXP_DELETE_MINS=7200
#####################################
############## DPOP #################
#####################################
# May be set to 'false' to disable forcing the usage of
# DPoP nonce's.
# default: true
DPOP_FORCE_NONCE=true
# Lifetime in seconds for DPoP nonces. These are used to
# limit the lifetime of a client's DPoP proof. Do not set
# lower than 30 seconds to avoid too many failed client
# token requests.
# default: 900
DPOP_NONCE_EXP=900
#####################################
########## DYNAMIC CLIENTS ##########
#####################################
# If set to `true`, dynamic client registration will be enabled.
# Only activate this, if you really need it and you know, what
# you are doing. The dynamic client registration without further
# restriction will allow anyone to register new clients, even
# bots and spammers, and this may create security issues, if not
# handled properly and your users just login blindly to any client
# they get redirected to.
# default: false
#ENABLE_DYN_CLIENT_REG=false
# If specified, this secret token will be expected during
# dynamic client registrations to be given as a
# `Bearer <DYN_CLIENT_REG_TOKEN>` token. Needs to be communicated
# in advance.
# default: <empty>
#DYN_CLIENT_REG_TOKEN=
# The default token lifetime in seconds for a dynamic client,
# that will be set during the registration.
# This value can be modified manually after registration via
# the Admin UI like for any other client.
# default: 1800
#DYN_CLIENT_DEFAULT_TOKEN_LIFETIME=1800
# If set to 'true', client secret and registration token will be
# automatically rotated each time a dynamic client updates itself
# via the PUT endpoint. This is the only way that secret rotation
# could be automated safely.
# However, this is not mandatory by RFC and it may lead to errors,
# if the dynamic clients are not implemented properly to check for
# and update their secrets after they have done a request.
# If you get into secret-problems with dynamic clients, you should
# update the client to check for new secrets, if this is under your
# control. If you cannot do anything about it, you might set this
# value to 'false' to disable secret rotation.
# default: true
#DYN_CLIENT_SECRET_AUTO_ROTATE=true
# This scheduler will be running in the background, if
# `ENABLE_DYN_CLIENT_REG=true`. It will auto-delete dynamic clients,
# that have been registered and not been used in the following
# `DYN_CLIENT_CLEANUP_THRES` hours.
# Since a dynamic client should be used right away, this should never
# be a problem with "real" clients, that are not bots or spammers.
#
# The interval is specified in minutes.
# default: 60
#DYN_CLIENT_CLEANUP_INTERVAL=60
# The threshold for newly registered dynamic clients cleanup, if
# not being used within this timeframe. This is a helper to keep
# the database clean, if you are not using any `DYN_CLIENT_REG_TOKEN`.
# The threshold should be specified in minutes. Any client, that has
# not been used within this time after the registration will be
# automatically deleted.
#
# Note: This scheduler will only run, if you have not set any
# `DYN_CLIENT_REG_TOKEN`.
#
# default: 60
#DYN_CLIENT_CLEANUP_MINUTES=60
# The rate-limiter timeout for dynamic client registration.
# This is the timeout in seconds which will prevent an IP from
# registering another dynamic client, if no `DYN_CLIENT_REG_TOKEN`
# is set. With a `DYN_CLIENT_REG_TOKEN`, the rate-limiter will not
# be applied.
# default: 60
#DYN_CLIENT_RATE_LIMIT_SEC=60
#####################################
############# E-MAIL ################
#####################################
# This contact information will be added to the `rauthy`client
# within the anti lockout rule with each new restart.
RAUTHY_ADMIN_EMAIL="admin@localhost.de"
# Will be used as the prefix for the E-Mail subject for each E-Mail
# that will be sent out to a client.
# This can be used to further customize your deployment.
# default: "Rauthy IAM"
EMAIL_SUB_PREFIX="Rauthy IAM"
# Rauthy will force TLS and try a downgrade to STARTTLS, if
# TLS fails. It will never allow an unencrypted connection.
# You might want to set `SMTP_DANGER_INSECURE=true` if you
# need this for local dev.
#SMTP_URL=
#SMTP_USERNAME=
#SMTP_PASSWORD=
# Format: "Rauthy <rauthy@localhost.de>"
# default: "Rauthy <rauthy@localhost.de>"
#SMTP_FROM=
# The number of retries that should be done for connecting to
# the given SMTP_URL.
# When these retries are exceeded without success, Rauthy will
# panic and exit, so no E-Mail can get lost silently because of
# a missing SMTP connection.
# default: 3
#SMTP_CONNECT_RETRIES=3
# You can set this to `true` to allow an unencrypted and
# unauthenticated SMTP connection to an SMTP relay on your localhost
# or for development purposes.
# When set to `true`, `SMTP_USERNAME` and `SMTP_PASSWORD` will be
# ignored and you can modify the target port with
# `SMTP_DANGER_INSECURE_PORT`.
# default: false
#SMTP_DANGER_INSECURE=false
# The port for an insecure SMTP relay.
# This will most likely be used for testing only.
# It will only be taken into account if `SMTP_DANGER_INSECURE=true` is set.
# default: 1025
#SMTP_DANGER_INSECURE_PORT=1025
#####################################
###### ENCRYPTION / HASHING #########
#####################################
# You need to define at least one valid encryption key.
# These keys are used in various places, like for instance
# encrypting confidential client secrets in the database, or
# encryption cookies, and so on.
#
# The format must match:
# ENC_KEYS="
# q6u26onRvXVG4427/M0NFQzhSSldCY01rckJNa1JYZ3g2NUFtSnNOVGdoU0E=
# bVCyTsGaggVy5yqQ/UzluN29DZW41M3hTSkx6Y3NtZmRuQkR2TnJxUTYzcjQ=
# "
#
# The first part until the first `/` is the key ID.
# The ID must match '[a-zA-Z0-9]{2,20}'
#
# The key itself begins after the first `/` has been found.
# The key must be exactly 32 bytes long, encoded as base64.
#
# You can find a more detailed explanation on how to generate
# keys in the documentation:
# 1. https://sebadob.github.io/rauthy/getting_started/k8s.html#create-and-apply-secrets
# 2. https://sebadob.github.io/rauthy/config/encryption.html
#
# You can provide multiple keys to make things like key
# rotation work. Be careful with removing old keys. Make sure
# that all secrets have been migrated beforehand.
# You can find a utility in the Admin UI to do this for you.
#
#ENC_KEYS="
#q6u26onRvXVG4427/M0NFQzhSSldCY01rckJNa1JYZ3g2NUFtSnNOVGdoU0E=
#bVCyTsGaggVy5yqQ/UzluN29DZW41M3hTSkx6Y3NtZmRuQkR2TnJxUTYzcjQ=
#"
# This identifies the key ID from the `ENC_KEYS` list, that
# should actively be used for new encryptions.
ENC_KEY_ACTIVE=bVCyTsGaggVy5yqQ
# Argon2ID hashing parameters. Take a look at the documention
# for more information:
# https://sebadob.github.io/rauthy/config/argon2.html
# M_COST should never be below 32768 in production
ARGON2_M_COST=32768
# T_COST should never be below 1 in production
ARGON2_T_COST=3
# P_COST should never be below 2 in production
ARGON2_P_COST=2
# Limits the maximum amount of parallel password hashes at
# the exact same time to never exceed system memory while
# still allowing a good amount of memory for the argon2id
# algorithm (default: 2)
#
# CAUTION: You must make sure, that you have at least
# (MAX_HASH_THREADS * ARGON2_M_COST / 1024) + ~30 MB of memory
# available.
MAX_HASH_THREADS=1
# The time in ms when to log a warning, if a request waited
# longer than this time. This is an indicator, that you have
# more concurrent logins than allowed and may need config
# adjustments,
# if this happens more often. (default: 500)
#HASH_AWAIT_WARN_TIME=500
# JWKS auto rotate cronjob. This will (by default) rotate
# all JWKs every 1. day of the month. If you need smaller
# intervals, you may adjust this value. For security reasons,
# you cannot fully disable it.
# In a HA deployment, this job will only be executed on the
# current cache leader at that time.
# Format: "sec min hour day_of_month month day_of_week year"
# default: "0 30 3 1 * * *"
#JWK_AUTOROTATE_CRON="0 30 3 1 * * *"
#####################################
####### EPHEMERAL CLIENTS ###########
#####################################
# Can be set to 'true' to allow the dynamic client lookup via URLs as
# 'client_id's during authorization_code flow initiation.
# default: false
#ENABLE_EPHEMERAL_CLIENTS=false
# Can be set to 'true' to enable WebID functionality like needed
# for things like Solid OIDC.
# default: false
#ENABLE_WEB_ID=false
# If set to 'true', 'solid' will be added to the 'aud' claim from the ID token
# for ephemeral clients.
# default: false
#ENABLE_SOLID_AUD=false
# If set to 'true', MFA / Passkeys will be forced for ephemeral clients.
# default: false
#EPHEMERAL_CLIENTS_FORCE_MFA=false
# The allowed flows separated by ' ' for ephemeral clients.
# default: "authorization_code"
#EPHEMERAL_CLIENTS_ALLOWED_FLOWS="authorization_code refresh_token"
# The allowed scopes separated by ' ' for ephemeral clients.
# default: "openid profile email webid"
#EPHEMERAL_CLIENTS_ALLOWED_SCOPES="openid profile email webid"
# The lifetime in seconds ephemeral clients will be kept inside the cache.
# default: 3600
#EPHEMERAL_CLIENTS_CACHE_LIFETIME=3600
#####################################
######### EVENTS / AUDIT ############
#####################################
# The E-Mail address event notifications should be sent to.
#EVENT_EMAIL=admin@localhost.de
# Matrix variables for event notifications.
# `EVENT_MATRIX_USER_ID` and `EVENT_MATRIX_ROOM_ID` are mandatory.
# Depending on your Matrix setup, additionally one of
# `EVENT_MATRIX_ACCESS_TOKEN` or `EVENT_MATRIX_USER_PASSWORD` is needed.
# If you log in to Matrix with User + Password, you may use `EVENT_MATRIX_USER_PASSWORD`.
# If you log in via OIDC SSO (or just want to use a session token you can revoke),
# you should provide `EVENT_MATRIX_ACCESS_TOKEN`.
# If both are given, the `EVENT_MATRIX_ACCESS_TOKEN` will be preferred.
#
# If left empty, no messages will be sent to Slack.
# Format: `@<user_id>:<server address>`
#EVENT_MATRIX_USER_ID=
# Format: `!<random string>:<server address>`
#EVENT_MATRIX_ROOM_ID=
#EVENT_MATRIX_ACCESS_TOKEN=
#EVENT_MATRIX_USER_PASSWORD=
# Optional path to a PEM Root CA certificate file for the Matrix client.
#EVENT_MATRIX_ROOT_CA_PATH=path/to/my/root_ca_cert.pem
# May be set to disable the TLS validation for the Matrix client.
# default: false
#EVENT_MATRIX_DANGER_DISABLE_TLS_VALIDATION=false
# The default behavior is, that Rauthy will panic at startup if it cannot connect
# to a configured Matrix server. The reason is that event notifications cannot be
# dropped silently.
# However, if you use a self-hosted Matrix server which uses Rauthy as its OIDC
# provider and both instances went offline, you will have a chicken and egg problem:
# - Rauthy cannot connect to Matrix and will panic
# - Your Matrix server cannot connect to Rauthy and will panic
# To solve this issue, you can temporarily set this value to 'true' and revert
# back, after the system is online again.
# default: false
#EVENT_MATRIX_ERROR_NO_PANIC=false
# The Webhook for Slack Notifications.
# If left empty, no messages will be sent to Slack.
#EVENT_SLACK_WEBHOOK=
# The notification level for events. Works the same way as a logging level.
# For instance: 'notice' means send out a notifications for all events with
# the info level or higher.
# Possible values:
# - info
# - notice
# - warning
# - critical
#
# default: 'warning'
EVENT_NOTIFY_LEVEL_EMAIL=warning
# default: 'notice'
EVENT_NOTIFY_LEVEL_MATRIX=notice
# default: 'notice'
EVENT_NOTIFY_LEVEL_SLACK=notice
# Define the level from which on events should be persisted inside the
# database. All events with a lower level will be lost, if there is no
# active event subscriber.
# Possible values:
# - info
# - notice
# - warning
# - critical
# default: 'info'
#EVENT_PERSIST_LEVEL=info
# Define the number of days when events should be cleaned up from the database.
# default: 31
#EVENT_CLEANUP_DAYS=31
# The level for the generated Event after a new user has been registered.
# default: info
EVENT_LEVEL_NEW_USER=info
# The level for the generated Event after a user has changed his E-Mail
# default: notice
EVENT_LEVEL_USER_EMAIL_CHANGE=notice
# The level for the generated Event after a user has reset its password
# default: notice
EVENT_LEVEL_USER_PASSWORD_RESET=notice
# The level for the generated Event after a user has been given the
# 'rauthy_admin' role
# default: notice
EVENT_LEVEL_RAUTHY_ADMIN=notice
# The level for the generated Event after a new App version has been found
# default: notice
EVENT_LEVEL_RAUTHY_VERSION=notice
# The level for the generated Event after the JWKS has been rotated
# default: notice
EVENT_LEVEL_JWKS_ROTATE=notice
# The level for the generated Event after DB secrets have been migrated
# to a new key
# default: notice
EVENT_LEVEL_SECRETS_MIGRATED=notice
# The level for the generated Event after a Rauthy instance has been
# started
# default: info
EVENT_LEVEL_RAUTHY_START=info
# The level for the generated Event after a Rauthy entered a healthy
# state (again)
# default: notice
EVENT_LEVEL_RAUTHY_HEALTHY=notice
# The level for the generated Event after a Rauthy entered an unhealthy
#state
# default: critical
EVENT_LEVEL_RAUTHY_UNHEALTHY=critical
# The level for the generated Event after an IP has been blacklisted
# default: warning
EVENT_LEVEL_IP_BLACKLISTED=warning
# The level for the generated Event after certain amounts of false
# logins from an IP
# default: critical
EVENT_LEVEL_FAILED_LOGINS_25=critical
# default: critical
EVENT_LEVEL_FAILED_LOGINS_20=critical
# default: warning
EVENT_LEVEL_FAILED_LOGINS_15=warning
# default: warning
EVENT_LEVEL_FAILED_LOGINS_10=warning
# default: notice
EVENT_LEVEL_FAILED_LOGINS_7=notice
# default: info
EVENT_LEVEL_FAILED_LOGIN=info
# If set to 'true', it will disable the app version checker.
# This is a scheduled task that looks up the latest version periodically
# by doing a request to the Github API to check the latest release.
# This ignores any type of prerelease and will only notify for a new stable.
# default: false
#DISABLE_APP_VERSION_CHECK=false
#####################################
####### LIFETIMES / TIMEOUTS ########
#####################################
# Set the grace time in seconds for how long in seconds the
# refresh token should still be valid after usage. Keep this
# value small, but do not set it to 0 with an HA deployment
# to not get issues with small HA cache latencies.
#
# If you have an external client, which does concurrent
# requests, from which the request interceptor wants to refresh
# the token, you may have multiple hits on the endpoint and all
# of them should be valid.
#
# Caching is done on the endpoint itself, but grace time of 0
# will only be good for a single instance of rauthy.
# default: 5
#REFRESH_TOKEN_GRACE_TIME=5
# Session lifetime in seconds - the session can not be
# extended beyond this time and a new login will be forced.
# This is the session for the authorization code flow. (default: 14400)
#SESSION_LIFETIME=14400
# If 'true', a 2FA / MFA check will be done with each automatic
# token generation, even with an active session, which kind of
# makes the session useless with Webauthn enabled, but provides
# maximum amount of security.
# If 'false', the user will not get a MFA prompt with an active
# session at the authorization endpoint.
# (default: false)
#SESSION_RENEW_MFA=false
# Session timeout in seconds
# When a new token / login is requested before this timeout hits
# the limit, the user will be authenticated without prompting for
# the credentials again.
# This is the value which can extend the session, until it hits
# its maximum lifetime set with SESSION_LIFETIME.
#SESSION_TIMEOUT=5400
# ML: magic link
# LT: lifetime
# Lifetime in minutes for reset password magic links (default: 30)
#ML_LT_PWD_RESET=30
# Lifetime in minutes for the first password magic link, for
# setting the initial password. (default: 4320)
#ML_LT_PWD_FIRST=4320
#####################################
############# LOGGING ###############
#####################################
# This is the log level for stdout logs
# Accepts: error, info, debug, trace (default: info)
#LOG_LEVEL=info
# This is a special config which allows the configuration of
# customized access logs. These logs will be logged with each
# request in addition to the normal LOG_LEVEL logs.
# The following values are valid:
# - Debug
# CAUTION: The Debug setting logs every information available
# to the middleware which includes SENSITIVE HEADERS
# DO NOT use the Debug level in a working production environment!
# - Verbose
# Verbose logging without headers - generates huge outputs
# - Basic
# Logs access to all endpoints apart from the Frontend ones
# which all js, css, ...
# - Modifying
# Logs only requests to modifying endpoints and skips all GET
# - Off
# default: Modifying
#LOG_LEVEL_ACCESS=Basic
#####################################
################ MFA ################
#####################################
# If 'true', MFA for an account must be enabled to access the
# rauthy admin UI (default: true)
#ADMIN_FORCE_MFA=true
#####################################
############## POW #################
#####################################
# The difficulty for a Proof-of-Work (PoW).
# The default is 20, which is reasonable for modern processors.
# This is currently only used for the user registration via UI.
# The value must be between 10 and 99.
# default: 20
POW_DIFFICULTY=20
# The expiration duration in seconds for a PoW
# default: 30
POW_EXP=30
#####################################
############# SERVER ################
#####################################
# The server address to listen on. Can bind to a specific IP.
# default: 0.0.0.0
#LISTEN_ADDRESS=0.0.0.0
# The listen ports for HTTP / HTTPS, depending on the
# activated 'LISTEN_SCHEME'
# default: 8080
#LISTEN_PORT_HTTP=8080
# default: 8443
#LISTEN_PORT_HTTPS=8443
# The scheme to use locally, valid values:
# http | https | http_https (default: http_https)
LISTEN_SCHEME=http
# The Public URL of the whole deployment
# The LISTEN_SCHEME + PUB_URL must match the HTTP ORIGIN
# HEADER later on, which is especially important when running
# rauthy behind a reverse proxy. In case of a non-standard
# port (80/443), you need to add the port to the PUB_URL
PUB_URL=localhost:8080
# default value: number of available physical cores
#HTTP_WORKERS=1
# When rauthy is running behind a reverse proxy, set to true
# default: false
PROXY_MODE=false
# To enable or disable the additional HTTP server to expose the /metrics endpoint
# default: true
#METRICS_ENABLE=true
# The IP address to listen on for the /metrics endpoint.
# You do not want to expose your metrics on a publicly reachable endpoint!
# default: 0.0.0.0
#METRICS_ADDR=0.0.0.0
# The post to listen on for the /metrics endpoint.
# You do not want to expose your metrics on a publicly reachable endpoint!
# default: 9090
#METRICS_PORT=9090
# If the Swagger UI should be served together with the /metrics route on the internal
# server. It it then reachable via:
# http://METRICS_ADDR:METRICS_PORT/docs/v1/swagger-ui/
# default: true
#SWAGGER_UI_INTERNAL=true
# If the Swagger UI should be served externally as well. This makes the link in the
# Admin UI work.
#
# CAUTION: The Swagger UI is open and does not require any login to be seen!
# Rauthy is open source, which means anyone could just download it and see on their
# own, but it may be a security concern to just expose less information.
# default: false
#SWAGGER_UI_EXTERNAL=false
# The interval in seconds in which keep-alives should be sent to SSE clients.
# Depending on your network setup, proxy timeouts, ...
# you may adjust this value to fit your needs.
# default: 30
#SSE_KEEP_ALIVE=30
#####################################
############ TEMPLATES ##############
#####################################
# You can overwrite some default email templating values here.
# If you want to modify the basic templates themselves, this is
# currently only possible with a custom build from source.
# The content however can mostly be set here.
# If the below values are not set, the default will be taken.
# New Password E-Mail
#TPL_EN_PASSWORD_NEW_SUBJECT="New Password"
#TPL_EN_PASSWORD_NEW_HEADER="New password for"
#TPL_EN_PASSWORD_NEW_TEXT=""
#TPL_EN_PASSWORD_NEW_CLICK_LINK="Click the link below to get forwarded to the password form."
#TPL_EN_PASSWORD_NEW_VALIDITY="This link is only valid for a short period of time for security reasons."
#TPL_EN_PASSWORD_NEW_EXPIRES="Link expires:"
#TPL_EN_PASSWORD_NEW_BUTTON="Set Password"
#TPL_EN_PASSWORD_NEW_FOOTER=""
#TPL_DE_PASSWORD_NEW_SUBJECT="Passwort Reset angefordert"
#TPL_DE_PASSWORD_NEW_HEADER="Passwort Reset angefordert für"
#TPL_DE_PASSWORD_NEW_TEXT=""
#TPL_DE_PASSWORD_NEW_CLICK_LINK="Klicken Sie auf den unten stehenden Link für den Passwort Reset."
#TPL_DE_PASSWORD_NEW_VALIDITY="Dieser Link ist aus Sicherheitsgründen nur für kurze Zeit gültig."
#TPL_DE_PASSWORD_NEW_EXPIRES="Link gültig bis:"
#TPL_DE_PASSWORD_NEW_BUTTON="Passwort Setzen"
#TPL_DE_PASSWORD_NEW_FOOTER=""
# Password Reset E-Mail
#TPL_EN_RESET_SUBJECT="Neues Passwort"
#TPL_EN_RESET_HEADER="Neues Passwort für"
#TPL_EN_RESET_TEXT=""
#TPL_EN_RESET_CLICK_LINK="Klicken Sie auf den unten stehenden Link um ein neues Passwort zu setzen."
#TPL_EN_RESET_VALIDITY="This link is only valid for a short period of time for security reasons."
#TPL_EN_RESET_EXPIRES="Link expires:"
#TPL_EN_RESET_BUTTON="Reset Password"
#TPL_EN_RESET_FOOTER=""
#TPL_DE_RESET_SUBJECT="Passwort Reset angefordert"
#TPL_DE_RESET_HEADER="Passwort Reset angefordert für"
#TPL_DE_RESET_TEXT=""
#TPL_DE_RESET_CLICK_LINK="Klicken Sie auf den unten stehenden Link für den Passwort Reset."
#TPL_DE_RESET_VALIDITY="Dieser Link ist aus Sicherheitsgründen nur für kurze Zeit gültig."
#TPL_DE_RESET_EXPIRES="Link gültig bis:"
#TPL_DE_RESET_BUTTON="Passwort Zurücksetzen"
#TPL_DE_RESET_FOOTER=""
#####################################
############### TLS #################
#####################################
## Rauthy TLS
# Overwrite the path to the TLS certificate file in PEM
# format for rauthy (default: tls/tls.crt)
#TLS_CERT=tls/tls.crt
# Overwrite the path to the TLS private key file in PEM
# format for rauthy. If the path / filename ends with
# '.der', rauthy will parse it as DER, otherwise as PEM.
# (default: tls/tls.key)
#TLS_KEY=tls/tls.key
## CACHE TLS
# Enable / disable TLS for the cache communication
# (default: true)
CACHE_TLS=true
# The path to the server TLS certificate PEM file
# default: tls/redhac.cert-chain.pem
CACHE_TLS_SERVER_CERT=tls/cert-chain.pem
# The path to the server TLS key PEM file
# default: tls/redhac.key.pem
CACHE_TLS_SERVER_KEY=tls/key.pem
# The path to the client mTLS certificate PEM file. This is optional.
#CACHE_TLS_CLIENT_CERT=tls/cert-chain.pem
# The path to the client mTLS key PEM file. This is optional.
#CACHE_TLS_CLIENT_KEY=tls/key.pem
# If not empty, the PEM file from the specified location will be
# added as the CA certificate chain for validating
# the servers TLS certificate. This is optional.
#CACHE_TLS_CA_SERVER=tls/ca-chain.pem
# If not empty, the PEM file from the specified location will
# be added as the CA certificate chain for validating
# the clients mTLS certificate. This is optional.
#CACHE_TLS_CA_CLIENT=tls/ca-chain.pem
# The domain / CN the client should validate the certificate
# against. This domain MUST be inside the
# 'X509v3 Subject Alternative Name' when you take a look at
# the servers certificate with the openssl tool.
# default: redhac.local
CACHE_TLS_CLIENT_VALIDATE_DOMAIN=redhac.local
# Can be used if you need to overwrite the SNI when the
# client connects to the server, for instance if you are
# behind a loadbalancer which combines multiple certificates.
# default: ""
#CACHE_TLS_SNI_OVERWRITE=
#####################################
############# WEBAUTHN ##############
#####################################
# The 'Relaying Party (RP) ID' - effective domain name
# (default: localhost)
# CAUTION: When this changes, already registered devices will stop
# working and users cannot log in anymore!
RP_ID=localhost
# Url containing the effective domain name
# (default: http://localhost:8080)
# CAUTION: Must include the port number!
RP_ORIGIN=http://localhost:8080
# Non critical RP Name
# Has no security properties and may be changed without issues
# (default: Rauthy Webauthn)
RP_NAME='Rauthy Webauthn'
# The Cache lifetime in seconds for Webauthn requests. Within
# this time, a webauthn request must have been validated.
# (default: 60)
#WEBAUTHN_REQ_EXP=60
# The Cache lifetime for additional Webauthn Data like auth
# codes and so on. Should not be lower than WEBAUTHN_REQ_EXP.
# The value is in seconds (default: 90)
#WEBAUTHN_DATA_EXP=90
# With webauthn enabled for a user, he needs to enter
# username / password on a new system. If these credentials are
# verified, rauthy will set an additional cookie, which will
# determine how long the user can then use only (safe) MFA
# passwordless webauthn login with yubikeys, apple touch id,
# Windows hello, ... until he needs to verify his credentials
# again.
# Passwordless login is generally much safer than logging in
# with a password. But sometimes it is possible, that the
# Webauthn devices do not force the user to include a second
# factor, which in that case would be a single factor login
# again. That is why we should ask for the original password
# in addition once in a while to set the cookie.
# The value is in hours (default: 2160)
#WEBAUTHN_RENEW_EXP=2160
# This feature can be set to 'true' to force User verification
# during the Webauthn ceremony. UV will be true, if the user
# does not only need to verify its presence by touching the key,
# but by also providing proof that he knows (or is) some secret
# via a PIN or biometric key for instance. With UV, we have a
# true MFA scenario where UV == false (user presence only)
# would be a 2FA scenario (with password). Be careful with this
# option, since Android and some special combinations of OS +
# browser to not support UV yet.
# (default: false)
#WEBAUTHN_FORCE_UV=false
# Can be set to 'true' to disable password expiry for users
# that have at least one active passkey. When set to 'false',
# the same password expiry from the set policy will apply to
# these users as well.
# With this option active, rauthy will ignore any password
# expiry set by the password policy for Webauthn users.
# default: true
#WEBAUTHN_NO_PASSWORD_EXPIRY=true