Document PasswordEncoder
This commit is contained in:
Rob Winch
parent
691bf2e11d
commit
cd1a02225b
|
|
@ -0,0 +1,295 @@
|
|||
[[core-services-password-encoding]]
|
||||
= Password Encoding
|
||||
|
||||
Spring Security's `PasswordEncoder` interface is used to perform a one way transformation of a password to allow the password to be stored securely.
|
||||
Given `PasswordEncoder` is a one way transformation, it is not intended when the password transformation needs to be two way (i.e. storing credentials used to authenticate to a database).
|
||||
Typically `PasswordEncoder` is used for storing a password that needs to be compared to a user provided password at the time of authentication.
|
||||
|
||||
[[pe-history]]
|
||||
== Password History
|
||||
|
||||
Throughout the years the standard mechanism for storing passwords has evolved.
|
||||
In the beginning passwords were stored in plain text.
|
||||
The passwords were assumed to be safe because the data store the passwords were saved in required credentials to access it.
|
||||
However, malicious users were able to find ways to get large "data dumps" of usernames and passwords using attacks like SQL Injection.
|
||||
As more and more user credentials became public security experts realized we needed to do more to protect users passwords.
|
||||
|
||||
Developers were then encouraged to store passwords after running them through a one way hash such as SHA-256.
|
||||
When a user tried to authenticate, the hashed password would be compared to the hash of the password that they typed.
|
||||
This meant that the system only needed to store the one way hash of the password.
|
||||
If a breach occurred, then only the one way hashes of the passwords were exposed.
|
||||
Since the hashes were one way and it was computationally difficult to guess the passwords given the hash, it would not be worth the effort to figure out each password in the system.
|
||||
To defeat this new system malicious users decided to create lookup tables known as https://en.wikipedia.org/wiki/Rainbow_table[Rainbow Tables].
|
||||
Rather than doing the work of guessing each password every time, they computed the password once and stored it in a lookup table.
|
||||
|
||||
To mitigate the effectiveness of Rainbow Tables, developers were encouraged to use salted passwords.
|
||||
Instead of using just the password as input to the hash function, random bytes (known as salt) would be generated for every users' password.
|
||||
The salt and the user's password would be ran through the hash function which produced a unique hash.
|
||||
The salt would be stored alongside the user's password in clear text.
|
||||
Then when a user tried to authenticate, the hashed password would be compared to the hash of the stored salt and the password that they typed.
|
||||
The unique salt meant that Rainbow Tables were no longer effective because the hash was different for every salt and password combination.
|
||||
|
||||
In modern times we realize that cryptographic hashes (like SHA-256) are no longer secure.
|
||||
The reason is that with modern hardware we can perform billions of hash calculations a second.
|
||||
This means that we can crack each password individually with ease.
|
||||
|
||||
Developers are now encouraged to leverage adaptive one-way functions to store a password.
|
||||
An adaptive one-way function allows configuring a "work factor" which can grow as hardware gets better.
|
||||
It is recommended that the "work factor" be tuned to take about 1 second to verify a password on your system.
|
||||
This trade off is to make it difficult for attackers to crack the password, but not so costly it puts excessive burden on your own system.
|
||||
Examples of adaptive one-way functions that should be used include
|
||||
https://en.wikipedia.org/wiki/Bcrypt[bcrypt],
|
||||
https://en.wikipedia.org/wiki/PBKDF2[PBKDF2],
|
||||
https://en.wikipedia.org/wiki/Scrypt[scrypt],
|
||||
and https://en.wikipedia.org/wiki/Argon2[Argon2].
|
||||
|
||||
[[pe-dpe]]
|
||||
== DelegatingPasswordEncoder
|
||||
|
||||
Prior to Spring Security 5.0 the default `PasswordEncoder` was `NoOpPasswordEncoder` which required plain text passwords.
|
||||
Based upon the <<password-history,Password History>> section you might expect that the default `PasswordEncoder` is now something like `BCryptPasswordEncoder`.
|
||||
However, this ignores three real world problems:
|
||||
|
||||
- There are many applications using old password encodings that cannot easily migrate
|
||||
- The best practice for password storage will change again.
|
||||
- As a framework Spring Security cannot make breaking changes frequently
|
||||
|
||||
Instead Spring Security introduces `DelegatingPasswordEncoder` which solves all of the problems by:
|
||||
|
||||
- Ensuring that passwords are encoded using the current password storage recommendations
|
||||
- Allowing for validating passwords in modern and legacy formats
|
||||
- Allowing for upgrading the encoding in the future
|
||||
|
||||
You can easily construct an instance of `DelegatingPasswordEncoder` using `PasswordEncoderFactories`.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
PasswordEncoder passwordEncoder =
|
||||
PasswordEncoderFactories.createDelegatingPasswordEncoder();
|
||||
----
|
||||
|
||||
Alternatively, you may create your own custom instance. For example:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
String idForEncode = "bcrypt";
|
||||
Map encoders = new HashMap<>();
|
||||
encoders.put(idForEncode, new BCryptPasswordEncoder());
|
||||
encoders.put("noop", NoOpPasswordEncoder.getInstance());
|
||||
encoders.put("pbkdf2", new Pbkdf2PasswordEncoder());
|
||||
encoders.put("scrypt", new SCryptPasswordEncoder());
|
||||
encoders.put("sha256", new StandardPasswordEncoder());
|
||||
|
||||
PasswordEncoder passwordEncoder =
|
||||
new DelegatingPasswordEncoder(idForEncode, encoders);
|
||||
----
|
||||
|
||||
[[pe-dpe-format]]
|
||||
=== Password Storage Format
|
||||
|
||||
The general format for a password is:
|
||||
|
||||
[source,text]
|
||||
----
|
||||
{id}encodedPassword
|
||||
----
|
||||
|
||||
Such that `id` is an identifier used to look up which `PasswordEncoder` should be used and `encodedPassword` is the original encoded password for the selected `PasswordEncoder`.
|
||||
The `id` must be at the beginning of the password, start with `{` and end with `}`.
|
||||
If the `id` cannot be found, the `id` will be null.
|
||||
For example, the following might be a list of passwords encoded using different `id`.
|
||||
All of the original passwords are "password".
|
||||
|
||||
|
||||
[source,text]
|
||||
----
|
||||
{bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG // <1>
|
||||
{noop}password // <2>
|
||||
{pbkdf2}5d923b44a6d129f3ddf3e3c8d29412723dcbde72445e8ef6bf3b508fbf17fa4ed4d6b99ca763d8dc // <3>
|
||||
{scrypt}$e0801$8bWJaSu2IKSn9Z9kM+TPXfOc/9bdYSrN1oD9qfVThWEwdRTnO7re7Ei+fUZRJ68k9lTyuTeUp4of4g24hHnazw==$OAOec05+bXxvuu/1qZ6NUR+xQYvYv7BeL1QxwRpY5Pc= // <4>
|
||||
{sha256}97cde38028ad898ebc02e690819fa220e88c62e0699403e94fff291cfffaf8410849f27605abcbc0 // <5>
|
||||
----
|
||||
|
||||
<1> The first password would have a `PasswordEncoder` id of `bcrypt` and encodedPassword of `$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG`.
|
||||
When matching it would delegate to `BCryptPasswordEncoder`
|
||||
<2> The second password would have a `PasswordEncoder` id of `noop` and encodedPassword of `password`.
|
||||
When matching it would delegate to `NoOpPasswordEncoder`
|
||||
<3> The third password would have a `PasswordEncoder` id of `pbkdf2` and encodedPassword of `5d923b44a6d129f3ddf3e3c8d29412723dcbde72445e8ef6bf3b508fbf17fa4ed4d6b99ca763d8dc`.
|
||||
When matching it would delegate to `Pbkdf2PasswordEncoder`
|
||||
<4> The fourth password would have a `PasswordEncoder` id of `scrypt` and encodedPassword of `$e0801$8bWJaSu2IKSn9Z9kM+TPXfOc/9bdYSrN1oD9qfVThWEwdRTnO7re7Ei+fUZRJ68k9lTyuTeUp4of4g24hHnazw==$OAOec05+bXxvuu/1qZ6NUR+xQYvYv7BeL1QxwRpY5Pc=`
|
||||
When matching it would delegate to `SCryptPasswordEncoder`
|
||||
<5> The final password would have a `PasswordEncoder` id of `sha256` and encodedPassword of `97cde38028ad898ebc02e690819fa220e88c62e0699403e94fff291cfffaf8410849f27605abcbc0`.
|
||||
When matching it would delegate to `StandardPasswordEncoder`
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Some users might be concerned that the storage format is provided for a potential hacker.
|
||||
This is not a concern because the storage of the password does not rely on the algorithm being a secret.
|
||||
Additionally, most formats are easy for an attacker to figure out without the prefix.
|
||||
For example, BCrypt passwords often start with `$2a$`.
|
||||
====
|
||||
|
||||
=== Password Encoding
|
||||
|
||||
The `idForEncode` passed into the constructor determines which `PasswordEncoder` will be used for encoding passwords.
|
||||
In the `DelegatingPasswordEncoder` we constructed above, that means that the result of encoding `password` would be delegated to `BCryptPasswordEncoder` and be prefixed with `{bcrypt}`.
|
||||
The end result would look like:
|
||||
|
||||
[source,text]
|
||||
----
|
||||
{bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
|
||||
----
|
||||
|
||||
=== Password Matching
|
||||
|
||||
Matching is done based upon the `{id}` and the mapping of the `id` to the `PasswordEncoder` provided in the constructor.
|
||||
Our example in <<Password Storage Format>> provides a working example of how this is done.
|
||||
By default, the result of invoking `matches(CharSequence, String)` with a password and an `id` that is not mapped (including a null id) will result in an `IllegalArgumentException`.
|
||||
This behavior can be customized using `DelegatingPasswordEncoder.setDefaultPasswordEncoderForMatches(PasswordEncoder)`.
|
||||
|
||||
By using the `id` we can match on any password encoding, but encode passwords using the most modern password encoding.
|
||||
This is important, because unlike encryption, password hashes are designed so that there is no simple way to recover the plaintext.
|
||||
Since there is no way to recover the plaintext, it makes it difficult to migrate the passwords.
|
||||
While it is simple for users to migrate `NoOpPasswordEncoder`, we chose to include it by default to make it simple for the getting started experience.
|
||||
|
||||
=== Getting Started Experience
|
||||
|
||||
If you are putting together a demo or a sample, it is a bit cumbersome to take time to hash the passwords of your users.
|
||||
There are convenience mechanisms to make this easier, but this is still not intended for production.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
User user = User.withDefaultPasswordEncoder()
|
||||
.username("user")
|
||||
.password("password")
|
||||
.roles("user")
|
||||
.build();
|
||||
System.out.println(user.getPassword());
|
||||
// {bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
|
||||
----
|
||||
|
||||
If you are creating multiple users, you can also reuse the builder.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
UserBuilder users = User.withDefaultPasswordEncoder();
|
||||
User user = users
|
||||
.username("user")
|
||||
.password("password")
|
||||
.roles("USER")
|
||||
.build();
|
||||
User admin = users
|
||||
.username("admin")
|
||||
.password("password")
|
||||
.roles("USER","ADMIN")
|
||||
.build();
|
||||
----
|
||||
|
||||
This does hash the password that is stored, but the passwords are still exposed in memory and in the compiled source code.
|
||||
Therefore, it is still not considered secure for a production environment.
|
||||
For production, you should hash your passwords externally.
|
||||
|
||||
=== Troubleshooting
|
||||
|
||||
The following error occurs when one of the passwords that are stored has no id as described in <<pe-dpe-format>>.
|
||||
|
||||
----
|
||||
java.lang.IllegalArgumentException: There is no PasswordEncoder mapped for the id "null"
|
||||
at org.springframework.security.crypto.password.DelegatingPasswordEncoder$UnmappedIdPasswordEncoder.matches(DelegatingPasswordEncoder.java:233)
|
||||
at org.springframework.security.crypto.password.DelegatingPasswordEncoder.matches(DelegatingPasswordEncoder.java:196)
|
||||
----
|
||||
|
||||
The easiest way to resolve the error is to switch to explicitly provide the `PasswordEncoder` that you passwords are encoded with.
|
||||
The easiest way to resolve it is to figure out how your passwords are currently being stored and explicitly provide the correct `PasswordEncoder`.
|
||||
If you are migrating from Spring Security 4.2.x you can revert to the previous behavior by exposing a `NoOpPasswordEncoder` bean.
|
||||
For example, if you are using Java Configuration, you can create a configuration that looks like:
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
Reverting to `NoOpPasswordEncoder` is not considered to be secure.
|
||||
You should instead migrate to using `DelegatingPasswordEncoder` to support secure password encoding.
|
||||
====
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public static NoOpPasswordEncoder passwordEncoder() {
|
||||
return NoOpPasswordEncoder.getInstance();
|
||||
}
|
||||
----
|
||||
|
||||
if you are using XML configuration, you can expose a `PasswordEncoder` with the id `passwordEncoder`:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<b:bean id="passwordEncoder"
|
||||
class="org.springframework.security.crypto.NoOpPasswordEncoder" factory-method="getInstance"/>
|
||||
----
|
||||
|
||||
Alternatively, you can prefix all of your passwords with the correct id and continue to use `DelegatingPasswordEncoder`.
|
||||
For example, if you are using BCrypt, you would migrate your password from something like:
|
||||
|
||||
----
|
||||
$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
|
||||
----
|
||||
|
||||
to
|
||||
|
||||
----
|
||||
{bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
|
||||
----
|
||||
|
||||
For a complete listing of the mappings refer to the Javadoc on
|
||||
https://docs.spring.io/spring-security/site/docs/5.0.x/api/org/springframework/security/crypto/factory/PasswordEncoderFactories.html[PasswordEncoderFactories].
|
||||
|
||||
[[pe-bcpe]]
|
||||
== BCryptPasswordEncoder
|
||||
|
||||
The `BCryptPasswordEncoder` implementation uses the widely supported https://en.wikipedia.org/wiki/Bcrypt[bcrypt] algorithm to hash the passwords.
|
||||
In order to make it more resistent to password cracking, bcrypt is deliberately slow.
|
||||
Like other adaptive one-way functions, it should be tuned to take about 1 second to verify a password on your system.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// Create an encoder with strength 16
|
||||
BCryptPasswordEncoder encoder = new BCryptPasswordEncoder(16);
|
||||
String result = encoder.encode("myPassword");
|
||||
assertTrue(encoder.matches("myPassword", result));
|
||||
----
|
||||
|
||||
[[pe-pbkdf2pe]]
|
||||
== Pbkdf2PasswordEncoder
|
||||
|
||||
The `Pbkdf2PasswordEncoder` implementation uses the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] algorithm to hash the passwords.
|
||||
In order to defeat password cracking PBKDF2 is a deliberately slow algorithm.
|
||||
Like other adaptive one-way functions, it should be tuned to take about 1 second to verify a password on your system.
|
||||
This algorithm is a good choice when FIPS certification is required.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// Create an encoder with all the defaults
|
||||
Pbkdf2PasswordEncoder encoder = new Pbkdf2PasswordEncoder();
|
||||
String result = encoder.encode("myPassword");
|
||||
assertTrue(encoder.matches("myPassword", result));
|
||||
----
|
||||
|
||||
[[pe-scpe]]
|
||||
== SCryptPasswordEncoder
|
||||
|
||||
The `SCryptPasswordEncoder` implementation uses https://en.wikipedia.org/wiki/Scrypt[scrypt] algorithm to hash the passwords.
|
||||
In order to defeat password cracking on custom hardware scrypt is a deliberately slow algorithm that requires large amounts of memory.
|
||||
Like other adaptive one-way functions, it should be tuned to take about 1 second to verify a password on your system.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// Create an encoder with all the defaults
|
||||
SCryptPasswordEncoder encoder = new SCryptPasswordEncoder();
|
||||
String result = encoder.encode("myPassword");
|
||||
assertTrue(encoder.matches("myPassword", result));
|
||||
----
|
||||
|
||||
== Other PasswordEncoders
|
||||
|
||||
There are a significant number of other `PasswordEncoder` implementations that exist entirely for backward compatibility.
|
||||
They are all deprecated to indicate that they are no longer considered secure.
|
||||
However, there are no plans to remove them since it is difficult to migrate existing legacy systems.
|
||||
|
|
@ -413,6 +413,7 @@ Below are the highlights of this milestone release.
|
|||
** <<jc-webflux,@EnableWebFluxSecurity>>
|
||||
** <<jc-erms,@EnableReactiveMethodSecurity>>
|
||||
** <<test-webflux,WebFlux Testing Support>>
|
||||
* Modernized <<core-services-password-encoding,Password Encoding>>
|
||||
|
||||
[[samples]]
|
||||
== Samples and Guides (Start Here)
|
||||
|
|
@ -3270,33 +3271,7 @@ You can use different relational database management systems by modifying the `D
|
|||
===== Authority Groups
|
||||
By default, `JdbcDaoImpl` loads the authorities for a single user with the assumption that the authorities are mapped directly to users (see the <<appendix-schema,database schema appendix>>). An alternative approach is to partition the authorities into groups and assign groups to the user. Some people prefer this approach as a means of administering user rights. See the `JdbcDaoImpl` Javadoc for more information on how to enable the use of group authorities. The group schema is also included in the appendix.
|
||||
|
||||
|
||||
[[core-services-password-encoding]]
|
||||
=== Password Encoding
|
||||
Spring Security's `PasswordEncoder` interface is used to support the use of passwords which are encoded in some way in persistent storage. You should never store passwords in plain text. Always use a one-way password hashing algorithm such as bcrypt which uses a built-in salt value which is different for each stored password. Do not use a plain hash function such as MD5 or SHA, or even a salted version. Bcrypt is deliberately designed to be slow and to hinder offline password cracking, whereas standard hash algorithms are fast and can easily be used to test thousands of passwords in parallel on custom hardware. You might think this doesn't apply to you since your password database is secure and offline attacks aren't a risk. If so, do some research and read up on all the high-profile sites which have been compromised in this way and have been pilloried for storing their passwords insecurely. It's best to be on the safe side. Using `org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder"` is a good choice for security. There are also compatible implementations in other common programming languages so it a good choice for interoperability too.
|
||||
|
||||
If you are using a legacy system which already has hashed passwords, then you will need to use an encoder which matches your current algorithm, at least until you can migrate your users to a more secure scheme (usually this will involve asking the user to set a new password, since hashes are irreversible). Spring Security has a package containing legacy password encoding implementation, namely, `org.springframework.security.authentication.encoding`. The `DaoAuthenticationProvider` can be injected with either the new or legacy `PasswordEncoder` types.
|
||||
|
||||
|
||||
==== What is a hash?
|
||||
Password hashing is not unique to Spring Security but is a common source of confusion for users who are not familiar with the concept. A hash (or digest) algorithm is a one-way function which produces a piece of fixed-length output data (the hash) from some input data, such as a password. As an example, the MD5 hash of the string "password" (in hexadecimal) is
|
||||
|
||||
[source,txt]
|
||||
----
|
||||
5f4dcc3b5aa765d61d8327deb882cf99
|
||||
----
|
||||
|
||||
A hash is "one-way" in the sense that it is very difficult (effectively impossible) to obtain the original input given the hash value, or indeed any possible input which would produce that hash value. This property makes hash values very useful for authentication purposes. They can be stored in your user database as an alternative to plaintext passwords and even if the values are compromised they do not immediately reveal a password which can be used to login. Note that this also means you have no way of recovering the password once it is encoded.
|
||||
|
||||
==== Adding Salt to a Hash
|
||||
One potential problem with the use of password hashes that it is relatively easy to get round the one-way property of the hash if a common word is used for the input. People tend to choose similar passwords and huge dictionaries of these from previously hacked sites are available online. For example, if you search for the hash value `5f4dcc3b5aa765d61d8327deb882cf99` using google, you will quickly find the original word "password". In a similar way, an attacker can build a dictionary of hashes from a standard word list and use this to lookup the original password. One way to help prevent this is to have a suitably strong password policy to try to prevent common words from being used. Another is to use a "salt" when calculating the hashes. This is an additional string of known data for each user which is combined with the password before calculating the hash. Ideally the data should be as random as possible, but in practice any salt value is usually preferable to none. Using a salt means that an attacker has to build a separate dictionary of hashes for each salt value, making the attack more complicated (but not impossible).
|
||||
|
||||
Bcrypt automatically generates a random salt value for each password when it is encoded, and stores it in the bcrypt string in a standard format.
|
||||
|
||||
==== Hashing and Authentication
|
||||
When an authentication provider (such as Spring Security's `DaoAuthenticationProvider`) needs to check the password in a submitted authentication request against the known value for a user, and the stored password is encoded in some way, then the submitted value must be encoded using exactly the same algorithm. It's up to you to check that these are compatible as Spring Security has no control over the persistent values. If you add password hashing to your authentication configuration in Spring Security, and your database contains plaintext passwords, then there is no way authentication can succeed. Even if you are aware that your database is using MD5 to encode the passwords, for example, and your application is configured to use Spring Security's `Md5PasswordEncoder`, there are still things that can go wrong. The database may have the passwords encoded in Base 64, for example while the encoder is using hexadecimal strings (the default). Alternatively your database may be using upper-case while the output from the encoder is lower-case. Make sure you write a test to check the output from your configured password encoder with a known password and salt combination and check that it matches the database value before going further and attempting to authenticate through your application. Using a standard like bcrypt will avoid these issues.
|
||||
|
||||
If you want to generate encoded passwords directly in Java for storage in your user database, then you can use the `encode` method on the `PasswordEncoder`.
|
||||
include::{include-dir}/password-encoder.adoc[leveloffset=+2]
|
||||
|
||||
include::{include-dir}/jackson.adoc[]
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue