Password Property
Reference
The "Password" property (PasswordClass) stores a password value on an XClass. It has two storage types: "Clear" (stored as plain text) and "Hash" (stored as an irreversible hash). The "Encrypt" storage type that existed in older versions has been removed.
Supported Hash Algorithms
| Algorithm | Key | Notes |
|---|---|---|
| Argon2 | argon2 | XWiki 18.8.0+, 18.4.5+ Default algorithm. |
| BCrypt | bcrypt | Limited to 72 characters. |
| SCrypt | scrypt | |
| PBKDF2 | pbkdf2 | |
| SHA-1 | SHA-1 | Deprecated, kept for legacy passwords only. |
| SHA-256 | SHA-256 | Deprecated, kept for legacy passwords only. |
| SHA-512 | SHA-512 | Deprecated, was the previous default algorithm. |
The algorithm used for a given property is configured on the XClass and defaults to Argon2 when not set.
Encoded Password Format
A hashed password is stored as {algorithmKey}<hash>, e.g. {argon2}$argon2id$....
Passwords stored by versions prior to XWiki 18.8.0RC1, 18.4.5 use the legacy format hash:<algorithmName>:<salt>:<hash>. This format is still read and matched correctly, but is reported as outdated in the logs.
Checking and Setting a Password
Use BaseCollection#isPasswordValueMatching and BaseCollection#setPasswordValue to check or set a password on an XObject without handling the property class directly:
boolean matches = xobject.isPasswordValueMatching("password", rawPassword);
xobject.setPasswordValue("password", newRawPassword);PasswordClass#arePasswordsMatching(String, String) is available when working directly with a PasswordClass instance. PasswordClass#getEquivalentPassword is deprecated since in favor of arePasswordsMatching.
Migrating Existing Passwords
XWiki 18.4.5+, 18.8.0+ On upgrade to 18.8.0RC1, 18.4.5 or later, a data migration re-encodes every legacy (hash:-prefixed) password by wrapping it with Argon2, without needing the original raw password. Passwords already using a Spring Security algorithm are left untouched. A property still using a deprecated algorithm (or the legacy format) logs a warning until it is re-hashed, which happens automatically the next time the password is set (e.g. on password change).
FAQ
Why did the default algorithm change from SHA-512 to Argon2?
SHA-512 is a fast, unsalted-by-design digest not intended for password hashing; Argon2 is a modern, purpose-built password-hashing algorithm.
Is existing password data at risk during the upgrade?
No, the migration re-wraps legacy hashes without needing plaintext passwords; verification keeps working throughout.
What happened to the "Encrypt" storage type?
It has been removed; only "Clear" and "Hash" remain.
