In this chapter you can find information of how ZITADEL processes and stores secrets and credentials in a secure fashion.
We use the terms secret and credentials interchangeable to keep this guide lean.
ZITADEL uses the following principles when handling Secrets across their lifecycle:
- Automate rotation
- Limit lifetime
- Show only once
- Prefer public / private key concepts (FIDO2, U2F, JWT Profile, ...)
- Irreversible hash secrets / passwords
- Encrypt secrets storage
- When sent across unsecure channels (eMail, SMS, ...)
- Forced changed through receiver
- Verify that the secret can only be used once
By default ZITADEL stores secrets from its users, clients as well as its generated secrets like signing keys in the database. To protect the secrets against extraction from database as well as database dumps they are encrypted with AES256.
The key used to encrypt and decrypt the secrets in the ZITADEL database is called
masterkey and needs to be exactly 32 bytes long.
The only secrets stored outside of the Secrets Storage are the masterkey, the TLS Keys, the initial Admin User (including the password)
Secrets stored in the Secrets Storage
ZITADEL does handle many different public keys. These include:
- JWT Profile
- Signing Keys
Due to the inherent nature of a public key being public we safeguard them against malicious key changes with our unique eventstore concept.
ZITADEL does handle many different passwords and secrets. These include:
- User Authentication
- Client / Machine Authentication
- Client Secrets
bcrypt by default to store all Passwords and Client Secrets in an non reversible way to further reduce the risk of a Secrets Storage breach.
Some secrets cannot be hashed because they need to be used in their raw form. These include:
- Client Secrets of Identity Providers (IdPs)
- Multi Factor Authentication
- TOTP Seed Values
- Validation Secrets
- Verifying contact information like eMail, Phonenumbers
- Verifying proof of ownership over domain names (DNS)
- Resting accounts of users (password, MFA reset, ...)
- Private Keys
- Token Signing (JWT, ...)
- Token Encryption (Opaque Bearer Tokens)
- Useragent Cookies (Session Cookies) Encryption
- CSRF Cookie Encryption
- Mail Provider
- SMTP Passwords
- SMS Provider
- Twilio API Keys
By default ZITADEL uses
RSA256 for signing purposes and
AES256 for encryption
Secrets stored outside the Secrets Storage
Since the Masterkey is used as means of protecting the Secrets Storage it cannot be stored in the storage. You find here the many ways how ZITADEL can consume the Masterkey.
ZITADEL does support end to end TLS as such it can consume TLS Key Material. Please check our TLS Modes documentation for more details.
The initial Admin User of ZITADEL can be configured through ZITADELs config options.
To prevent elevated breaches ZITADEL forces the Admin Users password to be changed during the first login.