[[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.
