162 lines
6.3 KiB
Plaintext
162 lines
6.3 KiB
Plaintext
[[recipe-basic-auth]]
|
|
= Recipe: Basic Auth
|
|
|
|
NOTE: You should not use basic auth for projects other than proofs of concept and demonstrations.
|
|
We include it in the cookbook because it lets us show the basic pattern of Spring Security with the fewest additional details.
|
|
(In other words, it is the simplest example.)
|
|
If you are already familiar with Spring Security, you might want to skip this recipe.
|
|
If you are new to Spring Security, this recipe is worth reviewing, to learn the basics.
|
|
|
|
[[security-cookbook-the-web-application]]
|
|
== The Application to Secure
|
|
|
|
For this guide, we build an application from scratch with Spring Boot
|
|
To do so, navigate to the https://start.spring.io[Spring Initializr] and add the Web and Thymeleaf dependencies.
|
|
|
|
Alternatively, you can perform the following steps on the command line:
|
|
|
|
====
|
|
.Gradle
|
|
[source,shell]
|
|
----
|
|
$ curl -G https://start.spring.io/starter.tgz -d dependencies=web,thymeleaf -d name=basic-auth -d baseDir=basic-auth -d type=gradle-project | tar -xzvf -
|
|
----
|
|
|
|
.Maven
|
|
[source,shell]
|
|
----
|
|
$ curl -G https://start.spring.io/starter.tgz -d dependencies=web,thymeleaf -d name=basic-auth -d baseDir=basic-auth -d type=maven-project | tar -xzvf -
|
|
----
|
|
====
|
|
|
|
You can then import that project into your favorite IDE or work directly with the files and `./mvnw` or `./gradlew` on the command line.
|
|
|
|
Spring Security secures applications, so we need an application to secure.
|
|
A simple web application suffices as an example that we can then secure in the various recipes.
|
|
|
|
NOTE: We use the same example that we used in the "`Securing a Web Application`" guide, which you can find on the Spring web site at https://spring.io/guides/gs/securing-web/[https://spring.io/guides/gs/securing-web/].
|
|
|
|
We use Spring Boot with the Spring Web and Thymeleaf dependencies.
|
|
There are lots of ways to make a web application, but we know this one well, since we have documented it elsewhere.
|
|
|
|
We need some HTML files.
|
|
We start where a visitor would start, at `home.html`.
|
|
|
|
IMPORTANT: The HTML files go in the `resources/templates` directory.
|
|
Spring Boot knows to look for them in that location.
|
|
|
|
The following listing shows our `home.html` file:
|
|
|
|
====
|
|
[source,html]
|
|
----
|
|
include::../../../../servlet/spring-boot/java/basic-auth/src/main/resources/templates/home.html[]
|
|
----
|
|
====
|
|
|
|
We also need a `hello.html` file, so that visitors to our web site can see the greeting we mention in the `home.html` file.
|
|
The following listing shows the `hello.html` file:
|
|
|
|
[source,html]
|
|
====
|
|
----
|
|
include::../../../../servlet/spring-boot/java/basic-auth/src/main/resources/templates/hello.html[]
|
|
----
|
|
====
|
|
|
|
Once we have HTML pages for our visitors to see, we need to route them to the pages.
|
|
We do that with a class that uses the `@Controller` annotation (from the Spring framework).
|
|
The following listing shows that class, which is called `HelloController`:
|
|
|
|
====
|
|
[source,java]
|
|
----
|
|
include::../../../../servlet/spring-boot/java/basic-auth/src/main/java/example/HelloController.java[tag=sans-header]
|
|
----
|
|
====
|
|
|
|
If we run this application now, we would see an unsecured web application.
|
|
Now we can make it be a secure application.
|
|
|
|
== Securing the Application
|
|
|
|
To secure the simple web application presented in the <<security-cookbook-the-web-application,preceding section>>, we need to add the appropriate Spring Security dependencies to our build file (we show both Maven and Gradle).
|
|
|
|
For Gradle, we need to add the following two lines to the `dependencies` block in our `build.gradle` file:
|
|
|
|
====
|
|
[source,java]
|
|
----
|
|
implementation 'org.springframework.boot:spring-boot-starter-security'
|
|
implementation 'org.springframework.security:spring-security-test'
|
|
----
|
|
====
|
|
|
|
For Maven, we need to add the following two dependencies to the `dependencies` element in our `pom.xml` file:
|
|
|
|
====
|
|
[source,xml]
|
|
----
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-security</artifactId>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>org.springframework.security</groupId>
|
|
<artifactId>spring-security-test</artifactId>
|
|
<scope>test</scope>
|
|
</dependency>
|
|
----
|
|
====
|
|
|
|
We also need a login page. The following HTML file serves that need:
|
|
|
|
====
|
|
[source,html]
|
|
----
|
|
include::../../../../servlet/spring-boot/java/basic-auth/src/main/resources/templates/login.html[]
|
|
----
|
|
====
|
|
|
|
We also need to add another class to our application, as the following listing shows:
|
|
|
|
====
|
|
[source,java]
|
|
----
|
|
include::../../../../servlet/spring-boot/java/basic-auth/src/main/java/example/LoginController.java[tag=sans-header]
|
|
----
|
|
<1> We need to add this class to make the `/login` path work.
|
|
====
|
|
|
|
We also need a class to configure security for our web application.
|
|
The following listing shows that class (called `SecurityConfiguration`):
|
|
|
|
====
|
|
[source,java]
|
|
----
|
|
include::../../../../servlet/spring-boot/java/basic-auth/src/main/java/example/SecurityConfiguration.java[tag=sans-header]
|
|
----
|
|
<1> Turn on security by authorizing the request.
|
|
<2> Let anyone see the default and `home` paths.
|
|
<3> Require that any request be authenticated. (This is where we apply security.)
|
|
<4> Allow a login form.
|
|
<5> Allow that form from the `/login` path.
|
|
<6> Let anyone see the logout success page.
|
|
<7> Define a user object.
|
|
<8> Encode the password in memory (used only for demonstration purposes -- do NOT do this in production).
|
|
<9> The user's user name is `user`.
|
|
<10> The user's password is `password`.
|
|
<11> The user's role is `USER`.
|
|
<12> Build the user object.
|
|
====
|
|
|
|
WARNING: _NEVER_ put user names and passwords in code for a real application.
|
|
It is tolerable for demonstrations and samples, but it is very poor practice for real applications.
|
|
|
|
The `SecurityConfiguration` class has two key parts: a `configure` method (which overrides the `configure` method in `WebSecurityConfigurerAdapter`) and a `UserDetailsService` bean.
|
|
The `configure` method has a chain of methods that define the security for the paths in our application.
|
|
In essence, the preceding configuration says, "`Let anyone see the login and logout pages, as well as the home page. Make everyone authenticate (log in) to see anything else.`"
|
|
We also define the one and only user who can view our web application.
|
|
Normally, we would get user details from a database or an LDAP or OAuth server (or from some other source -- the other Spring Security guides cover the most common ways to get user details).
|
|
We created this simple arrangement to show the basic outline of what happens.
|