TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2024-12-04 23:45:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(migrate): update password section (#8232)

Browse Source 
# Which Problems Are Solved

Password reset in combination of md5 was not clear

# How the Problems Are Solved

Some additional information in the docs
This commit is contained in:
mffap 2024-07-23 16:13:35 +02:00 committed by GitHub
parent f8b711ca5c
commit 91dcebbfc9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 29 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
cmd/defaults.yaml
View File

@ -453,12 +453,10 @@ SystemDefaults:
# Passwords previously hashed with a different algorithm
# or cost are automatically re-hashed using this config,
# upon password validation or update.
# Configure the Hasher config by environment variable using JSON notation:
# ZITADEL_SYSTEMDEFAULTS_PASSWORDHASHER_HASHER='{"Algorithm":"pbkdf2","Rounds":290000,"Hash":"sha256"}'
Hasher:
# Supported algorithms: "argon2i", "argon2id", "bcrypt", "scrypt", "pbkdf2"
# Depending on the algorithm, different configuration options take effect.
Algorithm: bcrypt
Algorithm: bcrypt # ZITADEL_SYSTEMDEFAULTS_PASSWORDHASHER_HASHER_ALGORITHM
# Cost takes effect for the algorithms bcrypt and scrypt
Cost: 14 # ZITADEL_SYSTEMDEFAULTS_PASSWORDHASHER_HASHER_COST
# Time takes effect for the algorithms argon2i and argon2id
@ -498,7 +496,7 @@ SystemDefaults:
Hasher:
# Supported algorithms: "argon2i", "argon2id", "bcrypt", "scrypt", "pbkdf2"
# Depending on the algorithm, different configuration options take effect.
Algorithm: bcrypt
Algorithm: bcrypt # ZITADEL_SYSTEMDEFAULTS_SECRETHASHER_HASHER_ALGORITHM
# Cost takes effect for the algorithms bcrypt and scrypt
Cost: 4 # ZITADEL_SYSTEMDEFAULTS_SECRETHASHER_HASHER_COST
# Time takes effect for the algorithms argon2i and argon2id

36
docs/docs/guides/migrate/users.md
View File

@ -129,11 +129,10 @@ The snippets in the sections below are parts from the bulk import endpoint, to c
### Passwords
Passwords are stored only as hash.
You can transfer the hashes as long as ZITADEL [supports the same hash algorithm](/docs/concepts/architecture/secrets#hashed-secrets).
Password change on the next sign-in can be enforced.
ZITADEL stores passwords only as irreversible hashes, never in clear text.
Existing password hashes can be imported if they use a supported [hash algorithm](/docs/concepts/architecture/secrets#hashed-secrets).
_snippet from [bulk-import](#bulk-import) example:_
Import password hashes using the import API (snippet from [bulk-import](#bulk-import)):
```json
{
"userName": "test9@test9",
@ -147,13 +146,32 @@ _snippet from [bulk-import](#bulk-import) example:_
}
```
Upon initial login, ZITADEL validates the imported password using the appropriate verifier.
:::info Verifiers
In ZITADEL, a password verifier checks the validity of a password hash created with an algorithm different from the currently configured one.
It acts as a translator, allowing ZITADEL to understand and validate hashes made with older algorithms like MD5 even when the system has transitioned to newer ones like Argon2.
This is crucial during migrations or when importing user data.
Essentially, a verifier ensures ZITADEL can work with passwords hashed using various algorithms, maintaining security while transitioning to stronger hashing methods.
:::
Regardless of the `passwordChangeRequired` setting, the password is rehashed using the configured hasher algorithm and stored.
This ensures consistency and allows for automatic updates even when hasher configurations are changed, such as increasing salt cost for bcrypt.
To configure the default hasher for new user passwords, set the `Algorithm` of the `PasswordHasher` in the [runtime configuration file](/docs/self-hosting/manage/configure#runtime-configuration-file)
or by the environment variable `ZITADEL_SYSTEMDEFAULTS_PASSWORDHASHER_HASHER_ALGORITHM`, for example:
```
ZITADEL_SYSTEMDEFAULTS_PASSWORDHASHER_HASHER_ALGORITHM='pbkdf2'
```
Hasher configuration updates will automatically rehash existing passwords when they are validated or changed.
In case the hashes can't be transferred directly, you always have the option to create a user in ZITADEL without password and prompt users to create a new password.
If your legacy system receives the passwords in clear text (eg, login form) you could also directly create users via ZITADEL API. We will explain this pattern in more detail in this guide.
:::info
In case the hash algorithm you are using is not supported by ZITADEL, please let us know after searching our discussions, issues, and chat for similar requests.
:::
If your legacy system receives the passwords in clear text (eg, login form) you could also directly create users via ZITADEL API.
We will explain this pattern in more detail in this guide.
### One-time-passwords (OTP)