You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/docs/asciidoc/guides/boot-findbyusername.adoc
+59-55Lines changed: 59 additions & 55 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,137 +4,141 @@ Rob Winch
4
4
5
5
This guide describes how to use Spring Session to find sessions by username.
6
6
7
-
NOTE: The completed guide can be found in the <<findbyusername-sample, findbyusername application>>.
7
+
NOTE: You can find the completed guide in the <<findbyusername-sample, findbyusername application>>.
8
8
9
9
10
10
[[findbyusername-assumptions]]
11
11
== Assumptions
12
12
13
-
The guide assumes you have already added Spring Session using the builtin Redis configuration support to your application.
13
+
The guide assumes you have already added Spring Session to your application by using the built-in Redis configuration support.
14
14
The guide also assumes you have already applied Spring Security to your application.
15
-
However, we the guide will be somewhat general purpose and can be applied to any technology with minimal changeswe will discuss.
15
+
However, we the guide is somewhat general purpose and can be applied to any technology with minimal changes, which we discuss later in the guide.
16
16
17
-
[NOTE]
18
-
====
19
-
If you need to learn how to add Spring Session to your project, please refer to the listing of link:../#samples[samples and guides]
20
-
====
17
+
NOTE: If you need to learn how to add Spring Session to your project, see the listing of link:../#samples[samples and guides]
21
18
22
19
== About the Sample
23
20
24
-
Our sample is using this feature to invalidate the users session that might have been compromised.
21
+
Our sample uses this feature to invalidate the users session that might have been compromised.
25
22
Consider the following scenario:
26
23
27
-
* User goes to library and authenticates to the application
28
-
* User goes home and realizes they forgot to log out
29
-
* User can log in and terminate the session from the library using clues like the location, created time, last accessed time, etc.
24
+
* User goes to library and authenticates to the application.
25
+
* User goes home and realizes they forgot to log out.
26
+
* User can log in and terminate the session from the library using clues like the location, created time, last accessed time, and so on.
30
27
31
-
Wouldn't it be nice if we could allow the user to invalidate the session at the library from any device they authenticate with?
28
+
Would it not be nice if we could let the user invalidate the session at the library from any device with which they authenticate?
32
29
This sample demonstrates how this is possible.
33
30
34
31
[[findbyindexnamesessionrepository]]
35
-
== FindByIndexNameSessionRepository
32
+
== Using `FindByIndexNameSessionRepository`
36
33
37
-
In order to look up a user by their username, you must first choose a `SessionRepository` that implements link:../#api-findbyindexnamesessionrepository[FindByIndexNameSessionRepository].
38
-
Our sample application assumes that the Redis support is already setup, so we are ready to go.
34
+
To look up a user by their username, you must first choose a `SessionRepository` that implements link:../#api-findbyindexnamesessionrepository[`FindByIndexNameSessionRepository`].
35
+
Our sample application assumes that the Redis support is already set up, so we are ready to go.
39
36
40
-
== Mapping the username
37
+
== Mapping the User Name
41
38
42
-
`FindByIndexNameSessionRepository` can only find a session by the username, if the developer instructs Spring Session what user is associated with the `Session`.
43
-
This is done by ensuring that the session attribute with the name `FindByUsernameSessionRepository.PRINCIPAL_NAME_INDEX_NAME` is populated with the username.
39
+
`FindByIndexNameSessionRepository` can find a session only by the user name if the developer instructs Spring Session what user is associated with the `Session`.
40
+
You can do so by ensuring that the session attribute with the name `FindByUsernameSessionRepository.PRINCIPAL_NAME_INDEX_NAME` is populated with the username.
44
41
45
-
Generally, speaking this can be done with the following code immediately after the user authenticates:
42
+
Generally speaking, you can do so with the following code immediately after the user authenticates:
We obtain the information we want and then set the `SessionDetails` as an attribute in the `Session`.
80
-
When we retrieve the `Session` by username, we can then use the session to access our `SessionDetails` just like any other session attribute.
82
+
When we retrieve the `Session` by user name, we can then use the session to access our `SessionDetails` as we would any other session attribute.
81
83
82
-
[NOTE]
83
-
====
84
-
You might be wondering at this point why Spring Session does not provide `SessionDetails` functionality out of the box.
85
-
The reason, is twofold.
86
-
The first is that it is very trivial for applications to implement this themselves.
87
-
The second reason is that the information that is populated in the session (and how frequently that information is updated) is highly application dependent.
88
-
====
84
+
NOTE: You might wonder why Spring Session does not provide `SessionDetails` functionality out of the box.
85
+
We have two reasons.
86
+
The first reason is that it is very trivial for applications to implement this themselves.
87
+
The second reason is that the information that is populated in the session (and how frequently that information is updated) is highly application-dependent.
89
88
90
89
== Finding sessions for a specific user
91
90
92
91
We can now find all the sessions for a specific user.
In our instance, we find all sessions for the currently logged in user.
100
-
However, this could easily be modified for an administrator to use a form to specify which user to look up.
102
+
However, you can modify this for an administrator to use a form to specify which user to look up.
101
103
102
104
[[findbyusername-sample]]
103
-
== findbyusername Sample Application
105
+
== `findbyusername` Sample Application
106
+
107
+
This section describes how to use the `findbyusername` sample application.
104
108
105
-
=== Running the findbyusername Sample Application
109
+
=== Running the `findbyusername` Sample Application
106
110
107
111
You can run the sample by obtaining the {download-url}[source code] and invoking the following command:
108
112
109
-
[NOTE]
110
-
====
111
-
For the sample to work, you must https://redis.io/download[install Redis 2.8+] on localhost and run it with the default port (6379).
112
-
Alternatively, you can update the `RedisConnectionFactory` to point to a Redis server.
113
-
Another option is to use https://www.docker.com/[Docker] to run Redis on localhost. See https://hub.docker.com/_/redis/[Docker Redis repository] for detailed instructions.
Copy file name to clipboardExpand all lines: docs/src/docs/asciidoc/guides/boot-jdbc.adoc
+50-36Lines changed: 50 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,15 +2,17 @@
2
2
Rob Winch, Vedran Pavić
3
3
:toc:
4
4
5
-
This guide describes how to use Spring Session to transparently leverage a relational database to back a web application's `HttpSession` when using Spring Boot.
5
+
This guide describes how to use Spring Session to transparently leverage a relational database to back a web application's `HttpSession` when you use Spring Boot.
6
6
7
-
NOTE: The completed guide can be found in the <<httpsession-jdbc-boot-sample, httpsession-jdbc-boot sample application>>.
7
+
NOTE: You can find the completed guide in the <<httpsession-jdbc-boot-sample, httpsession-jdbc-boot sample application>>.
8
8
9
9
== Updating Dependencies
10
-
Before you use Spring Session, you must ensure to update your dependencies.
10
+
11
+
Before you use Spring Session, you must update your dependencies.
11
12
We assume you are working with a working Spring Boot web application.
12
-
If you are using Maven, ensure to add the following dependencies:
13
+
If you use Maven, you must add the following dependencies:
13
14
15
+
====
14
16
.pom.xml
15
17
[source,xml]
16
18
[subs="verbatim,attributes"]
@@ -24,104 +26,116 @@ If you are using Maven, ensure to add the following dependencies:
24
26
</dependency>
25
27
</dependencies>
26
28
----
29
+
====
27
30
28
-
Spring Boot provides dependency management for Spring Session modules, so there's no need to explicitly declare dependency version.
31
+
Spring Boot provides dependency management for Spring Session modules, so you need not explicitly declare the dependency version.
29
32
30
33
// tag::config[]
31
34
32
35
[[httpsession-jdbc-boot-spring-configuration]]
33
36
== Spring Boot Configuration
34
37
35
38
After adding the required dependencies, we can create our Spring Boot configuration.
36
-
Thanks to first-class auto configuration support, setting up Spring Session backed by a relational database is as simple as adding a single configuration property to your `application.properties`:
39
+
Thanks to first-class auto configuration support, setting up Spring Session backed by a relational database is as simple as adding a single configuration property to your `application.properties`.
40
+
The following listing shows how to do so:
37
41
42
+
====
38
43
.src/main/resources/application.properties
39
44
----
40
45
spring.session.store-type=jdbc # Session store type.
41
46
----
47
+
====
42
48
43
-
Under the hood, Spring Boot will apply configuration that is equivalent to manually adding `@EnableJdbcHttpSession` annotation.
44
-
This creates a Spring Bean with the name of `springSessionRepositoryFilter` that implements Filter.
45
-
The filter is what is in charge of replacing the `HttpSession` implementation to be backed by Spring Session.
49
+
Under the hood, Spring Boot applies configuration that is equivalent to manually adding the `@EnableJdbcHttpSession` annotation.
50
+
This creates a Spring bean with the name of `springSessionRepositoryFilter`. That bean implements `Filter`.
51
+
The filter is in charge of replacing the `HttpSession` implementation to be backed by Spring Session.
46
52
47
-
Further customization is possible using `application.properties`:
53
+
You can further customize by using `application.properties`.
54
+
The following listing shows how to do so:
48
55
56
+
====
49
57
.src/main/resources/application.properties
50
58
----
51
-
server.servlet.session.timeout= # Session timeout. If a duration suffix is not specified, seconds will be used.
59
+
server.servlet.session.timeout= # Session timeout. If a duration suffix is not specified, seconds are used.
spring.session.jdbc.schema=classpath:org/springframework/session/jdbc/schema-@@platform@@.sql # Path to the SQL file to use to initialize the database schema.
54
62
spring.session.jdbc.table-name=SPRING_SESSION # Name of the database table used to store sessions.
55
63
----
64
+
====
56
65
57
-
For more information, refer to https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference/htmlsingle/#boot-features-session[Spring Session] portion of the Spring Boot documentation.
66
+
For more information, see the https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference/htmlsingle/#boot-features-session[Spring Session] portion of the Spring Boot documentation.
58
67
59
68
[[httpsession-jdbc-boot-configuration]]
60
-
== Configuring the DataSource
69
+
== Configuring the `DataSource`
61
70
62
-
Spring Boot automatically creates a `DataSource` that connects Spring Session to an embedded instance of H2 database.
63
-
In a production environment you need to ensure to update your configuration to point to your relational database.
64
-
For example, you can include the following in your *application.properties*
71
+
Spring Boot automatically creates a `DataSource` that connects Spring Session to an embedded instance of an H2 database.
72
+
In a production environment, you need to update your configuration to point to your relational database.
73
+
For example, you can include the following in your application.properties:
65
74
75
+
====
66
76
.src/main/resources/application.properties
67
77
----
68
78
spring.datasource.url= # JDBC URL of the database.
69
79
spring.datasource.username= # Login username of the database.
70
80
spring.datasource.password= # Login password of the database.
71
81
----
82
+
====
72
83
73
-
For more information, refer to https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference/htmlsingle/#boot-features-configure-datasource[Configure a DataSource] portion of the Spring Boot documentation.
84
+
For more information, see the https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference/htmlsingle/#boot-features-configure-datasource[Configure a DataSource] portion of the Spring Boot documentation.
74
85
75
86
[[httpsession-jdbc-boot-servlet-configuration]]
76
87
== Servlet Container Initialization
77
88
78
-
Our <<httpsession-jdbc-boot-spring-configuration,Spring Boot Configuration>> created a Spring Bean named `springSessionRepositoryFilter` that implements `Filter`.
89
+
Our <<httpsession-jdbc-boot-spring-configuration,Spring Boot Configuration>> created a Spring bean named `springSessionRepositoryFilter` that implements `Filter`.
79
90
The `springSessionRepositoryFilter` bean is responsible for replacing the `HttpSession` with a custom implementation that is backed by Spring Session.
80
91
81
92
In order for our `Filter` to do its magic, Spring needs to load our `Config` class.
82
-
Last we need to ensure that our Servlet Container (i.e. Tomcat) uses our `springSessionRepositoryFilter` for every request.
93
+
Last, we need to ensure that our Servlet Container (that is, Tomcat) uses our `springSessionRepositoryFilter` for every request.
83
94
Fortunately, Spring Boot takes care of both of these steps for us.
84
95
85
96
// end::config[]
86
97
87
98
[[httpsession-jdbc-boot-sample]]
88
-
== httpsession-jdbc-boot Sample Application
99
+
== `httpsession-jdbc-boot` Sample Application
89
100
90
-
The httpsession-jdbc-boot Sample Application demonstrates how to use Spring Session to transparently leverage H2 database to back a web application's `HttpSession` when using Spring Boot.
101
+
The httpsession-jdbc-boot Sample Application demonstrates how to use Spring Session to transparently leverage an H2 database to back a web application's `HttpSession` when you use Spring Boot.
91
102
92
103
[[httpsession-jdbc-boot-running]]
93
-
=== Running the httpsession-jdbc-boot Sample Application
104
+
=== Running the `httpsession-jdbc-boot` Sample Application
94
105
95
106
You can run the sample by obtaining the {download-url}[source code] and invoking the following command:
You should now be able to access the application at http://localhost:8080/
102
115
103
116
[[httpsession-jdbc-boot-explore]]
104
-
=== Exploring the security Sample Application
117
+
=== Exploring the Security Sample Application
105
118
106
-
Try using the application. Enter the following to log in:
119
+
You can now try using the application.
120
+
To do so, enter the following to log in:
107
121
108
-
* **Username** _user_
109
-
* **Password** _password_
122
+
* *Username* _user_
123
+
* *Password* _password_
110
124
111
-
Now click the **Login** button.
112
-
You should now see a message indicating your are logged in with the user entered previously.
113
-
The user's information is stored in H2 database rather than Tomcat's `HttpSession` implementation.
125
+
Now click the *Login* button.
126
+
You should now see a message indicating that your are logged in with the user entered previously.
127
+
The user's information is stored in the H2 database rather than Tomcat's `HttpSession` implementation.
114
128
115
129
[[httpsession-jdbc-boot-how]]
116
-
=== How does it work?
130
+
=== How Does It Work?
117
131
118
-
Instead of using Tomcat's `HttpSession`, we are actually persisting the values in H2 database.
132
+
Instead of using Tomcat's `HttpSession`, we persist the values in the H2 database.
119
133
Spring Session replaces the `HttpSession` with an implementation that is backed by a relational database.
120
-
When Spring Security's `SecurityContextPersistenceFilter` saves the `SecurityContext` to the `HttpSession` it is then persisted into H2 database.
134
+
When Spring Security's `SecurityContextPersistenceFilter` saves the `SecurityContext` to the `HttpSession`, it is then persisted into the H2 database.
121
135
122
-
When a new `HttpSession` is created, Spring Session creates a cookie named SESSION in your browser that contains the id of your session.
123
-
Go ahead and view the cookies (click for help with https://developers.google.com/web/tools/chrome-devtools/manage-data/cookies[Chrome] or https://developer.mozilla.org/en-US/docs/Tools/Storage_Inspector[Firefox]).
136
+
When a new `HttpSession` is created, Spring Session creates a cookie named `SESSION` in your browser. That cookie contains the ID of your session.
137
+
You can view the cookies (with https://developers.google.com/web/tools/chrome-devtools/manage-data/cookies[Chrome] or https://developer.mozilla.org/en-US/docs/Tools/Storage_Inspector[Firefox]).
124
138
125
-
If you like, you can easily remove the session using H2 web console available at: http://localhost:8080/h2-console/ (use `jdbc:h2:mem:testdb` for JDBC URL)
139
+
You can remove the session by using the H2 web console available at: http://localhost:8080/h2-console/ (use `jdbc:h2:mem:testdb` for JDBC URL).
126
140
127
-
Now visit the application at http://localhost:8080/ and observe that we are no longer authenticated.
141
+
Now you can visit the application at http://localhost:8080/ and see that we are no longer authenticated.
0 commit comments