Spring/spring-security
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch '5.8.x' into 6.0.x

Browse Source 
Closes gh-13406
This commit is contained in:
Rob Winch
2023-06-18 21:33:58 -05:00
parent be0c2bd44c 7da99acca7
commit f66a5bab99
116 changed files with 4826 additions and 3206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/modules/ROOT/pages/features/integrations/concurrency.adoc
View File

@@ -14,8 +14,10 @@ It wraps a delegate `Runnable` in order to initialize the `SecurityContextHolder
It then invokes the delegate Runnable ensuring to clear the `SecurityContextHolder` afterwards.
The `DelegatingSecurityContextRunnable` looks something like this:
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
public void run() {
@@ -28,7 +30,8 @@ try {
}
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
fun run() {
@@ -40,7 +43,7 @@ fun run() {
}
}
----
====
======
While very simple, it makes it seamless to transfer the SecurityContext from one Thread to another.
This is important since, in most cases, the SecurityContextHolder acts on a per Thread basis.
@@ -48,8 +51,10 @@ For example, you might have used Spring Security's xref:servlet/appendix/namespa
You can now easily transfer the `SecurityContext` of the current `Thread` to the `Thread` that invokes the secured service.
An example of how you might do this can be found below:
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
Runnable originalRunnable = new Runnable() {
@@ -65,7 +70,8 @@ DelegatingSecurityContextRunnable wrappedRunnable =
new Thread(wrappedRunnable).start();
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
val originalRunnable = Runnable {
@@ -76,7 +82,7 @@ val wrappedRunnable = DelegatingSecurityContextRunnable(originalRunnable, contex
Thread(wrappedRunnable).start()
----
====
======
The code above performs the following steps:
@@ -90,8 +96,10 @@ Since it is quite common to create a `DelegatingSecurityContextRunnable` with th
The following code is the same as the code above:
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
Runnable originalRunnable = new Runnable() {
@@ -106,7 +114,8 @@ DelegatingSecurityContextRunnable wrappedRunnable =
new Thread(wrappedRunnable).start();
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
val originalRunnable = Runnable {
@@ -117,7 +126,7 @@ val wrappedRunnable = DelegatingSecurityContextRunnable(originalRunnable)
Thread(wrappedRunnable).start()
----
====
======
The code we have is simple to use, but it still requires knowledge that we are using Spring Security.
In the next section we will take a look at how we can utilize `DelegatingSecurityContextExecutor` to hide the fact that we are using Spring Security.
@@ -131,8 +140,10 @@ The design of `DelegatingSecurityContextExecutor` is very similar to that of `De
You can see an example of how it might be used below:
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
SecurityContext context = SecurityContextHolder.createEmptyContext();
@@ -154,7 +165,8 @@ public void run() {
executor.execute(originalRunnable);
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
val context: SecurityContext = SecurityContextHolder.createEmptyContext()
@@ -171,7 +183,7 @@ val originalRunnable = Runnable {
executor.execute(originalRunnable)
----
====
======
The code performs the following steps:
@@ -185,8 +197,10 @@ In this instance, the same `SecurityContext` will be used for every Runnable sub
This is nice if we are running background tasks that need to be run by a user with elevated privileges.
* At this point you may be asking yourself "How does this shield my code of any knowledge of Spring Security?" Instead of creating the `SecurityContext` and the `DelegatingSecurityContextExecutor` in our own code, we can inject an already initialized instance of `DelegatingSecurityContextExecutor`.
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
@Autowired
@@ -202,7 +216,8 @@ executor.execute(originalRunnable);
}
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
@Autowired
@@ -215,7 +230,7 @@ fun submitRunnable() {
executor.execute(originalRunnable)
}
----
====
======
Now our code is unaware that the `SecurityContext` is being propagated to the `Thread`, then the `originalRunnable` is run, and then the `SecurityContextHolder` is cleared out.
In this example, the same user is being used to run each thread.
@@ -224,8 +239,10 @@ This can be done by removing the `SecurityContext` argument from our `Delegating
For example:
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
SimpleAsyncTaskExecutor delegateExecutor = new SimpleAsyncTaskExecutor();
@@ -233,13 +250,14 @@ DelegatingSecurityContextExecutor executor =
new DelegatingSecurityContextExecutor(delegateExecutor);
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
val delegateExecutor = SimpleAsyncTaskExecutor()
val executor = DelegatingSecurityContextExecutor(delegateExecutor)
----
====
======
Now anytime `executor.execute(Runnable)` is executed the `SecurityContext` is first obtained by the `SecurityContextHolder` and then that `SecurityContext` is used to create our `DelegatingSecurityContextRunnable`.
This means that we are running our `Runnable` with the same user that was used to invoke the `executor.execute(Runnable)` code.

101
docs/modules/ROOT/pages/features/integrations/cryptography.adoc
View File

@@ -23,19 +23,22 @@ Both `BytesEncryptor` and `TextEncryptor` are interfaces. `BytesEncryptor` has m
You can use the `Encryptors.stronger` factory method to construct a `BytesEncryptor`:
.BytesEncryptor
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
Encryptors.stronger("password", "salt");
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
Encryptors.stronger("password", "salt")
----
====
======
The `stronger` encryption method creates an encryptor by using 256-bit AES encryption with
Galois Counter Mode (GCM).
@@ -49,19 +52,22 @@ The provided salt should be in hex-encoded String form, be random, and be at lea
You can generate such a salt by using a `KeyGenerator`:
.Generating a key
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
String salt = KeyGenerators.string().generateKey(); // generates a random 8-byte salt that is then hex-encoded
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
val salt = KeyGenerators.string().generateKey() // generates a random 8-byte salt that is then hex-encoded
----
====
======
You can also use the `standard` encryption method, which is 256-bit AES in Cipher Block Chaining (CBC) Mode.
This mode is not https://en.wikipedia.org/wiki/Authenticated_encryption[authenticated] and does not provide any
@@ -73,19 +79,22 @@ For a more secure alternative, use `Encryptors.stronger`.
You can use the `Encryptors.text` factory method to construct a standard TextEncryptor:
.TextEncryptor
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
Encryptors.text("password", "salt");
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
Encryptors.text("password", "salt")
----
====
======
A `TextEncryptor` uses a standard `BytesEncryptor` to encrypt text data.
Encrypted results are returned as hex-encoded strings for easy storage on the filesystem or in a database.
@@ -101,81 +110,92 @@ You can also construct a {security-api-url}org/springframework/security/crypto/k
You can use the `KeyGenerators.secureRandom` factory methods to generate a `BytesKeyGenerator` backed by a `SecureRandom` instance:
.BytesKeyGenerator
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
BytesKeyGenerator generator = KeyGenerators.secureRandom();
byte[] key = generator.generateKey();
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
val generator = KeyGenerators.secureRandom()
val key = generator.generateKey()
----
====
======
The default key length is 8 bytes.
A `KeyGenerators.secureRandom` variant provides control over the key length:
.KeyGenerators.secureRandom
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
KeyGenerators.secureRandom(16);
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
KeyGenerators.secureRandom(16)
----
====
======
Use the `KeyGenerators.shared` factory method to construct a BytesKeyGenerator that always returns the same key on every invocation:
.KeyGenerators.shared
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
KeyGenerators.shared(16);
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
KeyGenerators.shared(16)
----
====
======
=== StringKeyGenerator
You can use the `KeyGenerators.string` factory method to construct an 8-byte, `SecureRandom` `KeyGenerator` that hex-encodes each key as a `String`:
.StringKeyGenerator
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
KeyGenerators.string();
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
KeyGenerators.string()
----
====
======
[[spring-security-crypto-passwordencoders]]
== Password Encoding
The password package of the `spring-security-crypto` module provides support for encoding passwords.
`PasswordEncoder` is the central service interface and has the following signature:
====
[source,java]
----
public interface PasswordEncoder {
@@ -188,7 +208,6 @@ public interface PasswordEncoder {
}
}
----
====
The `matches` method returns true if the `rawPassword`, once encoded, equals the `encodedPassword`.
This method is designed to support password-based authentication schemes.
@@ -202,8 +221,10 @@ You can change this value in your deployed system without affecting existing pas
The following example uses the `BCryptPasswordEncoder`:
.BCryptPasswordEncoder
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
@@ -213,7 +234,8 @@ String result = encoder.encode("myPassword");
assertTrue(encoder.matches("myPassword", result));
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
@@ -222,7 +244,7 @@ val encoder = BCryptPasswordEncoder(16)
val result: String = encoder.encode("myPassword")
assertTrue(encoder.matches("myPassword", result))
----
====
======
The `Pbkdf2PasswordEncoder` implementation uses PBKDF2 algorithm to hash the passwords.
To defeat password cracking, PBKDF2 is a deliberately slow algorithm and should be tuned to take about .5 seconds to verify a password on your system.
@@ -230,8 +252,10 @@ The following system uses the `Pbkdf2PasswordEncoder`:
.Pbkdf2PasswordEncoder
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
// Create an encoder with all the defaults
@@ -240,7 +264,8 @@ String result = encoder.encode("myPassword");
assertTrue(encoder.matches("myPassword", result));
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
// Create an encoder with all the defaults
@@ -248,4 +273,4 @@ val encoder = Pbkdf2PasswordEncoder.defaultsForSpringSecurity_v5_8()
val result: String = encoder.encode("myPassword")
assertTrue(encoder.matches("myPassword", result))
----
====
======

22
docs/modules/ROOT/pages/features/integrations/data.adoc
View File

@@ -10,8 +10,10 @@ It is not only useful but necessary to include the user in the queries to suppor
To use this support, add `org.springframework.security:spring-security-data` dependency and provide a bean of type `SecurityEvaluationContextExtension`.
In Java Configuration, this would look like:
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
@Bean
@@ -20,7 +22,8 @@ public SecurityEvaluationContextExtension securityEvaluationContextExtension() {
}
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
@Bean
@@ -28,7 +31,7 @@ fun securityEvaluationContextExtension(): SecurityEvaluationContextExtension {
return SecurityEvaluationContextExtension()
}
----
====
======
In XML Configuration, this would look like:
@@ -43,8 +46,10 @@ In XML Configuration, this would look like:
Now Spring Security can be used within your queries.
For example:
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
@Repository
@@ -54,7 +59,8 @@ public interface MessageRepository extends PagingAndSortingRepository<Message,Lo
}
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
@Repository
@@ -63,7 +69,7 @@ interface MessageRepository : PagingAndSortingRepository<Message?, Long?> {
fun findInbox(pageable: Pageable?): Page<Message?>?
}
----
====
======
This checks to see if the `Authentication.getPrincipal().getId()` is equal to the recipient of the `Message`.
Note that this example assumes you have customized the principal to be an Object that has an id property.

11
docs/modules/ROOT/pages/features/integrations/jackson.adoc
View File

@@ -6,8 +6,10 @@ This can improve the performance of serializing Spring Security related classes
To use it, register the `SecurityJackson2Modules.getModules(ClassLoader)` with `ObjectMapper` (https://github.com/FasterXML/jackson-databind[jackson-databind]):
====
.Java
[tabs]
======
Java::
+
[source,java,role="primary"]
----
ObjectMapper mapper = new ObjectMapper();
@@ -21,7 +23,8 @@ SecurityContext context = new SecurityContextImpl();
String json = mapper.writeValueAsString(context);
----
.Kotlin
Kotlin::
+
[source,kotlin,role="secondary"]
----
val mapper = ObjectMapper()
@@ -34,7 +37,7 @@ val context: SecurityContext = SecurityContextImpl()
// ...
val json: String = mapper.writeValueAsString(context)
----
====
======
[NOTE]
====