(window.webpackJsonp=window.webpackJsonp||[]).push([[237],{663:function(t,e,n){"use strict";n.r(e);vari=n(56),r=Object(i.a)({},(function(){vart=this,e=t.$createElement,n=t._self._c||e;returnn("ContentSlotsDistributor",{attrs:{"slot-key":t.$parent.slotKey}},[n("h1",{attrs:{id:"form-login"}},[n("a",{staticClass:"header-anchor",attrs:{href:"#form-login"}},[t._v("#")]),t._v(" Form Login")]),t._v(""),n("p",[t._v("Spring Security provides support for username and password being provided through an html form.\nThis section provides details on how form based authentication works within Spring Security.")]),t._v(""),n("p",[t._v("Let’s take a look at how form based log in works within Spring Security.\nFirst, we see how the user is redirected to the log in form.")]),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.png",alt:"loginurlauthenticationentrypoint"}})]),t._v(""),n("p",[t._v("Figure 1. Redirecting to the Log In Page")]),t._v(""),n("p",[t._v("The figure builds off our "),n("RouterLink",{attrs:{to:"/architecture.html#servlet-securityfilterchain"}},[n("code",[t._v("SecurityFilterChain")])]),t._v(" diagram.")],1),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_1.png",alt:"number 1"}}),t._v(" First, a user makes an unauthenticated request to the resource "),n("code",[t._v("/private")]),t._v(" for which it is not authorized.")]),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_2.png",alt:"number 2"}}),t._v(" Spring Security’s "),n("RouterLink",{attrs:{to:"/authorization/authorize-requests.html#servlet-authorization-filtersecurityinterceptor"}},[n("code",[t._v("FilterSecurityInterceptor")])]),t._v(" indicates that the unauthenticated request is "),n("em",[t._v("Denied")]),t._v(" by throwing an "),n("code",[t._v("AccessDeniedException")]),t._v(".")],1),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_3.png",alt:"number 3"}}),t._v(" Since the user is not authenticated, "),n("RouterLink",{attrs:{to:"/architecture.html#servlet-exceptiontranslationfilter"}},[n("code",[t._v("ExceptionTranslationFilter")])]),t._v(" initiates "),n("em",[t._v("Start Authentication")]),t._v(" and sends a redirect to the log in page with the configured "),n("RouterLink",{attrs:{to:"/en/architecture.html#servlet-authentication-authenticationentrypoint"}},[n("code",[t._v("AuthenticationEntryPoint")])]),t._v(".\nIn most cases the "),n("code",[t._v("AuthenticationEntryPoint")]),t._v(" is an instance of "),n("a",{attrs:{href:"https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html",target:"_blank",rel:"noopener noreferrer"}},[n("code",[t._v("LoginUrlAuthenticationEntryPoint")]),n("OutboundLink")],1),t._v(".")],1),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_4.png",alt:"number 4"}}),t._v(" The browser will then request the log in page that it was redirected to.")]),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_5.png",alt:"number 5"}}),t._v(" Something within the application, must "),n("a",{attrs:{href:"#servlet-authentication-form-custom"}},[t._v("render the log in page")]),t._v(".")]),t._v(""),n("p",[t._v("When the username and password are submitted, the "),n("code",[t._v("UsernamePasswordAuthenticationFilter")]),t._v(" authenticates the username and password.\nThe "),n("code",[t._v("UsernamePasswordAuthenticationFilter")]),t._v(" extends "),n("RouterLink",{attrs:{to:"/en/architecture.html#servlet-authentication-abstractprocessingfilter"}},[t._v("AbstractAuthenticationProcessingFilter")]),t._v(", so this diagram should look pretty similar.")],1),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png",alt:"usernamepasswordauthenticationfilter"}})]),t._v(""),n("p",[t._v("Figure 2. Authenticating Username and Password")]),t._v(""),n("p",[t._v("The figure builds off our "),n("RouterLink",{attrs:{to:"/architecture.html#servlet-securityfilterchain"}},[n("code",[t._v("SecurityFilterChain")])]),t._v(" diagram.")],1),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_1.png",alt:"number 1"}}),t._v(" When the user submits their username and password, the "),n("code",[t._v("UsernamePasswordAuthenticationFilter")]),t._v(" creates a "),n("code",[t._v("UsernamePasswordAuthenticationToken")]),t._v(" which is a type of "),n("RouterLink",{attrs:{to:"/en/architecture.html#servlet-authentication-authentication"}},[n("code",[t._v("Authentication")])]),t._v(" by extracting the username and password from the "),n("code",[t._v("HttpServletRequest")]),t._v(".")],1),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_2.png",alt:"number 2"}}),t._v(" Next, the "),n("code",[t._v("UsernamePasswordAuthenticationToken")]),t._v(" is passed into the "),n("code",[t._v("AuthenticationManager")]),t._v(" to be authenticated.\nThe details of what "),n("code",[t._v("AuthenticationManager")]),t._v(" looks like depend on how the "),n("RouterLink",{attrs:{to:"/en/spring-security/index.html#servlet-authentication-unpwd-storage"}},[t._v("user information is stored")]),t._v(".")],1),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_3.png",alt:"number 3"}}),t._v(" If authentication fails, then "),n("em",[t._v("Failure")])]),t._v(""),n("ul",[n("li",[n("p",[t._v("The "),n("RouterLink",{attrs:{to:"/en/architecture.html#servlet-authentication-securitycontextholder"}},[t._v("SecurityContextHolder")]),t._v(" is cleared out.")],1)]),t._v(""),n("li",[n("p",[n("code",[t._v("RememberMeServices.loginFail")]),t._v(" is invoked.\nIf remember me is not configured, this is a no-op.")])]),t._v(""),n("li",[n("p",[n("code",[t._v("AuthenticationFailureHandler")]),t._v(" is invoked.")])])]),t._v(""),n("p",[n("img",{attrs:{src:"https://docs.spring.io/spring-security/reference/_images/icons/number_4.png",alt:"number 4"}}),t._v(" If authentication is successful, then "),n("em",[t._v("Success")]),t._v(".")]),t._v(""),n("ul",[n("li",[n("p",[n("code",[t._v("SessionAuthenticationStrategy")]),t._v(" is notified of a new log in.")])]),t._v(""),n("li",[n("p",[t._v("The "),n("RouterLink",{attrs:{to:"/en/architecture.html#servlet-authentication-authentication"}},[t._v("Authentication")]),t._v(" is set on the "),n("RouterLink",{attrs:{to:"/en/architecture.html#servlet-authentication-securitycontextholder"}},[t._v("SecurityContextHolder")]),t._v(".")],1)]),t._v(""),n("li",[n("p",[n("code",[t._v("RememberMeServices.loginSuccess")]),t._v(" is invoked.\nIf remember me is not configured, this is a no-op.")])]),t._v(""),n("li",[n("p",[n("code",[t._v("ApplicationEventPublisher")]),t._v(" publishes an "),n("code",[t._v("InteractiveAuthenticationSuccessEvent")]),t._v(".")])]),t._v(""),n("li",[n("p",[t._v("The "),n("code",[t._v("AuthenticationSuccessHandler")]),t._v(" is invoked. Typically this is a "),n("code",[t._v("SimpleUrlAuthenticationSuccessHandler")]),t._v(" which will redirect to a request saved by "),n("RouterLink",{attrs:{to:"/architecture.html#servlet-exceptiontranslationfilter"}},[n("code",[t._v("ExceptionTranslationFilter")])]),t._v(" when we redirect to the log in page.")],1)])]),t._v(""),n("p",[t._v("Spring Security form log in is enabled by default.\nHowever, as soon as any servlet based configuration is provided, form based log in must be explicitly provided.\nA minimal, explicit Java configuration can be found below:")]),t._v(""),n("p",[t._v("Example 1. Form Log In")]),t._v(""),n("p",[t._v("Java")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v("protected void configure(HttpSecurity http) {\n\thttp\n\t\t// ...\n\t\t.formLogin(withDefaults());\n}\n")])])]),n("p",[t._v("XML")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v("<http>\n\t\x3c!-- ... --\x3e\n\t<form-login />\n</http>\n")])])]),n("p",[t._v("Kotlin")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v("fun configure(http: HttpSecurity) {\n\thttp {\n\t\t// ...\n\t\tformLogin { }\n\t}\n}\n")])])]),n("p",[t._v("In this configuration Spring Security will render a default log in page.\nMost production applications will require a custom log in form.")]),t._v(""),n("p",[t._v("The configuration below demonstrates how to provide a custom log in form.")]),t._v(""),n("p",[t._v("Example 2. Custom Log In Form Configuration")]),t._v(""),n("p",[t._v("Java")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v('protected void configure(HttpSecurity http) throws Exception {\n\thttp\n\t\t// ...\n\t\t.formLogin(form -> form\n\t\t\t.loginPage("/login")\n\t\t\t.permitAll()\n\t\t);\n}\n')])])]),n("p",[t._v("XML")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v('<http>\n\t\x3c!-- ... --\x3e\n\t<intercept-url pattern="/login" access="permitAll" />\n\t<form-login login-page="/login" />\n</http>\n')])])]),n("p",[t._v("Kotlin")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v('fun configure(http: HttpSecurity) {\n\thttp {\n\t\t// ...\n\t\tformLogin {\n\t\t\tloginPage = "/login"\n\t\t\tpermitAll()\n\t\t}\n\t}\n}\n')])])]),n("p",[t._v("When the login page is specified in the Spring Security configuration, you are responsible for rendering the page.\nBelow is a "),n("a",{attrs:{href:"https://www.thymeleaf.org/",target:"_blank",rel:"noopener noreferrer"}},[t._v("Thymeleaf"),n("OutboundLink")],1),t._v(" template that produces an HTML login form that complies with a login page of "),n("code",[t._v("/login")]),t._v(":")]),t._v(""),n("p",[t._v("Example 3. Log In Form")]),t._v(""),n("p",[t._v("src/main/resources/templates/login.html")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v('<!DOCTYPE html>\n<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="https://www.thymeleaf.org">\n\t<head>\n\t\t<title>Please Log In</title>\n\t</head>\n\t<body>\n\t\t<h1>Please Log In</h1>\n\t\t<div th:if="${param.error}">\n\t\t\tInvalid username and password.</div>\n\t\t<div th:if="${param.logout}">\n\t\t\tYou have been logged out.</div>\n\t\t<form th:action="@{/login}" method="post">\n\t\t\t<div>\n\t\t\t<input type="text" name="username" placeholder="Username"/>\n\t\t\t</div>\n\t\t\t<div>\n\t\t\t<input type="password" name="password" placeholder="Password"/>\n\t\t\t</div>\n\t\t\t<input type="submit" value="Log in" />\n\t\t</form>\n\t</body>\n</html>\n')])])]),n("p",[t._v("There are a few key points about the default HTML form:")]),t._v(""),n("ul",[n("li",[n("p",[t._v("The form should perform a "),n("code",[t._v("post")]),t._v(" to "),n("code",[t._v("/login")])])]),t._v(""),n("li",[n("p",[t._v("The form will need to include a "),n("RouterLink",{attrs:{to:"/exploits/csrf.html#servlet-csrf"}},[t._v("CSRF Token")]),t._v(" which is "),n("RouterLink",{attrs:{to:"/exploits/csrf.html#servlet-csrf-include-form-auto"}},[t._v("automatically included")]),t._v(" by Thymeleaf.")],1)]),t._v(""),n("li",[n("p",[t._v("The form should specify the username in a parameter named "),n("code",[t._v("username")])])]),t._v(""),n("li",[n("p",[t._v("The form should specify the password in a parameter named "),n("code",[t._v("password")])])]),t._v(""),n("li",[n("p",[t._v("If the HTTP parameter error is found, it indicates the user failed to provide a valid username / password")])]),t._v(""),n("li",[n("p",[t._v("If the HTTP parameter logout is found, it indicates the user has logged out successfully")])])]),t._v(""),n("p",[t._v("Many users will not need much more than to customize the log in page.\nHowever, if needed, everything above can be customized with additional configuration.")]),t._v(""),n("p",[t._v("If you are using Spring MVC, you will need a controller that maps "),n("code",[t._v("GET /login")]),t._v(" to the login template we created.\nA minimal sample "),n("code",[t._v("LoginController")]),t._v(" can be seen below:")]),t._v(""),n("p",[t._v("Example 4. LoginController")]),t._v(""),n("p",[t._v("Java")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v('@Controller\nclass LoginController {\n\t@GetMapping("/login")\n\tString login() {\n\t\treturn "login";\n\t}\n}\n')])])]),n("p",[t._v("Kotlin")]),t._v(""),n("div",{staticClass:"language- extra-class"},[n("pre",{pre:!0,attrs:{class:"language-text"}},[n("code",[t._v('@Controller\nclass LoginController {\n @GetMapping("/login")\n fun login(): String {\n return "login"\n }\n}\n')])])]),n("p",[n("RouterLink",{attrs:{to:"/en/spring-security/input.html"}},[t._v("Reading Username/Password")]),n("RouterLink",{attrs:{to:"/en/spring-security/basic.html"}},[t._v("Basic")])],1)])}),[],!1,null,null,null);e.default=r.exports}}]);
