From b8a362a60f456b55389fe85ceddd3d0c2f528dab Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Fri, 30 Jul 2021 13:52:15 -0500 Subject: [PATCH] Remove include servlet/saml2/index.adoc --- .../ROOT/pages/overview/whats-new.adoc | 2 +- .../ROOT/pages/servlet/appendix/faq.adoc | 82 +- .../pages/servlet/appendix/namespace.adoc | 458 ++--- .../pages/servlet/appendix/proxy-server.adoc | 2 +- .../servlet/authentication/anonymous.adoc | 10 +- .../pages/servlet/authentication/cas.adoc | 22 +- .../pages/servlet/authentication/events.adoc | 6 +- .../pages/servlet/authentication/jaas.adoc | 20 +- .../pages/servlet/authentication/logout.adoc | 12 +- .../pages/servlet/authentication/openid.adoc | 4 +- .../pages/servlet/authentication/preauth.adoc | 20 +- .../servlet/authentication/rememberme.adoc | 14 +- .../pages/servlet/authentication/runas.adoc | 6 +- .../authentication/session-management.adoc | 16 +- .../pages/servlet/authentication/x509.adoc | 8 +- .../pages/servlet/authorization/acls.adoc | 8 +- .../authorization/expression-based.adoc | 26 +- .../authorization/method-security.adoc | 16 +- .../servlet/authorization/secure-objects.adoc | 8 +- .../servlet/integrations/concurrency.adoc | 8 +- .../ROOT/pages/servlet/integrations/cors.adoc | 2 +- .../ROOT/pages/servlet/integrations/data.adoc | 6 +- .../pages/servlet/integrations/jackson.adoc | 2 +- .../servlet/integrations/jsp-taglibs.adoc | 16 +- .../servlet/integrations/localization.adoc | 2 +- .../ROOT/pages/servlet/integrations/mvc.adoc | 16 +- .../servlet/integrations/servlet-api.adoc | 26 +- .../pages/servlet/integrations/websocket.adoc | 32 +- .../ROOT/pages/servlet/saml2/index.adoc | 1616 ++++++++++++++++- .../ROOT/pages/servlet/test/method.adoc | 14 +- .../ROOT/pages/servlet/test/mockmvc.adoc | 66 +- 31 files changed, 2080 insertions(+), 466 deletions(-) diff --git a/docs/modules/ROOT/pages/overview/whats-new.adoc b/docs/modules/ROOT/pages/overview/whats-new.adoc index 3117f3dad1..1bfb085a41 100644 --- a/docs/modules/ROOT/pages/overview/whats-new.adoc +++ b/docs/modules/ROOT/pages/overview/whats-new.adoc @@ -1,5 +1,5 @@ [[new]] -== What's New in Spring Security 5.6 += What's New in Spring Security 5.6 Spring Security 5.6 provides a number of new features. Below are the highlights of the release. diff --git a/docs/modules/ROOT/pages/servlet/appendix/faq.adoc b/docs/modules/ROOT/pages/servlet/appendix/faq.adoc index 911f173982..87dcff4564 100644 --- a/docs/modules/ROOT/pages/servlet/appendix/faq.adoc +++ b/docs/modules/ROOT/pages/servlet/appendix/faq.adoc @@ -1,5 +1,5 @@ [[appendix-faq]] -== Spring Security FAQ += Spring Security FAQ * <> * <> @@ -7,7 +7,7 @@ * <> [[appendix-faq-general-questions]] -=== General Questions +== General Questions . <> . <> @@ -16,7 +16,7 @@ [[appendix-faq-other-concerns]] -==== Will Spring Security take care of all my application security requirements? +=== Will Spring Security take care of all my application security requirements? Spring Security provides you with a very flexible framework for your authentication and authorization requirements, but there are many other considerations for building a secure application that are outside its scope. Web applications are vulnerable to all kinds of attacks which you should be familiar with, preferably before you start development so you can design and code with them in mind from the beginning. @@ -24,7 +24,7 @@ Check out the https://www.owasp.org/[OWASP web site] for information on the majo [[appendix-faq-web-xml]] -==== Why not just use web.xml security? +=== Why not just use web.xml security? Let's assume you're developing an enterprise application based on Spring. There are four security concerns you typically need to address: authentication, web request security, service layer security (i.e. your methods that implement business logic), and domain object instance security (i.e. different domain objects have different permissions). With these typical requirements in mind: @@ -64,7 +64,7 @@ Although when considered within the context of web container portability, config [[appendix-faq-requirements]] -==== What Java and Spring Framework versions are required? +=== What Java and Spring Framework versions are required? Spring Security 3.0 and 3.1 require at least JDK 1.5 and also require Spring 3.0.3 as a minimum. Ideally you should be using the latest release versions to avoid problems. @@ -74,7 +74,7 @@ It should also be compatible with applications using Spring 2.5.x. [[appendix-faq-start-simple]] -==== I'm new to Spring Security and I need to build an application that supports CAS single sign-on over HTTPS, while allowing Basic authentication locally for certain URLs, authenticating against multiple back end user information sources (LDAP and JDBC). I've copied some configuration files I found but it doesn't work. +=== I'm new to Spring Security and I need to build an application that supports CAS single sign-on over HTTPS, while allowing Basic authentication locally for certain URLs, authenticating against multiple back end user information sources (LDAP and JDBC). I've copied some configuration files I found but it doesn't work. What could be wrong? Or substitute an alternative complex scenario... @@ -92,7 +92,7 @@ This will take you through a series of steps to get up and running and get some If you are using other technologies which you aren't familiar with then you should do some research and try to make sure you can use them in isolation before combining them in a complex system. [[appendix-faq-common-problems]] -=== Common Problems +== Common Problems . Authentication .. <> @@ -115,7 +115,7 @@ If you are using other technologies which you aren't familiar with then you shou .. <> [[appendix-faq-bad-credentials]] -==== When I try to log in, I get an error message that says "Bad Credentials". What's wrong? +=== When I try to log in, I get an error message that says "Bad Credentials". What's wrong? This means that authentication has failed. It doesn't say why, as it is good practice to avoid giving details which might help an attacker guess account names or passwords. @@ -129,7 +129,7 @@ If you are using hashed passwords, make sure the value stored in your database i [[appendix-faq-login-loop]] -==== My application goes into an "endless loop" when I try to login, what's going on? +=== My application goes into an "endless loop" when I try to login, what's going on? A common user problem with infinite loop and redirecting to the login page is caused by accidentally configuring the login page as a "secured" resource. Make sure your configuration allows anonymous access to the login page, either by excluding it from the security filter chain or marking it as requiring ROLE_ANONYMOUS. @@ -140,7 +140,7 @@ From Spring Security 2.0.1 onwards, when you are using namespace-based configura [[appendix-faq-anon-access-denied]] -==== I get an exception with the message "Access is denied (user is anonymous);". What's wrong? +=== I get an exception with the message "Access is denied (user is anonymous);". What's wrong? This is a debug level message which occurs the first time an anonymous user attempts to access a protected resource. @@ -158,7 +158,7 @@ It is normal and shouldn't be anything to worry about. [[appendix-faq-cached-secure-page]] -==== Why can I still see a secured page even after I've logged out of my application? +=== Why can I still see a secured page even after I've logged out of my application? The most common reason for this is that your browser has cached the page and you are seeing a copy which is being retrieved from the browsers cache. Verify this by checking whether the browser is actually sending the request (check your server access logs, the debug log or use a suitable browser debugging plugin such as "Tamper Data" for Firefox). This has nothing to do with Spring Security and you should configure your application or server to set the appropriate `Cache-Control` response headers. @@ -166,7 +166,7 @@ Note that SSL requests are never cached. [[auth-exception-credentials-not-found]] -==== I get an exception with the message "An Authentication object was not found in the SecurityContext". What's wrong? +=== I get an exception with the message "An Authentication object was not found in the SecurityContext". What's wrong? This is a another debug level message which occurs the first time an anonymous user attempts to access a protected resource, but when you do not have an `AnonymousAuthenticationFilter` in your filter chain configuration. @@ -184,7 +184,7 @@ It is normal and shouldn't be anything to worry about. [[appendix-faq-ldap-authentication]] -==== I can't get LDAP authentication to work. +=== I can't get LDAP authentication to work. What's wrong with my configuration? Note that the permissions for an LDAP directory often do not allow you to read the password for a user. @@ -232,7 +232,7 @@ fun ldapAuthenticationIsSuccessful() { ---- ==== -==== Session Management +=== Session Management Session management issues are a common source of forum questions. If you are developing Java web applications, you should understand how the session is maintained between the servlet container and the user's browser. @@ -242,7 +242,7 @@ This is entirely handled by the servlet container. [[appendix-faq-concurrent-session-same-browser]] -==== I'm using Spring Security's concurrent session control to prevent users from logging in more than once at a time. +=== I'm using Spring Security's concurrent session control to prevent users from logging in more than once at a time. When I open another browser window after logging in, it doesn't stop me from logging in again. Why can I log in more than once? @@ -256,7 +256,7 @@ If they are already authenticated with the same session, then re-authenticating [[appendix-faq-new-session-on-authentication]] -==== Why does the session Id change when I authenticate through Spring Security? +=== Why does the session Id change when I authenticate through Spring Security? With the default configuration, Spring Security changes the session ID when the user authenticates. If you're using a Servlet 3.1 or newer container, the session ID is simply changed. @@ -266,7 +266,7 @@ You can find more about this online and in the reference manual. [[appendix-faq-tomcat-https-session]] -==== I'm using Tomcat (or some other servlet container) and have enabled HTTPS for my login page, switching back to HTTP afterwards. +=== I'm using Tomcat (or some other servlet container) and have enabled HTTPS for my login page, switching back to HTTP afterwards. It doesn't work - I just end up back at the login page after authenticating. This happens because sessions created under HTTPS, for which the session cookie is marked as "secure", cannot subsequently be used under HTTP. The browser will not send the cookie back to the server and any session state will be lost (including the security context information). Starting a session in HTTP first should work as the session cookie won't be marked as secure. @@ -278,13 +278,13 @@ Even clicking on an HTTPS link from a page accessed over HTTP is potentially ris If you need more convincing, check out a tool like https://github.com/moxie0/sslstrip/[sslstrip]. -==== I'm not switching between HTTP and HTTPS but my session is still getting lost +=== I'm not switching between HTTP and HTTPS but my session is still getting lost Sessions are maintained either by exchanging a session cookie or by adding a `jsessionid` parameter to URLs (this happens automatically if you are using JSTL to output URLs, or if you call `HttpServletResponse.encodeUrl` on URLs (before a redirect, for example). If clients have cookies disabled, and you are not rewriting URLs to include the `jsessionid`, then the session will be lost. Note that the use of cookies is preferred for security reasons, as it does not expose the session information in the URL. [[appendix-faq-session-listener-missing]] -==== I'm trying to use the concurrent session-control support but it won't let me log back in, even if I'm sure I've logged out and haven't exceeded the allowed sessions. +=== I'm trying to use the concurrent session-control support but it won't let me log back in, even if I'm sure I've logged out and haven't exceeded the allowed sessions. Make sure you have added the listener to your web.xml file. It is essential to make sure that the Spring Security session registry is notified when a session is destroyed. @@ -299,7 +299,7 @@ Without it, the session information will not be removed from the registry. ---- [[appendix-faq-unwanted-session-creation]] -==== Spring Security is creating a session somewhere, even though I've configured it not to, by setting the create-session attribute to never. +=== Spring Security is creating a session somewhere, even though I've configured it not to, by setting the create-session attribute to never. This usually means that the user's application is creating a session somewhere, but that they aren't aware of it. The most common culprit is a JSP. Many people aren't aware that JSPs create sessions by default. @@ -308,19 +308,19 @@ To prevent a JSP from creating a session, add the directive `<%@ page session="f If you are having trouble working out where a session is being created, you can add some debugging code to track down the location(s). One way to do this would be to add a `javax.servlet.http.HttpSessionListener` to your application, which calls `Thread.dumpStack()` in the `sessionCreated` method. [[appendix-faq-forbidden-csrf]] -==== I get a 403 Forbidden when performing a POST +=== I get a 403 Forbidden when performing a POST If an HTTP 403 Forbidden is returned for HTTP POST, but works for HTTP GET then the issue is most likely related to https://docs.spring.io/spring-security/site/docs/3.2.x/reference/htmlsingle/#csrf[CSRF]. Either provide the CSRF Token or disable CSRF protection (not recommended). [[appendix-faq-no-security-on-forward]] -==== I'm forwarding a request to another URL using the RequestDispatcher, but my security constraints aren't being applied. +=== I'm forwarding a request to another URL using the RequestDispatcher, but my security constraints aren't being applied. Filters are not applied by default to forwards or includes. If you really want the security filters to be applied to forwards and/or includes, then you have to configure these explicitly in your web.xml using the element, a child element of . [[appendix-faq-method-security-in-web-context]] -==== I have added Spring Security's element to my application context but if I add security annotations to my Spring MVC controller beans (Struts actions etc.) then they don't seem to have an effect. +=== I have added Spring Security's element to my application context but if I add security annotations to my Spring MVC controller beans (Struts actions etc.) then they don't seem to have an effect. In a Spring web application, the application context which holds the Spring MVC beans for the dispatcher servlet is often separate from the main application context. It is often defined in a file called `myapp-servlet.xml`, where "myapp" is the name assigned to the Spring `DispatcherServlet` in `web.xml`. An application can have multiple ``DispatcherServlet``s, each with its own isolated application context. @@ -333,7 +333,7 @@ Generally we would recommend applying method security at the service layer rathe [[appendix-faq-no-filters-no-context]] -==== I have a user who has definitely been authenticated, but when I try to access the SecurityContextHolder during some requests, the Authentication is null. +=== I have a user who has definitely been authenticated, but when I try to access the SecurityContextHolder during some requests, the Authentication is null. Why can't I see the user information? If you have excluded the request from the security filter chain using the attribute `filters='none'` in the `` element that matches the URL pattern, then the `SecurityContextHolder` will not be populated for that request. @@ -341,12 +341,12 @@ Check the debug log to see whether the request is passing through the filter cha (You are reading the debug log, right?). [[appendix-faq-method-security-with-taglib]] -==== The authorize JSP Tag doesn't respect my method security annotations when using the URL attribute. +=== The authorize JSP Tag doesn't respect my method security annotations when using the URL attribute. Method security will not hide links when using the `url` attribute in `` because we cannot readily reverse engineer what URL is mapped to what controller endpoint as controllers can rely on headers, current user, etc to determine what method to invoke. [[appendix-faq-architecture]] -=== Spring Security Architecture Questions +== Spring Security Architecture Questions . <> . <> @@ -357,14 +357,14 @@ Method security will not hide links when using the `url` attribute in `> . <> @@ -453,7 +453,7 @@ See this https://spring.io/blog/2010/08/02/spring-security-in-google-app-engine/ [[appendix-faq-extra-login-fields]] -==== I need to login in with more information than just the username. +=== I need to login in with more information than just the username. How do I add support for extra login fields (e.g. a company name)? @@ -465,14 +465,14 @@ You will also need to customize the actual authentication process. If you are using a custom authentication token class, for example, you will have to write an `AuthenticationProvider` to handle it (or extend the standard `DaoAuthenticationProvider`). If you have concatenated the fields, you can implement your own `UserDetailsService` which splits them up and loads the appropriate user data for authentication. [[appendix-faq-matching-url-fragments]] -==== How do I apply different intercept-url constraints where only the fragment value of the requested URLs differs (e.g./foo#bar and /foo#blah? +=== How do I apply different intercept-url constraints where only the fragment value of the requested URLs differs (e.g./foo#bar and /foo#blah? You can't do this, since the fragment is not transmitted from the browser to the server. The URLs above are identical from the server's perspective. This is a common question from GWT users. [[appendix-faq-request-details-in-user-service]] -==== How do I access the user's IP Address (or other web-request data) in a UserDetailsService? +=== How do I access the user's IP Address (or other web-request data) in a UserDetailsService? Obviously you can't (without resorting to something like thread-local variables) since the only information supplied to the interface is the username. Instead of implementing `UserDetailsService`, you should implement `AuthenticationProvider` directly and extract the information from the supplied `Authentication` token. @@ -482,7 +482,7 @@ If you are using the namespace, for example with the `` element, the [[appendix-faq-access-session-from-user-service]] -==== How do I access the HttpSession from a UserDetailsService? +=== How do I access the HttpSession from a UserDetailsService? You can't, since the `UserDetailsService` has no awareness of the servlet API. If you want to store custom user data, then you should customize the `UserDetails` object which is returned. This can then be accessed at any point, via the thread-local `SecurityContextHolder`. A call to `SecurityContextHolder.getContext().getAuthentication().getPrincipal()` will return this custom object. @@ -491,14 +491,14 @@ If you really need to access the session, then it must be done by customizing th [[appendix-faq-password-in-user-service]] -==== How do I access the user's password in a UserDetailsService? +=== How do I access the user's password in a UserDetailsService? You can't (and shouldn't). You are probably misunderstanding its purpose. See "<>" above. [[appendix-faq-dynamic-url-metadata]] -==== How do I define the secured URLs within an application dynamically? +=== How do I define the secured URLs within an application dynamically? People often ask about how to store the mapping between secured URLs and security metadata attributes in a database, rather than in the application context. @@ -575,7 +575,7 @@ For more information, look at the code for `DefaultFilterInvocationSecurityMetad [[appendix-faq-ldap-authorities]] -==== How do I authenticate against LDAP but load user roles from a database? +=== How do I authenticate against LDAP but load user roles from a database? The `LdapAuthenticationProvider` bean (which handles normal LDAP authentication in Spring Security) is configured with two separate strategy interfaces, one which performs the authentication and one which loads the user authorities, called `LdapAuthenticator` and `LdapAuthoritiesPopulator` respectively. The `DefaultLdapAuthoritiesPopulator` loads the user authorities from the LDAP directory and has various configuration parameters to allow you to specify how these should be retrieved. @@ -637,7 +637,7 @@ You should also consult the Javadoc for the relevant classes and interfaces. [[appendix-faq-namespace-post-processor]] -==== I want to modify the property of a bean that is created by the namespace, but there is nothing in the schema to support it. +=== I want to modify the property of a bean that is created by the namespace, but there is nothing in the schema to support it. What can I do short of abandoning namespace use? The namespace functionality is intentionally limited, so it doesn't cover everything that you can do with plain beans. diff --git a/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc b/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc index f33d01b906..a2e029da6b 100644 --- a/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc +++ b/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc @@ -1,5 +1,5 @@ [[appendix-namespace]] -== The Security Namespace += The Security Namespace This appendix provides a reference to the elements available in the security namespace and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document). If you haven't used the namespace before, please read the <> on namespace configuration, as this is intended as a supplement to the information there. Using a good quality XML editor while editing a configuration based on the schema is recommended as this will provide contextual information on which elements and attributes are available as well as comments explaining their purpose. @@ -7,16 +7,16 @@ The namespace is written in https://relaxng.org/[RELAX NG] Compact format and la If you are familiar with this format, you may wish to examine the https://raw.githubusercontent.com/spring-projects/spring-security/main/config/src/main/resources/org/springframework/security/config/spring-security-4.1.rnc[schema file] directly. [[nsa-web]] -=== Web Application Security +== Web Application Security [[nsa-debug]] -==== +=== Enables Spring Security debugging infrastructure. This will provide human-readable (multi-line) debugging information to monitor requests coming into the security filters. This may include sensitive information, such as request parameters or headers, and should only be used in a development environment. [[nsa-http]] -==== +=== If you use an `` element within your application, a `FilterChainProxy` bean named "springSecurityFilterChain" is created and the configuration within the element is used to build a filter chain within `FilterChainProxy`. As of Spring Security 3.1, additional `http` elements can be used to add extra filter chains footnote:[See the pass:specialcharacters,macros[<>] for how to set up the mapping from your `web.xml` ]. @@ -34,7 +34,7 @@ These are fixed and cannot be replaced with alternatives. [[nsa-http-attributes]] -===== Attributes +==== Attributes The attributes on the `` element control some of the properties on the core filters. @@ -151,7 +151,7 @@ The default value is true. [[nsa-http-children]] -===== Child Elements of +==== Child Elements of * <> * <> * <> @@ -177,18 +177,18 @@ The default value is true. [[nsa-access-denied-handler]] -==== +=== This element allows you to set the `errorPage` property for the default `AccessDeniedHandler` used by the `ExceptionTranslationFilter`, using the <> attribute, or to supply your own implementation using the<> attribute. This is discussed in more detail in the section on the <>. [[nsa-access-denied-handler-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-access-denied-handler-attributes]] -===== Attributes +==== Attributes [[nsa-access-denied-handler-error-page]] @@ -202,12 +202,12 @@ Defines a reference to a Spring bean of type `AccessDeniedHandler`. [[nsa-cors]] -==== +=== This element allows for configuring a `CorsFilter`. If no `CorsFilter` or `CorsConfigurationSource` is specified and Spring MVC is on the classpath, a `HandlerMappingIntrospector` is used as the `CorsConfigurationSource`. [[nsa-cors-attributes]] -===== Attributes +==== Attributes The attributes on the `` element control the headers element. [[nsa-cors-ref]] @@ -219,12 +219,12 @@ Optional attribute that specifies the bean name of a `CorsFilter`. Optional attribute that specifies the bean name of a `CorsConfigurationSource` to be injected into a `CorsFilter` created by the XML namespace. [[nsa-cors-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-headers]] -==== +=== This element allows for configuring additional (security) headers to be send with the response. It enables easy configuration for several headers and also allows for setting custom headers through the <> element. Additional information, can be found in the <> section of the reference. @@ -248,7 +248,7 @@ https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] is a mechanism that w ** `Feature-Policy` - Can be set using the <> element, https://wicg.github.io/feature-policy/[Feature-Policy] is a mechanism that allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser. [[nsa-headers-attributes]] -===== Attributes +==== Attributes The attributes on the `` element control the headers element. @@ -264,14 +264,14 @@ The default is false (the headers are enabled). [[nsa-headers-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-headers-children]] -===== Child Elements of +==== Child Elements of * <> @@ -289,12 +289,12 @@ The default is false (the headers are enabled). [[nsa-cache-control]] -==== +=== Adds `Cache-Control`, `Pragma`, and `Expires` headers to ensure that the browser does not cache your secured pages. [[nsa-cache-control-attributes]] -===== Attributes +==== Attributes [[nsa-cache-control-disabled]] * **disabled** @@ -303,7 +303,7 @@ Default false. [[nsa-cache-control-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -311,13 +311,13 @@ Default false. [[nsa-hsts]] -==== +=== When enabled adds the https://tools.ietf.org/html/rfc6797[Strict-Transport-Security] header to the response for any secure request. This allows the server to instruct browsers to automatically use HTTPS for future requests. [[nsa-hsts-attributes]] -===== Attributes +==== Attributes [[nsa-hsts-disabled]] * **disabled** @@ -347,20 +347,20 @@ Specifies if preload should be included. Default false. [[nsa-hsts-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-hpkp]] -==== +=== When enabled adds the https://tools.ietf.org/html/rfc7469[Public Key Pinning Extension for HTTP] header to the response for any secure request. This allows HTTPS websites to resist impersonation by attackers using mis-issued or otherwise fraudulent certificates. [[nsa-hpkp-attributes]] -===== Attributes +==== Attributes [[nsa-hpkp-disabled]] * **disabled** @@ -391,28 +391,28 @@ Specifies the URI to which the browser should report pin validation failures. [[nsa-hpkp-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-pins]] -==== +=== The list of pins [[nsa-pins-children]] -===== Child Elements of +==== Child Elements of * <> [[nsa-pin]] -==== +=== A pin is specified using the base64-encoded SPKI fingerprint as value and the cryptographic hash algorithm as attribute [[nsa-pin-attributes]] -===== Attributes +==== Attributes [[nsa-pin-algorithm]] * **algorithm** @@ -421,19 +421,19 @@ Default is SHA256. [[nsa-pin-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-content-security-policy]] -==== +=== When enabled adds the https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] header to the response. CSP is a mechanism that web applications can leverage to mitigate content injection vulnerabilities, such as cross-site scripting (XSS). [[nsa-content-security-policy-attributes]] -===== Attributes +==== Attributes [[nsa-content-security-policy-policy-directives]] * **policy-directives** @@ -445,18 +445,18 @@ Set to true, to enable the Content-Security-Policy-Report-Only header for report Defaults to false. [[nsa-content-security-policy-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-referrer-policy]] -==== +=== When enabled adds the https://www.w3.org/TR/referrer-policy/[Referrer Policy] header to the response. [[nsa-referrer-policy-attributes]] -===== Attributes +==== Attributes [[nsa-referrer-policy-policy]] * **policy** @@ -464,37 +464,37 @@ The policy for the Referrer-Policy header. Default "no-referrer". [[nsa-referrer-policy-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-feature-policy]] -==== +=== When enabled adds the https://wicg.github.io/feature-policy/[Feature Policy] header to the response. [[nsa-feature-policy-attributes]] -===== Attributes +==== Attributes [[nsa-feature-policy-policy-directives]] * **policy-directives** The security policy directive(s) for the Feature-Policy header. [[nsa-feature-policy-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-frame-options]] -==== +=== When enabled adds the https://tools.ietf.org/html/draft-ietf-websec-x-frame-options[X-Frame-Options header] to the response, this allows newer browsers to do some security checks and prevent https://en.wikipedia.org/wiki/Clickjacking[clickjacking] attacks. [[nsa-frame-options-attributes]] -===== Attributes +==== Attributes [[nsa-frame-options-disabled]] * **disabled** @@ -515,34 +515,34 @@ On the other hand, if you specify SAMEORIGIN, you can still use the page in a fr [[nsa-frame-options-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-permissions-policy]] -==== +=== Adds the https://w3c.github.io/webappsec-permissions-policy/[Permissions-Policy header] to the response. [[nsa-permissions-policy-attributes]] -===== Attributes +==== Attributes [[nsa-permissions-policy-policy]] * **policy** The policy value to write for the `Permissions-Policy` header [[nsa-permissions-policy-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-xss-protection]] -==== +=== Adds the https://blogs.msdn.com/b/ie/archive/2008/07/02/ie8-security-part-iv-the-xss-filter.aspx[X-XSS-Protection header] to the response to assist in protecting against https://en.wikipedia.org/wiki/Cross-site_scripting#Non-Persistent[reflected / Type-1 Cross-Site Scripting (XSS)] attacks. This is in no-way a full protection to XSS attacks! [[nsa-xss-protection-attributes]] -===== Attributes +==== Attributes [[nsa-xss-protection-disabled]] @@ -564,20 +564,20 @@ Note that there are sometimes ways of bypassing this mode which can often times [[nsa-xss-protection-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-content-type-options]] -==== +=== Add the X-Content-Type-Options header with the value of nosniff to the response. This https://blogs.msdn.com/b/ie/archive/2008/09/02/ie8-security-part-vi-beta-2-update.aspx[disables MIME-sniffing] for IE8+ and Chrome extensions. [[nsa-content-type-options-attributes]] -===== Attributes +==== Attributes [[nsa-content-type-options-disabled]] * **disabled** @@ -585,7 +585,7 @@ Specifies if Content Type Options should be disabled. Default false. [[nsa-content-type-options-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -593,12 +593,12 @@ Default false. [[nsa-header]] -====
+===
Add additional headers to the response, both the name and value need to be specified. [[nsa-header-attributes]] -===== Attributes +==== Attributes [[nsa-header-name]] @@ -617,7 +617,7 @@ Reference to a custom implementation of the `HeaderWriter` interface. [[nsa-header-parents]] -===== Parent Elements of
+==== Parent Elements of
* <> @@ -625,13 +625,13 @@ Reference to a custom implementation of the `HeaderWriter` interface. [[nsa-anonymous]] -==== +=== Adds an `AnonymousAuthenticationFilter` to the stack and an `AnonymousAuthenticationProvider`. Required if you are using the `IS_AUTHENTICATED_ANONYMOUSLY` attribute. [[nsa-anonymous-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -639,7 +639,7 @@ Required if you are using the `IS_AUTHENTICATED_ANONYMOUSLY` attribute. [[nsa-anonymous-attributes]] -===== Attributes +==== Attributes [[nsa-anonymous-enabled]] @@ -671,14 +671,14 @@ if unset, defaults to `anonymousUser`. [[nsa-csrf]] -==== +=== This element will add https://en.wikipedia.org/wiki/Cross-site_request_forgery[Cross Site Request Forger (CSRF)] protection to the application. It also updates the default RequestCache to only replay "GET" requests upon successful authentication. Additional information can be found in the <> section of the reference. [[nsa-csrf-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -686,7 +686,7 @@ Additional information can be found in the < Attributes +==== Attributes [[nsa-csrf-disabled]] * **disabled** @@ -707,14 +707,14 @@ Default is any HTTP method except "GET", "TRACE", "HEAD", "OPTIONS". [[nsa-custom-filter]] -==== +=== This element is used to add a filter to the filter chain. It doesn't create any additional beans but is used to select a bean of type `javax.servlet.Filter` which is already defined in the application context and add that at a particular position in the filter chain maintained by Spring Security. Full details can be found in the <>. [[nsa-custom-filter-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -722,7 +722,7 @@ Full details can be found in the <>. [[nsa-custom-filter-attributes]] -===== Attributes +==== Attributes [[nsa-custom-filter-after]] @@ -749,13 +749,13 @@ Defines a reference to a Spring bean that implements `Filter`. [[nsa-expression-handler]] -==== +=== Defines the `SecurityExpressionHandler` instance which will be used if expression-based access-control is enabled. A default implementation (with no ACL support) will be used if not supplied. [[nsa-expression-handler-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -766,7 +766,7 @@ A default implementation (with no ACL support) will be used if not supplied. [[nsa-expression-handler-attributes]] -===== Attributes +==== Attributes [[nsa-expression-handler-ref]] @@ -775,7 +775,7 @@ Defines a reference to a Spring bean that implements `SecurityExpressionHandler` [[nsa-form-login]] -==== +=== Used to add an `UsernamePasswordAuthenticationFilter` to the filter stack and an `LoginUrlAuthenticationEntryPoint` to the application context to provide authentication on demand. This will always take precedence over other namespace-created entry points. If no attributes are supplied, a login page will be generated automatically at the URL "/login" footnote:[ @@ -785,7 +785,7 @@ The class `DefaultLoginPageGeneratingFilter` is responsible for rendering the lo [[nsa-form-login-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -793,7 +793,7 @@ The class `DefaultLoginPageGeneratingFilter` is responsible for rendering the lo [[nsa-form-login-attributes]] -===== Attributes +==== Attributes [[nsa-form-login-always-use-default-target]] @@ -870,17 +870,17 @@ Maps a `ForwardAuthenticationFailureHandler` to `authenticationFailureHandler` p [[nsa-oauth2-login]] -==== +=== The <> feature configures authentication support using an OAuth 2.0 and/or OpenID Connect 1.0 Provider. [[nsa-oauth2-login-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-oauth2-login-attributes]] -===== Attributes +==== Attributes [[nsa-oauth2-login-client-registration-repository-ref]] @@ -954,17 +954,17 @@ Reference to the `JwtDecoderFactory` used by `OidcAuthorizationCodeAuthenticatio [[nsa-oauth2-client]] -==== +=== Configures <> support. [[nsa-oauth2-client-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-oauth2-client-attributes]] -===== Attributes +==== Attributes [[nsa-oauth2-client-client-registration-repository-ref]] @@ -983,24 +983,24 @@ Reference to the `OAuth2AuthorizedClientService`. [[nsa-oauth2-client-children]] -===== Child Elements of +==== Child Elements of * <> [[nsa-authorization-code-grant]] -==== +=== Configures <>. [[nsa-authorization-code-grant-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-authorization-code-grant-attributes]] -===== Attributes +==== Attributes [[nsa-authorization-code-grant-authorization-request-repository-ref]] @@ -1019,30 +1019,30 @@ Reference to the `OAuth2AccessTokenResponseClient`. [[nsa-client-registrations]] -==== +=== A container element for client(s) registered (<>) with an OAuth 2.0 or OpenID Connect 1.0 Provider. [[nsa-client-registrations-children]] -===== Child Elements of +==== Child Elements of * <> * <> [[nsa-client-registration]] -==== +=== Represents a client registered with an OAuth 2.0 or OpenID Connect 1.0 Provider. [[nsa-client-registration-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-client-registration-attributes]] -===== Attributes +==== Attributes [[nsa-client-registration-registration-id]] @@ -1093,18 +1093,18 @@ A reference to the associated provider. May reference a `` element or [[nsa-provider]] -==== +=== The configuration information for an OAuth 2.0 or OpenID Connect 1.0 Provider. [[nsa-provider-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-provider-attributes]] -===== Attributes +==== Attributes [[nsa-provider-provider-id]] @@ -1148,23 +1148,23 @@ The URI used to retrieve the https://tools.ietf.org/html/rfc7517[JSON Web Key (J The URI used to initially configure a `ClientRegistration` using discovery of an OpenID Connect Provider's https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Configuration endpoint] or an Authorization Server's https://tools.ietf.org/html/rfc8414#section-3[Metadata endpoint]. [[nsa-oauth2-resource-server]] -==== +=== Adds a `BearerTokenAuthenticationFilter`, `BearerTokenAuthenticationEntryPoint`, and `BearerTokenAccessDeniedHandler` to the configuration. In addition, either `` or `` must be specified. [[nsa-oauth2-resource-server-parents]] -===== Parents Elements of +==== Parents Elements of * <> [[nsa-oauth2-resource-server-children]] -===== Child Elements of +==== Child Elements of * <> * <> [[nsa-oauth2-resource-server-attributes]] -===== Attributes +==== Attributes [[nsa-oauth2-resource-server-authentication-manager-resolver-ref]] * **authentication-manager-resolver-ref** @@ -1179,18 +1179,18 @@ Reference to a `BearerTokenResolver` which will retrieve the bearer token from t Reference to a `AuthenticationEntryPoint` which will handle unauthorized requests [[nsa-jwt]] -==== +=== Represents an OAuth 2.0 Resource Server that will authorize JWTs [[nsa-jwt-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-jwt-attributes]] -===== Attributes +==== Attributes [[nsa-jwt-jwt-authentication-converter-ref]] * **jwt-authentication-converter-ref** @@ -1205,16 +1205,16 @@ Reference to a `JwtDecoder`. This is a larger component that overrides `jwk-set- The JWK Set Uri used to load signing verification keys from an OAuth 2.0 Authorization Server [[nsa-opaque-token]] -==== +=== Represents an OAuth 2.0 Resource Server that will authorize opaque tokens [[nsa-opaque-token-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-opaque-token-attributes]] -===== Attributes +==== Attributes [[nsa-opaque-token-introspector-ref]] * **introspector-ref** @@ -1233,13 +1233,13 @@ The Client Id to use for client authentication against the provided `introspecti The Client Secret to use for client authentication against the provided `introspection-uri`. [[nsa-http-basic]] -==== +=== Adds a `BasicAuthenticationFilter` and `BasicAuthenticationEntryPoint` to the configuration. The latter will only be used as the configuration entry point if form-based login is not enabled. [[nsa-http-basic-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1247,7 +1247,7 @@ The latter will only be used as the configuration entry point if form-based logi [[nsa-http-basic-attributes]] -===== Attributes +==== Attributes [[nsa-http-basic-authentication-details-source-ref]] @@ -1261,13 +1261,13 @@ Sets the `AuthenticationEntryPoint` which is used by the `BasicAuthenticationFil [[nsa-http-firewall]] -==== Element +=== Element This is a top-level element which can be used to inject a custom implementation of `HttpFirewall` into the `FilterChainProxy` created by the namespace. The default implementation should be suitable for most applications. [[nsa-http-firewall-attributes]] -===== Attributes +==== Attributes [[nsa-http-firewall-ref]] @@ -1276,7 +1276,7 @@ Defines a reference to a Spring bean that implements `HttpFirewall`. [[nsa-intercept-url]] -==== +=== This element is used to define the set of URL patterns that the application is interested in and to configure how they should be handled. It is used to construct the `FilterInvocationSecurityMetadataSource` used by the `FilterSecurityInterceptor`. It is also responsible for configuring a `ChannelProcessingFilter` if particular URLs need to be accessed by HTTPS, for example. @@ -1285,7 +1285,7 @@ So the most specific patterns should come first and the most general should come [[nsa-intercept-url-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1294,7 +1294,7 @@ So the most specific patterns should come first and the most general should come [[nsa-intercept-url-attributes]] -===== Attributes +==== Attributes [[nsa-intercept-url-access]] @@ -1341,12 +1341,12 @@ NOTE: This property is invalid for < +=== Adds a J2eePreAuthenticatedProcessingFilter to the filter chain to provide integration with container authentication. [[nsa-jee-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1354,7 +1354,7 @@ Adds a J2eePreAuthenticatedProcessingFilter to the filter chain to provide integ [[nsa-jee-attributes]] -===== Attributes +==== Attributes [[nsa-jee-mappable-roles]] @@ -1368,13 +1368,13 @@ A reference to a user-service (or UserDetailsService bean) Id [[nsa-logout]] -==== +=== Adds a `LogoutFilter` to the filter stack. This is configured with a `SecurityContextLogoutHandler`. [[nsa-logout-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1382,7 +1382,7 @@ This is configured with a `SecurityContextLogoutHandler`. [[nsa-logout-attributes]] -===== Attributes +==== Attributes [[nsa-logout-delete-cookies]] @@ -1419,7 +1419,7 @@ May be used to supply an instance of `LogoutSuccessHandler` which will be invoke [[nsa-openid-login]] -==== +=== Similar to `` and has the same attributes. The default value for `login-processing-url` is "/login/openid". An `OpenIDAuthenticationFilter` and `OpenIDAuthenticationProvider` will be registered. @@ -1428,7 +1428,7 @@ Again, this can be specified by `id`, using the `user-service-ref` attribute, or [[nsa-openid-login-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1436,7 +1436,7 @@ Again, this can be specified by `id`, using the `user-service-ref` attribute, or [[nsa-openid-login-attributes]] -===== Attributes +==== Attributes [[nsa-openid-login-always-use-default-target]] @@ -1514,13 +1514,13 @@ Defaults to "username". [[nsa-openid-login-children]] -===== Child Elements of +==== Child Elements of * <> [[nsa-attribute-exchange]] -==== +=== The `attribute-exchange` element defines the list of attributes which should be requested from the identity provider. An example can be found in the <> section of the namespace configuration chapter. More than one can be used, in which case each must have an `identifier-match` attribute, containing a regular expression which is matched against the supplied OpenID identifier. @@ -1528,7 +1528,7 @@ This allows different attribute lists to be fetched from different providers (Go [[nsa-attribute-exchange-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1536,7 +1536,7 @@ This allows different attribute lists to be fetched from different providers (Go [[nsa-attribute-exchange-attributes]] -===== Attributes +==== Attributes [[nsa-attribute-exchange-identifier-match]] @@ -1545,7 +1545,7 @@ A regular expression which will be compared against the claimed identity, when d [[nsa-attribute-exchange-children]] -===== Child Elements of +==== Child Elements of * <> @@ -1553,12 +1553,12 @@ A regular expression which will be compared against the claimed identity, when d [[nsa-openid-attribute]] -==== +=== Attributes used when making an OpenID AX https://openid.net/specs/openid-attribute-exchange-1_0.html#fetch_request[ Fetch Request] [[nsa-openid-attribute-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1566,7 +1566,7 @@ Attributes used when making an OpenID AX https://openid.net/specs/openid-attribu [[nsa-openid-attribute-attributes]] -===== Attributes +==== Attributes [[nsa-openid-attribute-count]] @@ -1595,23 +1595,23 @@ For example, https://axschema.org/contact/email. See your OP's documentation for valid attribute types. [[nsa-password-management]] -==== +=== This element configures password management. [[nsa-password-management-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-password-management-attributes]] -===== Attributes +==== Attributes [[nsa-password-management-change-password-page]] * **change-password-page** The change password page. Defaults to "/change-password". [[nsa-port-mappings]] -==== +=== By default, an instance of `PortMapperImpl` will be added to the configuration for use in redirecting to secure and insecure URLs. This element can optionally be used to override the default mappings which that class defines. Each child `` element defines a pair of HTTP:HTTPS ports. @@ -1620,7 +1620,7 @@ An example of overriding these can be found in <>. [[nsa-port-mappings-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1628,7 +1628,7 @@ An example of overriding these can be found in <>. [[nsa-port-mappings-children]] -===== Child Elements of +==== Child Elements of * <> @@ -1636,12 +1636,12 @@ An example of overriding these can be found in <>. [[nsa-port-mapping]] -==== +=== Provides a method to map http ports to https ports when forcing a redirect. [[nsa-port-mapping-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1649,7 +1649,7 @@ Provides a method to map http ports to https ports when forcing a redirect. [[nsa-port-mapping-attributes]] -===== Attributes +==== Attributes [[nsa-port-mapping-http]] @@ -1663,13 +1663,13 @@ The https port to use. [[nsa-remember-me]] -==== +=== Adds the `RememberMeAuthenticationFilter` to the stack. This in turn will be configured with either a `TokenBasedRememberMeServices`, a `PersistentTokenBasedRememberMeServices` or a user-specified bean implementing `RememberMeServices` depending on the attribute settings. [[nsa-remember-me-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1677,7 +1677,7 @@ This in turn will be configured with either a `TokenBasedRememberMeServices`, a [[nsa-remember-me-attributes]] -===== Attributes +==== Attributes [[nsa-remember-me-authentication-success-handler-ref]] @@ -1757,17 +1757,17 @@ If there are multiple instances, you can specify a bean `id` explicitly using th [[nsa-request-cache]] -==== Element +=== Element Sets the `RequestCache` instance which will be used by the `ExceptionTranslationFilter` to store request information before invoking an `AuthenticationEntryPoint`. [[nsa-request-cache-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-request-cache-attributes]] -===== Attributes +==== Attributes [[nsa-request-cache-ref]] @@ -1776,12 +1776,12 @@ Defines a reference to a Spring bean that is a `RequestCache`. [[nsa-session-management]] -==== +=== Session-management related functionality is implemented by the addition of a `SessionManagementFilter` to the filter stack. [[nsa-session-management-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1789,7 +1789,7 @@ Session-management related functionality is implemented by the addition of a `Se [[nsa-session-management-attributes]] -===== Attributes +==== Attributes [[nsa-session-management-invalid-session-url]] @@ -1831,7 +1831,7 @@ See the Javadoc for this class for more details. [[nsa-session-management-children]] -===== Child Elements of +==== Child Elements of * <> @@ -1839,7 +1839,7 @@ See the Javadoc for this class for more details. [[nsa-concurrency-control]] -==== +=== Adds support for concurrent session control, allowing limits to be placed on the number of active sessions a user can have. A `ConcurrentSessionFilter` will be created, and a `ConcurrentSessionControlAuthenticationStrategy` will be used with the `SessionManagementFilter`. If a `form-login` element has been declared, the strategy object will also be injected into the created authentication filter. @@ -1847,7 +1847,7 @@ An instance of `SessionRegistry` (a `SessionRegistryImpl` instance unless the us [[nsa-concurrency-control-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1855,7 +1855,7 @@ An instance of `SessionRegistry` (a `SessionRegistryImpl` instance unless the us [[nsa-concurrency-control-attributes]] -===== Attributes +==== Attributes [[nsa-concurrency-control-error-if-maximum-exceeded]] @@ -1893,7 +1893,7 @@ The other concurrent session control beans will be wired up to use it. [[nsa-x509]] -==== +=== Adds support for X.509 authentication. An `X509AuthenticationFilter` will be added to the stack and an `Http403ForbiddenEntryPoint` bean will be created. The latter will only be used if no other authentication mechanisms are in use (its only functionality is to return an HTTP 403 error code). @@ -1901,7 +1901,7 @@ A `PreAuthenticatedAuthenticationProvider` will also be created which delegates [[nsa-x509-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1909,7 +1909,7 @@ A `PreAuthenticatedAuthenticationProvider` will also be created which delegates [[nsa-x509-attributes]] -===== Attributes +==== Attributes [[nsa-x509-authentication-details-source-ref]] @@ -1929,12 +1929,12 @@ If not set, an attempt will be made to locate a suitable instance automatically [[nsa-filter-chain-map]] -==== +=== Used to explicitly configure a FilterChainProxy instance with a FilterChainMap [[nsa-filter-chain-map-attributes]] -===== Attributes +==== Attributes [[nsa-filter-chain-map-request-matcher]] @@ -1944,7 +1944,7 @@ Currently the options are 'ant' (for ant path patterns), 'regex' for regular exp [[nsa-filter-chain-map-children]] -===== Child Elements of +==== Child Elements of * <> @@ -1952,13 +1952,13 @@ Currently the options are 'ant' (for ant path patterns), 'regex' for regular exp [[nsa-filter-chain]] -==== +=== Used within to define a specific URL pattern and the list of filters which apply to the URLs matching that pattern. When multiple filter-chain elements are assembled in a list in order to configure a FilterChainProxy, the most specific patterns must be placed at the top of the list, with most general ones at the bottom. [[nsa-filter-chain-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -1966,7 +1966,7 @@ When multiple filter-chain elements are assembled in a list in order to configur [[nsa-filter-chain-attributes]] -===== Attributes +==== Attributes [[nsa-filter-chain-filters]] @@ -1986,7 +1986,7 @@ A reference to a `RequestMatcher` that will be used to determine if any `Filter` [[nsa-filter-security-metadata-source]] -==== +=== Used to explicitly configure a FilterSecurityMetadataSource bean for use with a FilterSecurityInterceptor. Usually only needed if you are configuring a FilterChainProxy explicitly, rather than using the element. The intercept-url elements used should only contain pattern, method and access attributes. @@ -1994,7 +1994,7 @@ Any others will result in a configuration error. [[nsa-filter-security-metadata-source-attributes]] -===== Attributes +==== Attributes [[nsa-filter-security-metadata-source-id]] @@ -2017,19 +2017,19 @@ If the expression evaluates to 'true', access will be granted. [[nsa-filter-security-metadata-source-children]] -===== Child Elements of +==== Child Elements of * <> [[nsa-websocket-security]] -=== WebSocket Security +== WebSocket Security Spring Security 4.0+ provides support for authorizing messages. One concrete example of where this is useful is to provide authorization in WebSocket based applications. [[nsa-websocket-message-broker]] -==== +=== The websocket-message-broker element has two different modes. If the <> is not specified, then it will do the following things: @@ -2051,7 +2051,7 @@ This is more cumbersome, but provides greater control over the configuration. [[nsa-websocket-message-broker-attributes]] -===== Attributes +==== Attributes [[nsa-websocket-message-broker-id]] * **id** A bean identifier, used for referring to the ChannelSecurityInterceptor bean elsewhere in the context. @@ -2063,27 +2063,27 @@ If not specified, Spring Security will automatically integrate with the messagin Changing the default is useful if it is necessary to allow other origins to make SockJS connections. [[nsa-websocket-message-broker-children]] -===== Child Elements of +==== Child Elements of * <> * <> [[nsa-intercept-message]] -==== +=== Defines an authorization rule for a message. [[nsa-intercept-message-parents]] -===== Parent Elements of +==== Parent Elements of * <> [[nsa-intercept-message-attributes]] -===== Attributes +==== Attributes [[nsa-intercept-message-pattern]] * **pattern** An ant based pattern that matches on the Message destination. @@ -2098,7 +2098,7 @@ Valid values are defined in SimpMessageType (i.e. CONNECT, CONNECT_ACK, HEARTBEA For example, "denyAll" will deny access to all of the matching Messages; "permitAll" will grant access to all of the matching Messages; "hasRole('ADMIN') requires the current user to have the role 'ROLE_ADMIN' for the matching Messages. [[nsa-authentication]] -=== Authentication Services +== Authentication Services Before Spring Security 3.0, an `AuthenticationManager` was automatically registered internally. Now you must register one explicitly using the `` element. This creates an instance of Spring Security's `ProviderManager` class, which needs to be configured with a list of one or more `AuthenticationProvider` instances. @@ -2106,14 +2106,14 @@ These can either be created using syntax elements provided by the namespace, or [[nsa-authentication-manager]] -==== +=== Every Spring Security application which uses the namespace must have include this element somewhere. It is responsible for registering the `AuthenticationManager` which provides authentication services to the application. All elements which create `AuthenticationProvider` instances should be children of this element. [[nsa-authentication-manager-attributes]] -===== Attributes +==== Attributes [[nsa-authentication-manager-alias]] @@ -2134,7 +2134,7 @@ It is the same as the alias element, but provides a more consistent experience w [[nsa-authentication-manager-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2143,7 +2143,7 @@ It is the same as the alias element, but provides a more consistent experience w [[nsa-authentication-provider]] -==== +=== Unless used with a `ref` attribute, this element is shorthand for configuring a `DaoAuthenticationProvider`. `DaoAuthenticationProvider` loads user information from a `UserDetailsService` and compares the username/password combination with the values supplied at login. The `UserDetailsService` instance can be defined either by using an available namespace element (`jdbc-user-service` or by using the `user-service-ref` attribute to point to a bean defined elsewhere in the application context). @@ -2151,7 +2151,7 @@ The `UserDetailsService` instance can be defined either by using an available na [[nsa-authentication-provider-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2159,7 +2159,7 @@ The `UserDetailsService` instance can be defined either by using an available na [[nsa-authentication-provider-attributes]] -===== Attributes +==== Attributes [[nsa-authentication-provider-ref]] @@ -2187,7 +2187,7 @@ A reference to a bean that implements UserDetailsService that may be created usi [[nsa-authentication-provider-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2198,12 +2198,12 @@ A reference to a bean that implements UserDetailsService that may be created usi [[nsa-jdbc-user-service]] -==== +=== Causes creation of a JDBC-based UserDetailsService. [[nsa-jdbc-user-service-attributes]] -===== Attributes +==== Attributes [[nsa-jdbc-user-service-authorities-by-username-query]] @@ -2277,13 +2277,13 @@ select username, password, enabled from users where username = ? [[nsa-password-encoder]] -==== +=== Authentication providers can optionally be configured to use a password encoder as described in the <>. This will result in the bean being injected with the appropriate `PasswordEncoder` instance. [[nsa-password-encoder-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2292,7 +2292,7 @@ This will result in the bean being injected with the appropriate `PasswordEncode [[nsa-password-encoder-attributes]] -===== Attributes +==== Attributes [[nsa-password-encoder-hash]] @@ -2307,13 +2307,13 @@ Defines a reference to a Spring bean that implements `PasswordEncoder`. [[nsa-user-service]] -==== +=== Creates an in-memory UserDetailsService from a properties file or a list of "user" child elements. Usernames are converted to lower-case internally to allow for case-insensitive lookups, so this should not be used if case-sensitivity is required. [[nsa-user-service-attributes]] -===== Attributes +==== Attributes [[nsa-user-service-id]] @@ -2336,7 +2336,7 @@ username=password,grantedAuthority[,grantedAuthority][,enabled|disabled] [[nsa-user-service-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2344,12 +2344,12 @@ username=password,grantedAuthority[,grantedAuthority][,enabled|disabled] [[nsa-user]] -==== +=== Represents a user in the application. [[nsa-user-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2357,7 +2357,7 @@ Represents a user in the application. [[nsa-user-attributes]] -===== Attributes +==== Attributes [[nsa-user-authorities]] @@ -2392,15 +2392,15 @@ Cannot be empty. -=== Method Security +== Method Security [[nsa-method-security]] -==== +=== This element is the primary means of adding support for securing methods on Spring Security beans. Methods can be secured by the use of annotations (defined at the interface or class level) or by defining a set of pointcuts. [[nsa-method-security-attributes]] -===== attributes +==== attributes [[nsa-method-security-pre-post-enabled]] * **pre-post-enabled** @@ -2423,18 +2423,18 @@ If true, class based proxying will be used instead of interface based proxying. Defaults to "false". [[nsa-method-security-children]] -===== Child Elements of +==== Child Elements of * <> [[nsa-global-method-security]] -==== +=== This element is the primary means of adding support for securing methods on Spring Security beans. Methods can be secured by the use of annotations (defined at the interface or class level) or by defining a set of pointcuts as child elements, using AspectJ syntax. [[nsa-global-method-security-attributes]] -===== Attributes +==== Attributes [[nsa-global-method-security-access-decision-manager-ref]] @@ -2498,7 +2498,7 @@ Defaults to "disabled". [[nsa-global-method-security-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2509,13 +2509,13 @@ Defaults to "disabled". [[nsa-after-invocation-provider]] -==== +=== This element can be used to decorate an `AfterInvocationProvider` for use by the security interceptor maintained by the `` namespace. You can define zero or more of these within the `global-method-security` element, each with a `ref` attribute pointing to an `AfterInvocationProvider` bean instance within your application context. [[nsa-after-invocation-provider-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2523,7 +2523,7 @@ You can define zero or more of these within the `global-method-security` element [[nsa-after-invocation-provider-attributes]] -===== Attributes +==== Attributes [[nsa-after-invocation-provider-ref]] @@ -2532,13 +2532,13 @@ Defines a reference to a Spring bean that implements `AfterInvocationProvider`. [[nsa-pre-post-annotation-handling]] -==== +=== Allows the default expression-based mechanism for handling Spring Security's pre and post invocation annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) to be replaced entirely. Only applies if these annotations are enabled. [[nsa-pre-post-annotation-handling-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2546,7 +2546,7 @@ Only applies if these annotations are enabled. [[nsa-pre-post-annotation-handling-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2556,12 +2556,12 @@ Only applies if these annotations are enabled. [[nsa-invocation-attribute-factory]] -==== +=== Defines the PrePostInvocationAttributeFactory instance which is used to generate pre and post invocation metadata from the annotated methods. [[nsa-invocation-attribute-factory-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2569,7 +2569,7 @@ Defines the PrePostInvocationAttributeFactory instance which is used to generate [[nsa-invocation-attribute-factory-attributes]] -===== Attributes +==== Attributes [[nsa-invocation-attribute-factory-ref]] @@ -2578,12 +2578,12 @@ Defines a reference to a Spring bean Id. [[nsa-post-invocation-advice]] -==== +=== Customizes the `PostInvocationAdviceProvider` with the ref as the `PostInvocationAuthorizationAdvice` for the element. [[nsa-post-invocation-advice-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2591,7 +2591,7 @@ Customizes the `PostInvocationAdviceProvider` with the ref as the `PostInvocatio [[nsa-post-invocation-advice-attributes]] -===== Attributes +==== Attributes [[nsa-post-invocation-advice-ref]] @@ -2600,12 +2600,12 @@ Defines a reference to a Spring bean Id. [[nsa-pre-invocation-advice]] -==== +=== Customizes the `PreInvocationAuthorizationAdviceVoter` with the ref as the `PreInvocationAuthorizationAdviceVoter` for the element. [[nsa-pre-invocation-advice-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2613,7 +2613,7 @@ Customizes the `PreInvocationAuthorizationAdviceVoter` with the ref as the `PreI [[nsa-pre-invocation-advice-attributes]] -===== Attributes +==== Attributes [[nsa-pre-invocation-advice-ref]] @@ -2622,14 +2622,14 @@ Defines a reference to a Spring bean Id. [[nsa-protect-pointcut]] -==== Securing Methods using +=== Securing Methods using `` Rather than defining security attributes on an individual method or class basis using the `@Secured` annotation, you can define cross-cutting security constraints across whole sets of methods and interfaces in your service layer using the `` element. You can find an example in the <>. [[nsa-protect-pointcut-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2637,7 +2637,7 @@ You can find an example in the <>. [[nsa-protect-pointcut-attributes]] -===== Attributes +==== Attributes [[nsa-protect-pointcut-access]] @@ -2653,12 +2653,12 @@ For example, `execution(int com.foo.TargetObject.countLength(String))`. [[nsa-intercept-methods]] -==== +=== Can be used inside a bean definition to add a security interceptor to the bean and set up access configuration attributes for the bean's methods [[nsa-intercept-methods-attributes]] -===== Attributes +==== Attributes [[nsa-intercept-methods-access-decision-manager-ref]] @@ -2667,7 +2667,7 @@ Optional AccessDecisionManager bean ID to be used by the created method security [[nsa-intercept-methods-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2675,12 +2675,12 @@ Optional AccessDecisionManager bean ID to be used by the created method security [[nsa-method-security-metadata-source]] -==== +=== Creates a MethodSecurityMetadataSource instance [[nsa-method-security-metadata-source-attributes]] -===== Attributes +==== Attributes [[nsa-method-security-metadata-source-id]] @@ -2697,7 +2697,7 @@ If the expression evaluates to 'true', access will be granted. [[nsa-method-security-metadata-source-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2705,13 +2705,13 @@ If the expression evaluates to 'true', access will be granted. [[nsa-protect]] -==== +=== Defines a protected method and the access control configuration attributes that apply to it. We strongly advise you NOT to mix "protect" declarations with any services provided "global-method-security". [[nsa-protect-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2720,7 +2720,7 @@ We strongly advise you NOT to mix "protect" declarations with any services provi [[nsa-protect-attributes]] -===== Attributes +==== Attributes [[nsa-protect-access]] @@ -2735,14 +2735,14 @@ A method name [[nsa-ldap]] -=== LDAP Namespace Options +== LDAP Namespace Options LDAP is covered in some details in <>. We will expand on that here with some explanation of how the namespace options map to Spring beans. The LDAP implementation uses Spring LDAP extensively, so some familiarity with that project's API may be useful. [[nsa-ldap-server]] -==== Defining the LDAP Server using the +=== Defining the LDAP Server using the `` Element This element sets up a Spring LDAP `ContextSource` for use by the other LDAP beans, defining the location of the LDAP server and other information (such as a username and password, if it doesn't allow anonymous access) for connecting to it. It can also be used to create an embedded server for testing. @@ -2756,7 +2756,7 @@ This is actually the bean `id` of the `ContextSource` instance, if you want to u [[nsa-ldap-server-attributes]] -===== Attributes +==== Attributes [[nsa-ldap-server-mode]] * **mode** @@ -2805,14 +2805,14 @@ Specifies the ldap server URL when not using the embedded LDAP server. [[nsa-ldap-authentication-provider]] -==== +=== This element is shorthand for the creation of an `LdapAuthenticationProvider` instance. By default this will be configured with a `BindAuthenticator` instance and a `DefaultAuthoritiesPopulator`. As with all namespace authentication providers, it must be included as a child of the `authentication-provider` element. [[nsa-ldap-authentication-provider-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2820,7 +2820,7 @@ As with all namespace authentication providers, it must be included as a child o [[nsa-ldap-authentication-provider-attributes]] -===== Attributes +==== Attributes [[nsa-ldap-authentication-provider-group-role-attribute]] @@ -2905,7 +2905,7 @@ If these attributes aren't set and no `user-dn-pattern` has been supplied as an [[nsa-ldap-authentication-provider-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2913,12 +2913,12 @@ If these attributes aren't set and no `user-dn-pattern` has been supplied as an [[nsa-password-compare]] -==== +=== This is used as child element to `` and switches the authentication strategy from `BindAuthenticator` to `PasswordComparisonAuthenticator`. [[nsa-password-compare-parents]] -===== Parent Elements of +==== Parent Elements of * <> @@ -2926,7 +2926,7 @@ This is used as child element to `` and switches the authenticati [[nsa-password-compare-attributes]] -===== Attributes +==== Attributes [[nsa-password-compare-hash]] @@ -2942,7 +2942,7 @@ Defaults to "userPassword". [[nsa-password-compare-children]] -===== Child Elements of +==== Child Elements of * <> @@ -2950,14 +2950,14 @@ Defaults to "userPassword". [[nsa-ldap-user-service]] -==== +=== This element configures an LDAP `UserDetailsService`. The class used is `LdapUserDetailsService` which is a combination of a `FilterBasedLdapUserSearch` and a `DefaultLdapAuthoritiesPopulator`. The attributes it supports have the same usage as in ``. [[nsa-ldap-user-service-attributes]] -===== Attributes +==== Attributes [[nsa-ldap-user-service-cache-ref]] diff --git a/docs/modules/ROOT/pages/servlet/appendix/proxy-server.adoc b/docs/modules/ROOT/pages/servlet/appendix/proxy-server.adoc index 18d650bf45..ac3f182a16 100644 --- a/docs/modules/ROOT/pages/servlet/appendix/proxy-server.adoc +++ b/docs/modules/ROOT/pages/servlet/appendix/proxy-server.adoc @@ -1,5 +1,5 @@ [[appendix-proxy-server]] -== Proxy Server Configuration += Proxy Server Configuration When using a proxy server it is important to ensure that you have configured your application properly. For example, many applications will have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080 diff --git a/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc b/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc index eee0f8e6f4..b98e87e075 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc @@ -1,9 +1,9 @@ [[anonymous]] -== Anonymous Authentication += Anonymous Authentication [[anonymous-overview]] -=== Overview +== Overview It's generally considered good security practice to adopt a "deny-by-default" where you explicitly specify what is allowed and disallow everything else. Defining what is accessible to unauthenticated users is a similar situation, particularly for web applications. Many sites require that users must be authenticated for anything other than a few URLs (for example the home and login pages). @@ -21,7 +21,7 @@ Classes can be authored more robustly if they know the `SecurityContextHolder` a [[anonymous-config]] -=== Configuration +== Configuration Anonymous authentication support is provided automatically when using the HTTP configuration Spring Security 3.0 and can be customized (or disabled) using the `` element. You don't need to configure the beans described here unless you are using traditional bean configuration. @@ -88,7 +88,7 @@ For example: [[anonymous-auth-trust-resolver]] -=== AuthenticationTrustResolver +== AuthenticationTrustResolver Rounding out the anonymous authentication discussion is the `AuthenticationTrustResolver` interface, with its corresponding `AuthenticationTrustResolverImpl` implementation. This interface provides an `isAnonymous(Authentication)` method, which allows interested classes to take into account this special type of authentication status. The `ExceptionTranslationFilter` uses this interface in processing ``AccessDeniedException``s. @@ -102,7 +102,7 @@ The `AuthenticatedVoter` approach is more powerful, since it allows you to diffe If you don't need this functionality though, then you can stick with `ROLE_ANONYMOUS`, which will be processed by Spring Security's standard `RoleVoter`. [[anonymous-auth-mvc-controller]] -=== Getting Anonymous Authentications with Spring MVC +== Getting Anonymous Authentications with Spring MVC https://docs.spring.io/spring-framework/docs/current/reference/html/web.html#mvc-ann-arguments[Spring MVC resolves parameters of type `Principal`] using its own argument resolver. diff --git a/docs/modules/ROOT/pages/servlet/authentication/cas.adoc b/docs/modules/ROOT/pages/servlet/authentication/cas.adoc index 29c245eb95..5287dd6d92 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/cas.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/cas.adoc @@ -1,8 +1,8 @@ [[servlet-cas]] -== CAS Authentication += CAS Authentication [[cas-overview]] -=== Overview +== Overview JA-SIG produces an enterprise-wide single sign on system known as CAS. Unlike other initiatives, JA-SIG's Central Authentication Service is open source, widely used, simple to understand, platform independent, and supports proxy capabilities. Spring Security fully supports CAS, and provides an easy migration path from single-application deployments of Spring Security through to multiple-application deployments secured by an enterprise-wide CAS server. @@ -11,7 +11,7 @@ You can learn more about CAS at https://www.apereo.org. You will also need to visit this site to download the CAS Server files. [[cas-how-it-works]] -=== How CAS Works +== How CAS Works Whilst the CAS web site contains documents that detail the architecture of CAS, we present the general overview again here within the context of Spring Security. Spring Security 3.x supports CAS 3. At the time of writing, the CAS server was at version 3.4. @@ -34,7 +34,7 @@ Authenticating a proxy ticket differs because the list of proxies must be valida [[cas-sequence]] -==== Spring Security and CAS Interaction Sequence +=== Spring Security and CAS Interaction Sequence The basic interaction between a web browser, CAS server and a Spring Security-secured service is as follows: * The web user is browsing the service's public pages. @@ -87,7 +87,7 @@ It's good that you're still here! Let's now look at how this is configured [[cas-client]] -=== Configuration of CAS Client +== Configuration of CAS Client The web application side of CAS is made easy due to Spring Security. It is assumed you already know the basics of using Spring Security, so these are not covered again below. We'll assume a namespace based configuration is being used and add in the CAS beans as required. @@ -96,7 +96,7 @@ A full CAS sample application can be found in the Spring Security <> contains a working example in the `ProxyTicketSampleServlet`. Example code can be found below: @@ -379,7 +379,7 @@ protected fun doGet(request: HttpServletRequest, response: HttpServletResponse?) ==== [[cas-pt]] -==== Proxy Ticket Authentication +=== Proxy Ticket Authentication The `CasAuthenticationProvider` distinguishes between stateful and stateless clients. A stateful client is considered any that submits to the `filterProcessUrl` of the `CasAuthenticationFilter`. A stateless client is any that presents an authentication request to `CasAuthenticationFilter` on a URL other than the `filterProcessUrl`. diff --git a/docs/modules/ROOT/pages/servlet/authentication/events.adoc b/docs/modules/ROOT/pages/servlet/authentication/events.adoc index 6bb9896718..c016d37574 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/events.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/events.adoc @@ -1,5 +1,5 @@ [[servlet-events]] -== Authentication Events += Authentication Events For each authentication that succeeds or fails, a `AuthenticationSuccessEvent` or `AbstractAuthenticationFailureEvent` is fired, respectively. @@ -68,7 +68,7 @@ class AuthenticationEvents { While similar to `AuthenticationSuccessHandler` and `AuthenticationFailureHandler`, these are nice in that they can be used independently from the servlet API. -=== Adding Exception Mappings +== Adding Exception Mappings `DefaultAuthenticationEventPublisher` by default will publish an `AbstractAuthenticationFailureEvent` for the following events: @@ -121,7 +121,7 @@ fun authenticationEventPublisher ---- ==== -=== Default Event +== Default Event And, you can supply a catch-all event to fire in the case of any `AuthenticationException`: diff --git a/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc b/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc index 216435bf43..76671ba579 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc @@ -1,21 +1,21 @@ [[servlet-jaas]] -== Java Authentication and Authorization Service (JAAS) Provider += Java Authentication and Authorization Service (JAAS) Provider -=== Overview +== Overview Spring Security provides a package able to delegate authentication requests to the Java Authentication and Authorization Service (JAAS). This package is discussed in detail below. [[jaas-abstractjaasauthenticationprovider]] -=== AbstractJaasAuthenticationProvider +== AbstractJaasAuthenticationProvider The `AbstractJaasAuthenticationProvider` is the basis for the provided JAAS `AuthenticationProvider` implementations. Subclasses must implement a method that creates the `LoginContext`. The `AbstractJaasAuthenticationProvider` has a number of dependencies that can be injected into it that are discussed below. [[jaas-callbackhandler]] -==== JAAS CallbackHandler +=== JAAS CallbackHandler Most JAAS ``LoginModule``s require a callback of some sort. These callbacks are usually used to obtain the username and password from the user. @@ -33,7 +33,7 @@ If the `LoginModule` requests a callback against the ``InternalCallbackHandler`` [[jaas-authoritygranter]] -==== JAAS AuthorityGranter +=== JAAS AuthorityGranter JAAS works with principals. Even "roles" are represented as principals in JAAS. Spring Security, on the other hand, works with `Authentication` objects. @@ -50,14 +50,14 @@ However, there is a `TestAuthorityGranter` in the unit tests that demonstrates a [[jaas-defaultjaasauthenticationprovider]] -=== DefaultJaasAuthenticationProvider +== DefaultJaasAuthenticationProvider The `DefaultJaasAuthenticationProvider` allows a JAAS `Configuration` object to be injected into it as a dependency. It then creates a `LoginContext` using the injected JAAS `Configuration`. This means that `DefaultJaasAuthenticationProvider` is not bound any particular implementation of `Configuration` as `JaasAuthenticationProvider` is. [[jaas-inmemoryconfiguration]] -==== InMemoryConfiguration +=== InMemoryConfiguration In order to make it easy to inject a `Configuration` into `DefaultJaasAuthenticationProvider`, a default in-memory implementation named `InMemoryConfiguration` is provided. The implementation constructor accepts a `Map` where each key represents a login configuration name and the value represents an `Array` of ``AppConfigurationEntry``s. `InMemoryConfiguration` also supports a default `Array` of `AppConfigurationEntry` objects that will be used if no mapping is found within the provided `Map`. @@ -65,7 +65,7 @@ For details, refer to the class level javadoc of `InMemoryConfiguration`. [[jaas-djap-config]] -==== DefaultJaasAuthenticationProvider Example Configuration +=== DefaultJaasAuthenticationProvider Example Configuration While the Spring configuration for `InMemoryConfiguration` can be more verbose than the standard JAAS configuration files, using it in conjunction with `DefaultJaasAuthenticationProvider` is more flexible than `JaasAuthenticationProvider` since it not dependant on the default `Configuration` implementation. An example configuration of `DefaultJaasAuthenticationProvider` using `InMemoryConfiguration` is provided below. @@ -116,7 +116,7 @@ class="org.springframework.security.authentication.jaas.DefaultJaasAuthenticatio [[jaas-jaasauthenticationprovider]] -=== JaasAuthenticationProvider +== JaasAuthenticationProvider The `JaasAuthenticationProvider` assumes the default `Configuration` is an instance of https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/login/ConfigFile.html[ ConfigFile]. This assumption is made in order to attempt to update the `Configuration`. The `JaasAuthenticationProvider` then uses the default `Configuration` to create the `LoginContext`. @@ -157,7 +157,7 @@ class="org.springframework.security.authentication.jaas.JaasAuthenticationProvid ---- [[jaas-apiprovision]] -=== Running as a Subject +== Running as a Subject If configured, the `JaasApiIntegrationFilter` will attempt to run as the `Subject` on the `JaasAuthenticationToken`. This means that the `Subject` can be accessed using: diff --git a/docs/modules/ROOT/pages/servlet/authentication/logout.adoc b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc index 7ebb287ac2..9ad2110072 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/logout.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc @@ -1,8 +1,8 @@ [[jc-logout]] -== Handling Logouts += Handling Logouts [[logout-java-configuration]] -=== Logout Java/Kotlin Configuration +== Logout Java/Kotlin Configuration When using the `{security-api-url}org/springframework/security/config/annotation/web/configuration/WebSecurityConfigurerAdapter.html[WebSecurityConfigurerAdapter]`, logout capabilities are automatically applied. The default is that accessing the URL `/logout` will log the user out by: @@ -86,13 +86,13 @@ For many common scenarios, these handlers are applied under the covers when using the fluent API. [[ns-logout]] -=== Logout XML Configuration +== Logout XML Configuration The `logout` element adds support for logging out by navigating to a particular URL. The default logout URL is `/logout`, but you can set it to something else using the `logout-url` attribute. More information on other available attributes may be found in the namespace appendix. [[jc-logout-handler]] -=== LogoutHandler +== LogoutHandler Generally, `{security-api-url}org/springframework/security/web/authentication/logout/LogoutHandler.html[LogoutHandler]` implementations indicate classes that are able to participate in logout handling. @@ -115,7 +115,7 @@ E.g. `deleteCookies()` allows specifying the names of one or more cookies to be This is a shortcut compared to adding a `CookieClearingLogoutHandler`. [[jc-logout-success-handler]] -=== LogoutSuccessHandler +== LogoutSuccessHandler The `LogoutSuccessHandler` is called after a successful logout by the `LogoutFilter`, to handle e.g. redirection or forwarding to the appropriate destination. @@ -137,7 +137,7 @@ Instead of redirecting to a URL upon the successful logout, this `LogoutSuccessH If not configured a status code 200 will be returned by default. [[jc-logout-references]] -=== Further Logout-Related References +== Further Logout-Related References - <> - <> diff --git a/docs/modules/ROOT/pages/servlet/authentication/openid.adoc b/docs/modules/ROOT/pages/servlet/authentication/openid.adoc index 01362127ff..9ecc0b8246 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/openid.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/openid.adoc @@ -1,5 +1,5 @@ [[servlet-openid]] -== OpenID Support += OpenID Support [NOTE] The OpenID 1.0 and 2.0 protocols have been deprecated and users are encouraged to migrate to OpenID Connect, which is supported by spring-security-oauth2. @@ -27,7 +27,7 @@ Note that we have omitted the password attribute from the above user configurati A random password will be generated internally, preventing you from accidentally using this user data as an authentication source elsewhere in your configuration. -=== Attribute Exchange +== Attribute Exchange Support for OpenID https://openid.net/specs/openid-attribute-exchange-1_0.html[attribute exchange]. As an example, the following configuration would attempt to retrieve the email and full name from the OpenID provider, for use by the application: diff --git a/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc b/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc index f23b57a203..67da7fc4b9 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc @@ -1,5 +1,5 @@ [[servlet-preauth]] -== Pre-Authentication Scenarios += Pre-Authentication Scenarios There are situations where you want to use Spring Security for authorization, but the user has already been reliably authenticated by some external system prior to accessing the application. We refer to these situations as "pre-authenticated" scenarios. Examples include X.509, Siteminder and authentication by the Java EE container in which the application is running. @@ -16,7 +16,7 @@ If relying on container authentication, the user will be identified by calling t In some cases, the external mechanism may supply role/authority information for the user but in others the authorities must be obtained from a separate source, such as a `UserDetailsService`. -=== Pre-Authentication Framework Classes +== Pre-Authentication Framework Classes Because most pre-authentication mechanisms follow the same pattern, Spring Security has a set of classes which provide an internal framework for implementing pre-authenticated authentication providers. This removes duplication and allows new implementations to be added in a structured fashion, without having to write everything from scratch. You don't need to know about these classes if you want to use something like <>, as it already has a namespace configuration option which is simpler to use and get started with. @@ -25,7 +25,7 @@ You will find classes under the `org.springframework.security.web.authentication We just provide an outline here so you should consult the Javadoc and source where appropriate. -==== AbstractPreAuthenticatedProcessingFilter +=== AbstractPreAuthenticatedProcessingFilter This class will check the current contents of the security context and, if empty, it will attempt to extract user information from the HTTP request and submit it to the `AuthenticationManager`. Subclasses override the following methods to obtain this information: @@ -59,7 +59,7 @@ We'll look at a concrete example next. [[j2ee-preauth-details]] -===== J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource +==== J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource If the filter is configured with an `authenticationDetailsSource` which is an instance of this class, the authority information is obtained by calling the `isUserInRole(String role)` method for each of a pre-determined set of "mappable roles". The class gets these from a configured `MappableAttributesRetriever`. Possible implementations include hard-coding a list in the application context and reading the role information from the `` information in a `web.xml` file. @@ -69,7 +69,7 @@ There is an additional stage where the roles (or attributes) are mapped to Sprin The default will just add the usual `ROLE_` prefix to the names, but it gives you full control over the behaviour. -==== PreAuthenticatedAuthenticationProvider +=== PreAuthenticatedAuthenticationProvider The pre-authenticated provider has little more to do than load the `UserDetails` object for the user. It does this by delegating to an `AuthenticationUserDetailsService`. The latter is similar to the standard `UserDetailsService` but takes an `Authentication` object rather than just user name: @@ -85,19 +85,19 @@ This interface may have also other uses but with pre-authentication it allows ac The `PreAuthenticatedGrantedAuthoritiesUserDetailsService` class does this. Alternatively, it may delegate to a standard `UserDetailsService` via the `UserDetailsByNameServiceWrapper` implementation. -==== Http403ForbiddenEntryPoint +=== Http403ForbiddenEntryPoint The <> is responsible for kick-starting the authentication process for an unauthenticated user (when they try to access a protected resource), but in the pre-authenticated case this doesn't apply. You would only configure the `ExceptionTranslationFilter` with an instance of this class if you aren't using pre-authentication in combination with other authentication mechanisms. It will be called if the user is rejected by the `AbstractPreAuthenticatedProcessingFilter` resulting in a null authentication. It always returns a `403`-forbidden response code if called. -=== Concrete Implementations +== Concrete Implementations X.509 authentication is covered in its <>. Here we'll look at some classes which provide support for other pre-authenticated scenarios. -==== Request-Header Authentication (Siteminder) +=== Request-Header Authentication (Siteminder) An external authentication system may supply information to the application by setting specific headers on the HTTP request. A well-known example of this is Siteminder, which passes the username in a header called `SM_USER`. This mechanism is supported by the class `RequestHeaderAuthenticationFilter` which simply extracts the username from the header. @@ -110,7 +110,7 @@ Note that when using a system like this, the framework performs no authenticatio If an attacker is able to forge the headers in their original request without this being detected then they could potentially choose any username they wished. ==== -===== Siteminder Example Configuration +==== Siteminder Example Configuration A typical configuration using this filter would look like this: [source,xml] @@ -143,7 +143,7 @@ We've assumed here that the <> is being used for c It's also assumed that you have added a `UserDetailsService` (called "userDetailsService") to your configuration to load the user's roles. -==== Java EE Container Authentication +=== Java EE Container Authentication The class `J2eePreAuthenticatedProcessingFilter` will extract the username from the `userPrincipal` property of the `HttpServletRequest`. Use of this filter would usually be combined with the use of Java EE roles as described above in <>. diff --git a/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc b/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc index b2375d62cb..fd65a3ce62 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc @@ -1,9 +1,9 @@ [[servlet-rememberme]] -== Remember-Me Authentication += Remember-Me Authentication [[remember-me-overview]] -=== Overview +== Overview Remember-me or persistent-login authentication refers to web sites being able to remember the identity of a principal between sessions. This is typically accomplished by sending a cookie to the browser, with the cookie being detected during future sessions and causing automated login to take place. Spring Security provides the necessary hooks for these operations to take place, and has two concrete remember-me implementations. @@ -14,7 +14,7 @@ If you are using an authentication provider which doesn't use a `UserDetailsServ [[remember-me-hash-token]] -=== Simple Hash-Based Token Approach +== Simple Hash-Based Token Approach This approach uses hashing to achieve a useful remember-me strategy. In essence a cookie is sent to the browser upon successful interactive authentication, with the cookie being composed as follows: @@ -50,7 +50,7 @@ The `UserDetailsService` will normally be selected automatically. If you have more than one in your application context, you need to specify which one should be used with the `user-service-ref` attribute, where the value is the name of your `UserDetailsService` bean. [[remember-me-persistent-token]] -=== Persistent Token Approach +== Persistent Token Approach This approach is based on the article https://web.archive.org/web/20180819014446/http://jaspan.com/improved_persistent_login_cookie_best_practice[http://jaspan.com/improved_persistent_login_cookie_best_practice] with some minor modifications footnote:[Essentially, the username is not included in the cookie, to prevent exposing a valid login name unecessarily. There is a discussion on this in the comments section of this article.]. To use the this approach with namespace configuration, you would supply a datasource reference: @@ -74,7 +74,7 @@ create table persistent_logins (username varchar(64) not null, ---- [[remember-me-impls]] -=== Remember-Me Interfaces and Implementations +== Remember-Me Interfaces and Implementations Remember-me is used with `UsernamePasswordAuthenticationFilter`, and is implemented via hooks in the `AbstractAuthenticationProcessingFilter` superclass. It is also used within `BasicAuthenticationFilter`. The hooks will invoke a concrete `RememberMeServices` at the appropriate times. @@ -97,7 +97,7 @@ This design allows any number of remember-me implementation strategies. We've seen above that Spring Security provides two implementations. We'll look at these in turn. -==== TokenBasedRememberMeServices +=== TokenBasedRememberMeServices This implementation supports the simpler approach described in <>. `TokenBasedRememberMeServices` generates a `RememberMeAuthenticationToken`, which is processed by `RememberMeAuthenticationProvider`. A `key` is shared between this authentication provider and the `TokenBasedRememberMeServices`. @@ -130,7 +130,7 @@ The beans required in an application context to enable remember-me services are Don't forget to add your `RememberMeServices` implementation to your `UsernamePasswordAuthenticationFilter.setRememberMeServices()` property, include the `RememberMeAuthenticationProvider` in your `AuthenticationManager.setProviders()` list, and add `RememberMeAuthenticationFilter` into your `FilterChainProxy` (typically immediately after your `UsernamePasswordAuthenticationFilter`). -==== PersistentTokenBasedRememberMeServices +=== PersistentTokenBasedRememberMeServices This class can be used in the same way as `TokenBasedRememberMeServices`, but it additionally needs to be configured with a `PersistentTokenRepository` to store the tokens. There are two standard implementations. diff --git a/docs/modules/ROOT/pages/servlet/authentication/runas.adoc b/docs/modules/ROOT/pages/servlet/authentication/runas.adoc index 0b439ad369..258e5a033c 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/runas.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/runas.adoc @@ -1,8 +1,8 @@ [[runas]] -== Run-As Authentication Replacement += Run-As Authentication Replacement [[runas-overview]] -=== Overview +== Overview The `AbstractSecurityInterceptor` is able to temporarily replace the `Authentication` object in the `SecurityContext` and `SecurityContextHolder` during the secure object callback phase. This only occurs if the original `Authentication` object was successfully processed by the `AuthenticationManager` and `AccessDecisionManager`. The `RunAsManager` will indicate the replacement `Authentication` object, if any, that should be used during the `SecurityInterceptorCallback`. @@ -12,7 +12,7 @@ It will also be able to perform any internal security checks for specific `Grant Because Spring Security provides a number of helper classes that automatically configure remoting protocols based on the contents of the `SecurityContextHolder`, these run-as replacements are particularly useful when calling remote web services. [[runas-config]] -=== Configuration +== Configuration A `RunAsManager` interface is provided by Spring Security: [source,java] diff --git a/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc b/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc index bee0394d4b..6024d34a1b 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc @@ -1,9 +1,9 @@ [[session-mgmt]] -== Session Management += Session Management HTTP session related functionality is handled by a combination of the `SessionManagementFilter` and the `SessionAuthenticationStrategy` interface, which the filter delegates to. Typical usage includes session-fixation protection attack prevention, detection of session timeouts and restrictions on how many sessions an authenticated user may have open concurrently. -=== Detecting Timeouts +== Detecting Timeouts You can configure Spring Security to detect the submission of an invalid session ID and redirect the user to an appropriate URL. This is achieved through the `session-management` element: @@ -74,7 +74,7 @@ Header always set Set-Cookie "JSESSIONID=;Path=/tutorial;Expires=Thu, 01 Jan 197 [[ns-concurrent-sessions]] -=== Concurrent Session Control +== Concurrent Session Control If you wish to place constraints on a single user's ability to log in to your application, Spring Security supports this out of the box with the following simple additions. First, you need to add the following listener to your configuration to keep Spring Security updated about session lifecycle events: @@ -165,7 +165,7 @@ If you are using a customized authentication filter for form-based login, then y More details can be found in the <>. [[ns-session-fixation]] -=== Session Fixation Attack Protection +== Session Fixation Attack Protection https://en.wikipedia.org/wiki/Session_fixation[Session fixation] attacks are a potential risk where it is possible for a malicious attacker to create a session by accessing a site, then persuade another user to log in with the same session (by sending them a link containing the session identifier as a parameter, for example). Spring Security protects against this automatically by creating a new session or otherwise changing the session ID when a user logs in. If you don't require this protection, or it conflicts with some other requirement, you can control the behavior using the `session-fixation-protection` attribute on ``, which has four options @@ -189,7 +189,7 @@ When session fixation protection occurs, it results in a `SessionFixationProtect If you use `changeSessionId`, this protection will __also__ result in any ``javax.servlet.http.HttpSessionIdListener``s being notified, so use caution if your code listens for both events. See the <> chapter for additional information. -=== SessionManagementFilter +== SessionManagementFilter The `SessionManagementFilter` checks the contents of the `SecurityContextRepository` against the current contents of the `SecurityContextHolder` to determine whether a user has been authenticated during the current request, typically by a non-interactive authentication mechanism, such as pre-authentication or remember-me footnote:[ Authentication by mechanisms which perform a redirect after authenticating (such as form-login) will not be detected by `SessionManagementFilter`, as the filter will not be invoked during the authenticating request. Session-management functionality has to be handled separately in these cases. @@ -203,7 +203,7 @@ The most common behaviour is just to redirect to a fixed URL and this is encapsu The latter is also used when configuring an invalid session URL through the namespace, <>. -=== SessionAuthenticationStrategy +== SessionAuthenticationStrategy `SessionAuthenticationStrategy` is used by both `SessionManagementFilter` and `AbstractAuthenticationProcessingFilter`, so if you are using a customized form-login class, for example, you will need to inject it into both of these. In this case, a typical configuration, combining the namespace and custom beans might look like this: @@ -230,7 +230,7 @@ Note that the use of the default, `SessionFixationProtectionStrategy` may cause See the Javadoc for this class for more information. [[concurrent-sessions]] -=== Concurrency Control +== Concurrency Control Spring Security is able to prevent a principal from concurrently authenticating to the same application more than a specified number of times. Many ISVs take advantage of this to enforce licensing, whilst network administrators like this feature because it helps prevent people from sharing login names. You can, for example, stop user "Batman" from logging onto the web application from two different sessions. @@ -327,7 +327,7 @@ Without it, a user will never be able to log back in again once they have exceed [[list-authenticated-principals]] -==== Querying the SessionRegistry for currently authenticated users and their sessions +=== Querying the SessionRegistry for currently authenticated users and their sessions Setting up concurrency-control, either through the namespace or using plain beans has the useful side effect of providing you with a reference to the `SessionRegistry` which you can use directly within your application, so even if you don't want to restrict the number of sessions a user may have, it may be worth setting up the infrastructure anyway. You can set the `maximumSession` property to -1 to allow unlimited sessions. If you're using the namespace, you can set an alias for the internally-created `SessionRegistry` using the `session-registry-alias` attribute, providing a reference which you can inject into your own beans. diff --git a/docs/modules/ROOT/pages/servlet/authentication/x509.adoc b/docs/modules/ROOT/pages/servlet/authentication/x509.adoc index 138721e127..5dc29b08d1 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/x509.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/x509.adoc @@ -1,9 +1,9 @@ [[servlet-x509]] -== X.509 Authentication += X.509 Authentication [[x509-overview]] -=== Overview +== Overview The most common use of X.509 certificate authentication is in verifying the identity of a server when using SSL, most commonly when using HTTPS from a browser. The browser will automatically check that the certificate presented by a server has been issued (ie digitally signed) by one of a list of trusted certificate authorities which it maintains. @@ -19,7 +19,7 @@ For example, if you're using Tomcat then read the instructions here https://tomc It's important that you get this working before trying it out with Spring Security -=== Adding X.509 Authentication to Your Web Application +== Adding X.509 Authentication to Your Web Application Enabling X.509 client authentication is very straightforward. Just add the `` element to your http security namespace configuration. @@ -51,7 +51,7 @@ If no certificate is found, or no corresponding user could be found then the sec This means that you can easily use X.509 authentication with other options such as a form-based login. [[x509-ssl-config]] -=== Setting up SSL in Tomcat +== Setting up SSL in Tomcat There are some pre-generated certificates in the {gh-samples-url}/servlet/java-configuration/authentication/x509/server[Spring Security Samples repository]. You can use these to enable SSL for testing if you don't want to generate your own. The file `server.jks` contains the server certificate, private key and the issuing certificate authority certificate. diff --git a/docs/modules/ROOT/pages/servlet/authorization/acls.adoc b/docs/modules/ROOT/pages/servlet/authorization/acls.adoc index 32ef05e387..1735e9000b 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/acls.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/acls.adoc @@ -1,8 +1,8 @@ [[domain-acls]] -== Domain Object Security (ACLs) += Domain Object Security (ACLs) [[domain-acls-overview]] -=== Overview +== Overview Complex applications often will find the need to define access permissions not simply at a web request or method invocation level. Instead, security decisions need to comprise both who (`Authentication`), where (`MethodInvocation`) and what (`SomeDomainObject`). In other words, authorization decisions also need to consider the actual domain object instance subject of a method invocation. @@ -37,7 +37,7 @@ Fortunately, there is another alternative, which we'll talk about below. [[domain-acls-key-concepts]] -=== Key Concepts +== Key Concepts Spring Security's ACL services are shipped in the `spring-security-acl-xxx.jar`. You will need to add this JAR to your classpath to use Spring Security's domain object instance security capabilities. @@ -130,7 +130,7 @@ We suggest taking a look over these for examples. [[domain-acls-getting-started]] -=== Getting Started +== Getting Started To get starting using Spring Security's ACL capability, you will need to store your ACL information somewhere. This necessitates the instantiation of a `DataSource` using Spring. The `DataSource` is then injected into a `JdbcMutableAclService` and `BasicLookupStrategy` instance. diff --git a/docs/modules/ROOT/pages/servlet/authorization/expression-based.adoc b/docs/modules/ROOT/pages/servlet/authorization/expression-based.adoc index 1070783c92..f5b916d636 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/expression-based.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/expression-based.adoc @@ -1,18 +1,18 @@ [[el-access]] -== Expression-Based Access Control += Expression-Based Access Control Spring Security 3.0 introduced the ability to use Spring EL expressions as an authorization mechanism in addition to the simple use of configuration attributes and access-decision voters which have been seen before. Expression-based access control is built on the same architecture but allows complicated Boolean logic to be encapsulated in a single expression. -=== Overview +== Overview Spring Security uses Spring EL for expression support and you should look at how that works if you are interested in understanding the topic in more depth. Expressions are evaluated with a "root object" as part of the evaluation context. Spring Security uses specific classes for web and method security as the root object, in order to provide built-in expressions and access to values such as the current principal. [[el-common-built-in]] -==== Common Built-In Expressions +=== Common Built-In Expressions The base class for expression root objects is `SecurityExpressionRoot`. This provides some common expressions which are available in both web and method security. @@ -83,7 +83,7 @@ For example, `hasPermission(1, 'com.example.domain.Message', 'read')` [[el-access-web]] -=== Web Security Expressions +== Web Security Expressions To use expressions to secure individual URLs, you would first need to set the `use-expressions` attribute in the `` element to `true`. Spring Security will then expect the `access` attributes of the `` elements to contain Spring EL expressions. The expressions should evaluate to a Boolean, defining whether access should be allowed or not. @@ -109,7 +109,7 @@ If expressions are being used, a `WebExpressionVoter` will be added to the `Acce So if you aren't using the namespace and want to use expressions, you will have to add one of these to your configuration. [[el-access-web-beans]] -==== Referring to Beans in Web Security Expressions +=== Referring to Beans in Web Security Expressions If you wish to extend the expressions that are available, you can easily refer to any Spring Bean you expose. For example, assuming you have a Bean with the name of `webSecurity` that contains the following method signature: @@ -172,7 +172,7 @@ http { ==== [[el-access-web-path-variables]] -==== Path Variables in Web Security Expressions +=== Path Variables in Web Security Expressions At times it is nice to be able to refer to path variables within a URL. For example, consider a RESTful application that looks up a user by id from the URL path in the format `+/user/{userId}+`. @@ -240,13 +240,13 @@ http { In this configuration URLs that match would pass in the path variable (and convert it) into checkUserId method. For example, if the URL were `/user/123/resource`, then the id passed in would be `123`. -=== Method Security Expressions +== Method Security Expressions Method security is a bit more complicated than a simple allow or deny rule. Spring Security 3.0 introduced some new annotations in order to allow comprehensive support for the use of expressions. [[el-pre-post-annotations]] -==== @Pre and @Post Annotations +=== @Pre and @Post Annotations There are four annotations which support expression attributes to allow pre and post-invocation authorization checks and also to support filtering of submitted collection arguments or return values. They are `@PreAuthorize`, `@PreFilter`, `@PostAuthorize` and `@PostFilter`. Their use is enabled through the `global-method-security` namespace element: @@ -256,7 +256,7 @@ Their use is enabled through the `global-method-security` namespace element: ---- -===== Access Control using @PreAuthorize and @PostAuthorize +==== Access Control using @PreAuthorize and @PostAuthorize The most obviously useful annotation is `@PreAuthorize` which decides whether a method can actually be invoked or not. For example (from the {gh-samples-url}/servlet/xml/java/contacts[Contacts] sample application) @@ -412,7 +412,7 @@ This can be achieved using the `@PostAuthorize` annotation. To access the return value from a method, use the built-in name `returnObject` in the expression. -- -===== Filtering using @PreFilter and @PostFilter +==== Filtering using @PreFilter and @PostFilter Spring Security supports filtering of collections, arrays, maps and streams using expressions. This is most commonly performed on the return value of a method. For example: @@ -447,13 +447,13 @@ If you are filtering large collections and removing many of the entries then thi [[el-method-built-in]] -==== Built-In Expressions +=== Built-In Expressions There are some built-in expressions which are specific to method security, which we have already seen in use above. The `filterTarget` and `returnValue` values are simple enough, but the use of the `hasPermission()` expression warrants a closer look. [[el-permission-evaluator]] -===== The PermissionEvaluator interface +==== The PermissionEvaluator interface `hasPermission()` expressions are delegated to an instance of `PermissionEvaluator`. It is intended to bridge between the expression system and Spring Security's ACL system, allowing you to specify authorization constraints on domain objects, based on abstract permissions. It has no explicit dependencies on the ACL module, so you could swap that out for an alternative implementation if required. @@ -494,7 +494,7 @@ Where `myPermissionEvaluator` is the bean which implements `PermissionEvaluator` Usually this will be the implementation from the ACL module which is called `AclPermissionEvaluator`. See the {gh-samples-url}/servlet/xml/java/contacts[Contacts] sample application configuration for more details. -===== Method Security Meta Annotations +==== Method Security Meta Annotations You can make use of meta annotations for method security to make your code more readable. This is especially convenient if you find that you are repeating the same complex expression throughout your code base. diff --git a/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc index b960be9e22..ce49cdd45e 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc @@ -1,12 +1,12 @@ [[jc-method]] -== Method Security += Method Security From version 2.0 onwards Spring Security has improved support substantially for adding security to your service layer methods. It provides support for JSR-250 annotation security as well as the framework's original `@Secured` annotation. From 3.0 you can also make use of new <>. You can apply security to a single bean, using the `intercept-methods` element to decorate the bean declaration, or you can secure multiple beans across the entire service layer using the AspectJ style pointcuts. -=== EnableMethodSecurity +== EnableMethodSecurity In Spring Security 5.6, we can enable annotation-based security using the `@EnableMethodSecurity` annotation on any `@Configuration` instance. @@ -149,7 +149,7 @@ class MethodSecurityConfig { ---- ==== -==== Customizing Authorization +=== Customizing Authorization Spring Security's `@PreAuthorize`, `@PostAuthorize`, `@PreFilter`, and `@PostFilter` ship with rich expression-based support. @@ -245,7 +245,7 @@ We expose `GrantedAuthorityDefaults` using a `static` method to ensure that Spri ==== [[jc-method-security-custom-authorization-manager]] -==== Custom Authorization Managers +=== Custom Authorization Managers Method authorization is a combination of before- and after-method authorization. @@ -598,7 +598,7 @@ class MethodSecurityConfig { and it will be invoked after the `@PostAuthorize` interceptor. [[jc-enable-global-method-security]] -=== EnableGlobalMethodSecurity +== EnableGlobalMethodSecurity We can enable annotation-based security using the `@EnableGlobalMethodSecurity` annotation on any `@Configuration` instance. For example, the following would enable Spring Security's `@Secured` annotation. @@ -740,7 +740,7 @@ interface BankService { ---- ==== -=== GlobalMethodSecurityConfiguration +== GlobalMethodSecurityConfiguration Sometimes you may need to perform operations that are more complicated than are possible with the `@EnableGlobalMethodSecurity` annotation allow. For these instances, you can extend the `GlobalMethodSecurityConfiguration` ensuring that the `@EnableGlobalMethodSecurity` annotation is present on your subclass. @@ -776,7 +776,7 @@ open class MethodSecurityConfig : GlobalMethodSecurityConfiguration() { For additional information about methods that can be overridden, refer to the `GlobalMethodSecurityConfiguration` Javadoc. [[ns-global-method]] -=== The Element +== The Element This element is used to enable annotation-based security in your application (by setting the appropriate attributes on the element), and also to group together security pointcut declarations which will be applied across your entire application context. You should only declare one `` element. The following declaration would enable support for Spring Security's `@Secured`: @@ -889,7 +889,7 @@ If two annotations are found which apply to a particular method, then only one o ==== [[ns-protect-pointcut]] -=== Adding Security Pointcuts using protect-pointcut +== Adding Security Pointcuts using protect-pointcut The use of `protect-pointcut` is particularly powerful, as it allows you to apply security to many beans with only a simple declaration. Consider the following example: diff --git a/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc b/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc index 3182ac322f..5c24678b16 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc @@ -1,9 +1,9 @@ [[secure-object-impls]] -== Secure Object Implementations += Secure Object Implementations [[aop-alliance]] -=== AOP Alliance (MethodInvocation) Security Interceptor +== AOP Alliance (MethodInvocation) Security Interceptor Prior to Spring Security 2.0, securing ``MethodInvocation``s needed quite a lot of boiler plate configuration. Now the recommended approach for method security is to use <>. This way the method security infrastructure beans are configured automatically for you so you don't really need to know about the implementation classes. @@ -15,7 +15,7 @@ The interceptor uses a `MethodSecurityMetadataSource` instance to obtain the con `MapBasedMethodSecurityMetadataSource` is used to store configuration attributes keyed by method names (which can be wildcarded) and will be used internally when the attributes are defined in the application context using the `` or `` elements. Other implementations will be used to handle annotation-based configuration. -==== Explicit MethodSecurityInterceptor Configuration +=== Explicit MethodSecurityInterceptor Configuration You can of course configure a `MethodSecurityInterceptor` directly in your application context for use with one of Spring AOP's proxying mechanisms: [source,xml] @@ -36,7 +36,7 @@ You can of course configure a `MethodSecurityInterceptor` directly in your appli ---- [[aspectj]] -=== AspectJ (JoinPoint) Security Interceptor +== AspectJ (JoinPoint) Security Interceptor The AspectJ security interceptor is very similar to the AOP Alliance security interceptor discussed in the previous section. Indeed we will only discuss the differences in this section. diff --git a/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc b/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc index a2ac3fe2a2..202b51ab09 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc @@ -1,5 +1,5 @@ [[concurrency]] -== Concurrency Support += Concurrency Support In most environments, Security is stored on a per `Thread` basis. This means that when work is done on a new `Thread`, the `SecurityContext` is lost. @@ -7,7 +7,7 @@ Spring Security provides some infrastructure to help make this much easier for u Spring Security provides low level abstractions for working with Spring Security in multi-threaded environments. In fact, this is what Spring Security builds on to integration with <> and <>. -=== DelegatingSecurityContextRunnable +== DelegatingSecurityContextRunnable One of the most fundamental building blocks within Spring Security's concurrency support is the `DelegatingSecurityContextRunnable`. It wraps a delegate `Runnable` in order to initialize the `SecurityContextHolder` with a specified `SecurityContext` for the delegate. @@ -122,7 +122,7 @@ 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. -=== DelegatingSecurityContextExecutor +== DelegatingSecurityContextExecutor In the previous section we found that it was easy to use the `DelegatingSecurityContextRunnable`, but it was not ideal since we had to be aware of Spring Security in order to use it. Let's take a look at how `DelegatingSecurityContextExecutor` can shield our code from any knowledge that we are using Spring Security. @@ -244,7 +244,7 @@ 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. -=== Spring Security Concurrency Classes +== Spring Security Concurrency Classes Refer to the Javadoc for additional integrations with both the Java concurrent APIs and the Spring Task abstractions. They are quite self-explanatory once you understand the previous code. diff --git a/docs/modules/ROOT/pages/servlet/integrations/cors.adoc b/docs/modules/ROOT/pages/servlet/integrations/cors.adoc index cf9eae9629..aa5cb3ff17 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/cors.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/cors.adoc @@ -1,5 +1,5 @@ [[cors]] -== CORS += CORS Spring Framework provides https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-cors[first class support for CORS]. CORS must be processed before Spring Security because the pre-flight request will not contain any cookies (i.e. the `JSESSIONID`). diff --git a/docs/modules/ROOT/pages/servlet/integrations/data.adoc b/docs/modules/ROOT/pages/servlet/integrations/data.adoc index 2e618b11f5..9212daeda3 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/data.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/data.adoc @@ -1,11 +1,11 @@ [[data]] -== Spring Data Integration += Spring Data Integration Spring Security provides Spring Data integration that allows referring to the current user within your queries. It is not only useful but necessary to include the user in the queries to support paged results since filtering the results afterwards would not scale. [[data-configuration]] -=== Spring Data & Spring Security Configuration +== Spring Data & Spring Security Configuration 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: @@ -38,7 +38,7 @@ In XML Configuration, this would look like: ---- [[data-query]] -=== Security Expressions within @Query +== Security Expressions within @Query Now Spring Security can be used within your queries. For example: diff --git a/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc b/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc index b78a880998..1f26756b08 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc @@ -1,5 +1,5 @@ [[jackson]] -== Jackson Support += Jackson Support Spring Security provides Jackson support for persisting Spring Security related classes. This can improve the performance of serializing Spring Security related classes when working with distributed sessions (i.e. session replication, Spring Session, etc). diff --git a/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc b/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc index 3f31683258..28a02e34ac 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc @@ -1,9 +1,9 @@ [[taglibs]] -== JSP Tag Libraries += JSP Tag Libraries Spring Security has its own taglib which provides basic support for accessing security information and applying security constraints in JSPs. -=== Declaring the Taglib +== Declaring the Taglib To use any of the tags, you must have the security taglib declared in your JSP: [source,xml] @@ -12,7 +12,7 @@ To use any of the tags, you must have the security taglib declared in your JSP: ---- [[taglibs-authorize]] -=== The authorize Tag +== The authorize Tag This tag is used to determine whether its contents should be evaluated or not. In Spring Security 3.0, it can be used in two ways footnote:[ The legacy options from Spring Security 2.0 are also supported, but discouraged. @@ -65,7 +65,7 @@ This approach can also be combined with a `method` attribute, supplying the HTTP The Boolean result of evaluating the tag (whether it grants or denies access) can be stored in a page context scope variable by setting the `var` attribute to the variable name, avoiding the need for duplicating and re-evaluating the condition at other points in the page. -==== Disabling Tag Authorization for Testing +=== Disabling Tag Authorization for Testing Hiding a link in a page for unauthorized users doesn't prevent them from accessing the URL. They could just type it into their browser directly, for example. As part of your testing process, you may want to reveal the hidden areas in order to check that links really are secured at the back end. @@ -77,7 +77,7 @@ Try running the "tutorial" sample application with this property enabled, for ex You can also set the properties `spring.security.securedUIPrefix` and `spring.security.securedUISuffix` if you want to change surrounding text from the default `span` tags (or use empty strings to remove it completely). -=== The authentication Tag +== The authentication Tag This tag allows access to the current `Authentication` object stored in the security context. It renders a property of the object directly in the JSP. So, for example, if the `principal` property of the `Authentication` is an instance of Spring Security's `UserDetails` object, then using `` will render the name of the current user. @@ -86,7 +86,7 @@ Of course, it isn't necessary to use JSP tags for this kind of thing and some pe You can access the `Authentication` object in your MVC controller (by calling `SecurityContextHolder.getContext().getAuthentication()`) and add the data directly to your model for rendering by the view. -=== The accesscontrollist Tag +== The accesscontrollist Tag This tag is only valid when used with Spring Security's ACL module. It checks a comma-separated list of required permissions for a specified domain object. If the current user has all of those permissions, then the tag body will be evaluated. @@ -113,7 +113,7 @@ The `Acl` will be invoked with the required permissions to check if all of them This tag also supports the `var` attribute, in the same way as the `authorize` tag. [[taglibs-csrfinput]] -=== The csrfInput Tag +== The csrfInput Tag If CSRF protection is enabled, this tag inserts a hidden form field with the correct name and value for the CSRF protection token. If CSRF protection is not enabled, this tag outputs nothing. @@ -134,7 +134,7 @@ Spring Security handles Spring forms automatically. ---- [[taglibs-csrfmeta]] -=== The csrfMetaTags Tag +== The csrfMetaTags Tag If CSRF protection is enabled, this tag inserts meta tags containing the CSRF protection token form field and header names and CSRF protection token value. These meta tags are useful for employing CSRF protection within JavaScript in your applications. diff --git a/docs/modules/ROOT/pages/servlet/integrations/localization.adoc b/docs/modules/ROOT/pages/servlet/integrations/localization.adoc index 0f8f9b402e..e1fc22b9a2 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/localization.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/localization.adoc @@ -1,5 +1,5 @@ [[localization]] -== Localization += Localization Spring Security supports localization of exception messages that end users are likely to see. If your application is designed for English-speaking users, you don't need to do anything as by default all Security messages are in English. If you need to support other locales, everything you need to know is contained in this section. diff --git a/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc index 796be873fd..ef2d849355 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc @@ -1,11 +1,11 @@ [[mvc]] -== Spring MVC Integration += Spring MVC Integration Spring Security provides a number of optional integrations with Spring MVC. This section covers the integration in further detail. [[mvc-enablewebmvcsecurity]] -=== @EnableWebMvcSecurity +== @EnableWebMvcSecurity NOTE: As of Spring Security 4.0, `@EnableWebMvcSecurity` is deprecated. The replacement is `@EnableWebSecurity` which will determine adding the Spring MVC features based upon the classpath. @@ -16,7 +16,7 @@ NOTE: Spring Security provides the configuration using Spring MVC's https://docs This means that if you are using more advanced options, like integrating with `WebMvcConfigurationSupport` directly, then you will need to manually provide the Spring Security configuration. [[mvc-requestmatcher]] -=== MvcRequestMatcher +== MvcRequestMatcher Spring Security provides deep integration with how Spring MVC matches on URLs with `MvcRequestMatcher`. This is helpful to ensure your Security rules match the logic used to handle your requests. @@ -212,7 +212,7 @@ or in XML ---- [[mvc-authentication-principal]] -=== @AuthenticationPrincipal +== @AuthenticationPrincipal Spring Security provides `AuthenticationPrincipalArgumentResolver` which can automatically resolve the current `Authentication.getPrincipal()` for Spring MVC arguments. By using `@EnableWebSecurity` you will automatically have this added to your Spring MVC configuration. @@ -448,7 +448,7 @@ open fun findMessagesForUser(@CurrentUser customUser: CustomUser?): ModelAndView [[mvc-async]] -=== Spring MVC Async Integration +== Spring MVC Async Integration Spring Web MVC 3.2+ has excellent support for https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/mvc.html#mvc-ann-async[Asynchronous Request Processing]. With no additional configuration, Spring Security will automatically setup the `SecurityContext` to the `Thread` that invokes a `Callable` returned by your controllers. @@ -495,9 +495,9 @@ This is because `DeferredResult` is processed by the users and thus there is no However, you can still use <> to provide transparent integration with Spring Security. [[mvc-csrf]] -=== Spring MVC and CSRF Integration +== Spring MVC and CSRF Integration -==== Automatic Token Inclusion +=== Automatic Token Inclusion Spring Security will automatically <> within forms that use the https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/view.html#view-jsp-formtaglib-formtag[Spring MVC form tag]. For example, the following JSP: @@ -541,7 +541,7 @@ Will output HTML that is similar to the following: ---- [[mvc-csrf-resolver]] -==== Resolving the CsrfToken +=== Resolving the CsrfToken Spring Security provides `CsrfTokenArgumentResolver` which can automatically resolve the current `CsrfToken` for Spring MVC arguments. By using <> you will automatically have this added to your Spring MVC configuration. diff --git a/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc b/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc index ad76aa54a0..6bc74d8af5 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc @@ -1,14 +1,14 @@ [[servletapi]] -== Servlet API integration += Servlet API integration This section describes how Spring Security is integrated with the Servlet API. [[servletapi-25]] -=== Servlet 2.5+ Integration +== Servlet 2.5+ Integration [[servletapi-remote-user]] -==== HttpServletRequest.getRemoteUser() +=== HttpServletRequest.getRemoteUser() The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[HttpServletRequest.getRemoteUser()] will return the result of `SecurityContextHolder.getContext().getAuthentication().getName()` which is typically the current username. This can be useful if you want to display the current username in your application. Additionally, checking if this is null can be used to indicate if a user has authenticated or is anonymous. @@ -16,7 +16,7 @@ Knowing if the user is authenticated or not can be useful for determining if cer [[servletapi-user-principal]] -==== HttpServletRequest.getUserPrincipal() +=== HttpServletRequest.getUserPrincipal() The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[HttpServletRequest.getUserPrincipal()] will return the result of `SecurityContextHolder.getContext().getAuthentication()`. This means it is an `Authentication` which is typically an instance of `UsernamePasswordAuthenticationToken` when using username and password based authentication. This can be useful if you need additional information about your user. @@ -55,7 +55,7 @@ Instead, one should centralize it to reduce any coupling of Spring Security and ==== [[servletapi-user-in-role]] -==== HttpServletRequest.isUserInRole(String) +=== HttpServletRequest.isUserInRole(String) The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[HttpServletRequest.isUserInRole(String)] will determine if `SecurityContextHolder.getContext().getAuthentication().getAuthorities()` contains a `GrantedAuthority` with the role passed into `isUserInRole(String)`. Typically users should not pass in the "ROLE_" prefix into this method since it is added automatically. For example, if you want to determine if the current user has the authority "ROLE_ADMIN", you could use the following: @@ -78,18 +78,18 @@ This might be useful to determine if certain UI components should be displayed. For example, you might display admin links only if the current user is an admin. [[servletapi-3]] -=== Servlet 3+ Integration +== Servlet 3+ Integration The following section describes the Servlet 3 methods that Spring Security integrates with. [[servletapi-authenticate]] -==== HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse) +=== HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse) The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#authenticate%28javax.servlet.http.HttpServletResponse%29[HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)] method can be used to ensure that a user is authenticated. If they are not authenticated, the configured AuthenticationEntryPoint will be used to request the user to authenticate (i.e. redirect to the login page). [[servletapi-login]] -==== HttpServletRequest.login(String,String) +=== HttpServletRequest.login(String,String) The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login%28java.lang.String,%20java.lang.String%29[HttpServletRequest.login(String,String)] method can be used to authenticate the user with the current `AuthenticationManager`. For example, the following would attempt to authenticate with the username "user" and password "password": @@ -121,7 +121,7 @@ It is not necessary to catch the ServletException if you want Spring Security to ==== [[servletapi-logout]] -==== HttpServletRequest.logout() +=== HttpServletRequest.logout() The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout%28%29[HttpServletRequest.logout()] method can be used to log the current user out. Typically this means that the SecurityContextHolder will be cleared out, the HttpSession will be invalidated, any "Remember Me" authentication will be cleaned up, etc. @@ -130,7 +130,7 @@ It is important to note that after HttpServletRequest.logout() has been invoked, Typically this would involve a redirect to the welcome page. [[servletapi-start-runnable]] -==== AsyncContext.start(Runnable) +=== AsyncContext.start(Runnable) The https://docs.oracle.com/javaee/6/api/javax/servlet/AsyncContext.html#start%28java.lang.Runnable%29[AsyncContext.start(Runnable)] method that ensures your credentials will be propagated to the new Thread. Using Spring Security's concurrency support, Spring Security overrides the AsyncContext.start(Runnable) to ensure that the current SecurityContext is used when processing the Runnable. For example, the following would output the current user's Authentication: @@ -174,7 +174,7 @@ async.start { ==== [[servletapi-async]] -==== Async Servlet Support +=== Async Servlet Support If you are using Java Based configuration, you are ready to go. If you are using XML configuration, there are a few updates that are necessary. The first step is to ensure you have updated your web.xml to use at least the 3.0 schema as shown below: @@ -265,9 +265,9 @@ When Spring Security automatically saved the SecurityContext on committing the H Since version 3.2, Spring Security is smart enough to no longer automatically save the SecurityContext on committing the HttpServletResponse as soon as HttpServletRequest.startAsync() is invoked. [[servletapi-31]] -=== Servlet 3.1+ Integration +== Servlet 3.1+ Integration The following section describes the Servlet 3.1 methods that Spring Security integrates with. [[servletapi-change-session-id]] -==== HttpServletRequest#changeSessionId() +=== HttpServletRequest#changeSessionId() The https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServletRequest.html#changeSessionId()[HttpServletRequest.changeSessionId()] is the default method for protecting against <> attacks in Servlet 3.1 and higher. diff --git a/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc b/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc index 43b83c752e..2ef0312334 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc @@ -1,5 +1,5 @@ [[websocket]] -== WebSocket Security += WebSocket Security Spring Security 4 added support for securing https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html[Spring's WebSocket support]. This section describes how to use Spring Security's WebSocket support. @@ -12,7 +12,7 @@ Additionally, JSR-356 does not provide a way to intercept messages, so security **** [[websocket-configuration]] -=== WebSocket Configuration +== WebSocket Configuration Spring Security 4.0 has introduced authorization support for WebSockets through the Spring Messaging abstraction. To configure authorization using Java Configuration, simply extend the `AbstractSecurityWebSocketMessageBrokerConfigurer` and configure the `MessageSecurityMetadataSourceRegistry`. @@ -69,7 +69,7 @@ This will ensure that: <3> Our messages require the proper authorization. Specifically, any inbound message that starts with "/user/" will require ROLE_USER. Additional details on authorization can be found in <> [[websocket-authentication]] -=== WebSocket Authentication +== WebSocket Authentication WebSockets reuse the same authentication information that is found in the HTTP request when the WebSocket connection was made. This means that the `Principal` on the `HttpServletRequest` will be handed off to WebSockets. @@ -78,7 +78,7 @@ If you are using Spring Security, the `Principal` on the `HttpServletRequest` is More concretely, to ensure a user has authenticated to your WebSocket application, all that is necessary is to ensure that you setup Spring Security to authenticate your HTTP based web application. [[websocket-authorization]] -=== WebSocket Authorization +== WebSocket Authorization Spring Security 4.0 has introduced authorization support for WebSockets through the Spring Messaging abstraction. To configure authorization using Java Configuration, simply extend the `AbstractSecurityWebSocketMessageBrokerConfigurer` and configure the `MessageSecurityMetadataSourceRegistry`. @@ -168,12 +168,12 @@ This will ensure that: <6> Any other message with a destination is rejected. This is a good idea to ensure that you do not miss any messages. [[websocket-authorization-notes]] -==== WebSocket Authorization Notes +=== WebSocket Authorization Notes In order to properly secure your application it is important to understand Spring's WebSocket support. [[websocket-authorization-notes-messagetypes]] -===== WebSocket Authorization on Message Types +==== WebSocket Authorization on Message Types It is important to understand the distinction between SUBSCRIBE and MESSAGE types of messages and how it works within Spring. @@ -188,7 +188,7 @@ If we allowed sending a MESSAGE to "/topic/system/notifications", then clients c In general, it is common for applications to deny any MESSAGE sent to a destination that starts with the https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-stomp[broker prefix] (i.e. "/topic/" or "/queue/"). [[websocket-authorization-notes-destinations]] -===== WebSocket Authorization on Destinations +==== WebSocket Authorization on Destinations It is also is important to understand how destinations are transformed. @@ -206,7 +206,7 @@ In general, it is common for applications to deny any SUBSCRIBE sent to a messag Of course we may provide exceptions to account for things like [[websocket-authorization-notes-outbound]] -==== Outbound Messages +=== Outbound Messages Spring contains a section titled https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-stomp-message-flow[Flow of Messages] that describes how messages flow through the system. It is important to note that Spring Security only secures the `clientInboundChannel`. @@ -217,13 +217,13 @@ For every message that goes in, there are typically many more that go out. Instead of securing the outbound messages, we encourage securing the subscription to the endpoints. [[websocket-sameorigin]] -=== Enforcing Same Origin Policy +== Enforcing Same Origin Policy It is important to emphasize that the browser does not enforce the https://en.wikipedia.org/wiki/Same-origin_policy[Same Origin Policy] for WebSocket connections. This is an extremely important consideration. [[websocket-sameorigin-why]] -==== Why Same Origin? +=== Why Same Origin? Consider the following scenario. A user visits bank.com and authenticates to their account. @@ -238,13 +238,13 @@ Since SockJS tries to emulate WebSockets it also bypasses the Same Origin Policy This means developers need to explicitly protect their applications from external domains when using SockJS. [[websocket-sameorigin-spring]] -==== Spring WebSocket Allowed Origin +=== Spring WebSocket Allowed Origin Fortunately, since Spring 4.1.5 Spring's WebSocket and SockJS support restricts access to the https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-server-allowed-origins[current domain]. Spring Security adds an additional layer of protection to provide https://en.wikipedia.org/wiki/Defense_in_depth_(computing)[defence in depth]. [[websocket-sameorigin-csrf]] -==== Adding CSRF to Stomp Headers +=== Adding CSRF to Stomp Headers By default Spring Security requires the <> in any CONNECT message type. This ensures that only a site that has access to the CSRF token can connect. @@ -310,7 +310,7 @@ stompClient.connect(headers, function(frame) { ---- [[websocket-sameorigin-disable]] -==== Disable CSRF within WebSockets +=== Disable CSRF within WebSockets If you want to allow other domains to access your site, you can disable Spring Security's protection. For example, in Java Configuration you can use the following: @@ -348,13 +348,13 @@ open class WebSocketSecurityConfig : AbstractSecurityWebSocketMessageBrokerConfi [[websocket-sockjs]] -=== Working with SockJS +== Working with SockJS https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-fallback[SockJS] provides fallback transports to support older browsers. When using the fallback options we need to relax a few security constraints to allow SockJS to work with Spring Security. [[websocket-sockjs-sameorigin]] -==== SockJS & frame-options +=== SockJS & frame-options SockJS may use an https://github.com/sockjs/sockjs-client/tree/v0.3.4[transport that leverages an iframe]. By default Spring Security will <> the site from being framed to prevent Clickjacking attacks. @@ -418,7 +418,7 @@ open class WebSecurityConfig : WebSecurityConfigurerAdapter() { ==== [[websocket-sockjs-csrf]] -==== SockJS & Relaxing CSRF +=== SockJS & Relaxing CSRF SockJS uses a POST on the CONNECT messages for any HTTP based transport. Typically we need to include the CSRF token in an HTTP header or an HTTP parameter. diff --git a/docs/modules/ROOT/pages/servlet/saml2/index.adoc b/docs/modules/ROOT/pages/servlet/saml2/index.adoc index e872f5d9d8..e0adeaf0c7 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/index.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/index.adoc @@ -1,4 +1,1618 @@ [[servlet-saml2]] = SAML2 -include::saml2-login.adoc[] +Spring Security provides comprehensive SAML 2 support. +This section discusses how to integrate SAML 2 into your servlet based application. + +[[servlet-saml2login]] +== SAML 2.0 Login +:figures: images/servlet/saml2 +:icondir: images/icons + +The SAML 2.0 Login feature provides an application with the capability to act as a SAML 2.0 Relying Party, having users https://wiki.shibboleth.net/confluence/display/CONCEPT/FlowsAndConfig[log in] to the application by using their existing account at a SAML 2.0 Asserting Party (Okta, ADFS, etc). + +NOTE: SAML 2.0 Login is implemented by using the *Web Browser SSO Profile*, as specified in +https://www.oasis-open.org/committees/download.php/35389/sstc-saml-profiles-errata-2.0-wd-06-diff.pdf#page=15[SAML 2 Profiles]. + +[[servlet-saml2login-spring-security-history]] +Since 2009, support for relying parties has existed as an https://github.com/spring-projects/spring-security-saml/tree/1e013b07a7772defd6a26fcfae187c9bf661ee8f#spring-saml[extension project]. +In 2019, the process began to port that into https://github.com/spring-projects/spring-security[Spring Security] proper. +This process is similar to the one started in 2017 for <>. + +[NOTE] +==== +A working sample for {gh-samples-url}/servlet/spring-boot/java/saml2-login[SAML 2.0 Login] is available in the {gh-samples-url}[Spring Security Samples repository]. +==== + +Let's take a look at how SAML 2.0 Relying Party Authentication works within Spring Security. +First, we see that, like <>, Spring Security takes the user to a third-party for performing authentication. +It does this through a series of redirects. + +.Redirecting to Asserting Party Authentication +image::{figures}/saml2webssoauthenticationrequestfilter.png[] + +The figure above builds off our <> and <> diagrams: + +image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized. + +image:{icondir}/number_2.png[] Spring Security's <> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. + +image:{icondir}/number_3.png[] Since the user lacks authorization, the <> initiates __Start Authentication__. +The configured <> is an instance of {security-api-url}org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html[`LoginUrlAuthenticationEntryPoint`] which redirects to <` generating endpoint>>, `Saml2WebSsoAuthenticationRequestFilter`. +Or, if you've <>, it will first redirect to a picker page. + +image:{icondir}/number_4.png[] Next, the `Saml2WebSsoAuthenticationRequestFilter` creates, signs, serializes, and encodes a `` using its configured <>. + +image:{icondir}/number_5.png[] Then, the browser takes this `` and presents it to the asserting party. +The asserting party attempts to authentication the user. +If successful, it will return a `` back to the browser. + +image:{icondir}/number_6.png[] The browser then POSTs the `` to the assertion consumer service endpoint. + +[[servlet-saml2login-authentication-saml2webssoauthenticationfilter]] +.Authenticating a `` +image::{figures}/saml2webssoauthenticationfilter.png[] + +The figure builds off our <> diagram. + +image:{icondir}/number_1.png[] When the browser submits a `` to the application, it <>. +This filter calls its configured `AuthenticationConverter` to create a `Saml2AuthenticationToken` by extracting the response from the `HttpServletRequest`. +This converter additionally resolves the <> and supplies it to `Saml2AuthenticationToken`. + +image:{icondir}/number_2.png[] Next, the filter passes the token to its configured <>. +By default, it will use the <>. + +image:{icondir}/number_3.png[] If authentication fails, then __Failure__ + +* The <> is cleared out. +* The <> is invoked to restart the authentication process. + +image:{icondir}/number_4.png[] If authentication is successful, then __Success__. + +* The <> is set on the <>. +* The `Saml2WebSsoAuthenticationFilter` invokes `FilterChain#doFilter(request,response)` to continue with the rest of the application logic. + +[[servlet-saml2login-minimaldependencies]] +=== Minimal Dependencies + +SAML 2.0 service provider support resides in `spring-security-saml2-service-provider`. +It builds off of the OpenSAML library. + +[[servlet-saml2login-minimalconfiguration]] +=== Minimal Configuration + +When using https://spring.io/projects/spring-boot[Spring Boot], configuring an application as a service provider consists of two basic steps. +First, include the needed dependencies and second, indicate the necessary asserting party metadata. + +[NOTE] +Also, this presupposes that you've already <>. + +==== Specifying Identity Provider Metadata + +In a Spring Boot application, to specify an identity provider's metadata, simply do: + +[source,yml] +---- +spring: + security: + saml2: + relyingparty: + registration: + adfs: + identityprovider: + entity-id: https://idp.example.com/issuer + verification.credentials: + - certificate-location: "classpath:idp.crt" + singlesignon.url: https://idp.example.com/issuer/sso + singlesignon.sign-request: false +---- + +where + +* `https://idp.example.com/issuer` is the value contained in the `Issuer` attribute of the SAML responses that the identity provider will issue +* `classpath:idp.crt` is the location on the classpath for the identity provider's certificate for verifying SAML responses, and +* `https://idp.example.com/issuer/sso` is the endpoint where the identity provider is expecting `AuthnRequest` s. + +And that's it! + +[NOTE] +Identity Provider and Asserting Party are synonymous, as are Service Provider and Relying Party. +These are frequently abbreviated as AP and RP, respectively. + +==== Runtime Expectations + +As configured above, the application processes any `+POST /login/saml2/sso/{registrationId}+` request containing a `SAMLResponse` parameter: + +[source,html] +---- +POST /login/saml2/sso/adfs HTTP/1.1 + +SAMLResponse=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZ... +---- + +There are two ways to see induce your asserting party to generate a `SAMLResponse`: + +* First, you can navigate to your asserting party. +It likely has some kind of link or button for each registered relying party that you can click to send the `SAMLResponse`. +* Second, you can navigate to a protected page in your app, for example, `http://localhost:8080`. +Your app then redirects to the configured asserting party which then sends the `SAMLResponse`. + +From here, consider jumping to: + +* <> +* <> +* <> + +[[servlet-saml2login-architecture]] +=== How SAML 2.0 Login Integrates with OpenSAML + +Spring Security's SAML 2.0 support has a couple of design goals: + +* First, rely on a library for SAML 2.0 operations and domain objects. +To achieve this, Spring Security uses OpenSAML. +* Second, ensure this library is not required when using Spring Security's SAML support. +To achieve this, any interfaces or classes where Spring Security uses OpenSAML in the contract remain encapsulated. +This makes it possible for you to switch out OpenSAML for some other library or even an unsupported version of OpenSAML. + +As a natural outcome of the above two goals, Spring Security's SAML API is quite small relative to other modules. +Instead, classes like `OpenSaml4AuthenticationRequestFactory` and `OpenSaml4AuthenticationProvider` expose `Converter` s that customize various steps in the authentication process. + +For example, once your application receives a `SAMLResponse` and delegates to `Saml2WebSsoAuthenticationFilter`, the filter will delegate to `OpenSaml4AuthenticationProvider`. + +[NOTE] +For backward compatibility, Spring Security will use the latest OpenSAML 3 by default. +Note, though that OpenSAML 3 has reached it's end-of-life and updating to OpenSAML 4.x is recommended. +For that reason, Spring Security supports both OpenSAML 3.x and 4.x. +If you manage your OpenSAML dependency to 4.x, then Spring Security will select its OpenSAML 4.x implementations. + +.Authenticating an OpenSAML `Response` +image:{figures}/opensamlauthenticationprovider.png[] + +This figure builds off of the <>. + +image:{icondir}/number_1.png[] The `Saml2WebSsoAuthenticationFilter` formulates the `Saml2AuthenticationToken` and invokes the <>. + +image:{icondir}/number_2.png[] The <> invokes the OpenSAML authentication provider. + +image:{icondir}/number_3.png[] The authentication provider deserializes the response into an OpenSAML `Response` and checks its signature. +If the signature is invalid, authentication fails. + +image:{icondir}/number_4.png[] Then, the provider <>. +If any decryptions fail, authentication fails. + +image:{icondir}/number_5.png[] Next, the provider validates the response's `Issuer` and `Destination` values. +If they don't match what's in the `RelyingPartyRegistration`, authentication fails. + +image:{icondir}/number_6.png[] After that, the provider verifies the signature of each `Assertion`. +If any signature is invalid, authentication fails. +Also, if neither the response nor the assertions have signatures, authentication fails. +Either the response or all the assertions must have signatures. + +image:{icondir}/number_7.png[] Then, the provider <>. +If any decryptions fail, authentication fails. + +image:{icondir}/number_8.png[] Next, the provider validates each assertion's `ExpiresAt` and `NotBefore` timestamps, the `` and any `` conditions. +If any validations fail, authentication fails. + +image:{icondir}/number_9.png[] Following that, the provider takes the first assertion's `AttributeStatement` and maps it to a `Map>`. +It also grants the `ROLE_USER` granted authority. + +image:{icondir}/number_10.png[] And finally, it takes the `NameID` from the first assertion, the `Map` of attributes, and the `GrantedAuthority` and constructs a `Saml2AuthenticatedPrincipal`. +Then, it places that principal and the authorities into a `Saml2Authentication`. + +The resulting `Authentication#getPrincipal` is a Spring Security `Saml2AuthenticatedPrincipal` object, and `Authentication#getName` maps to the first assertion's `NameID` element. + +[[servlet-saml2login-opensaml-customization]] +==== Customizing OpenSAML Configuration + +Any class that uses both Spring Security and OpenSAML should statically initialize `OpenSamlInitializationService` at the beginning of the class, like so: + +==== +.Java +[source,java,role="primary"] +---- +static { + OpenSamlInitializationService.initialize(); +} +---- + + +.Kotlin +[source,kotlin,role="secondary"] +---- +companion object { + init { + OpenSamlInitializationService.initialize() + } +} +---- +==== + +This replaces OpenSAML's `InitializationService#initialize`. + +Occasionally, it can be valuable to customize how OpenSAML builds, marshalls, and unmarshalls SAML objects. +In these circumstances, you may instead want to call `OpenSamlInitializationService#requireInitialize(Consumer)` that gives you access to OpenSAML's `XMLObjectProviderFactory`. + +For example, when sending an unsigned AuthNRequest, you may want to force reauthentication. +In that case, you can register your own `AuthnRequestMarshaller`, like so: + +==== +.Java +[source,java,role="primary"] +---- +static { + OpenSamlInitializationService.requireInitialize(factory -> { + AuthnRequestMarshaller marshaller = new AuthnRequestMarshaller() { + @Override + public Element marshall(XMLObject object, Element element) throws MarshallingException { + configureAuthnRequest((AuthnRequest) object); + return super.marshall(object, element); + } + + public Element marshall(XMLObject object, Document document) throws MarshallingException { + configureAuthnRequest((AuthnRequest) object); + return super.marshall(object, document); + } + + private void configureAuthnRequest(AuthnRequest authnRequest) { + authnRequest.setForceAuthn(true); + } + } + + factory.getMarshallerFactory().registerMarshaller(AuthnRequest.DEFAULT_ELEMENT_NAME, marshaller); + }); +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +companion object { + init { + OpenSamlInitializationService.requireInitialize { + val marshaller = object : AuthnRequestMarshaller() { + override fun marshall(xmlObject: XMLObject, element: Element): Element { + configureAuthnRequest(xmlObject as AuthnRequest) + return super.marshall(xmlObject, element) + } + + override fun marshall(xmlObject: XMLObject, document: Document): Element { + configureAuthnRequest(xmlObject as AuthnRequest) + return super.marshall(xmlObject, document) + } + + private fun configureAuthnRequest(authnRequest: AuthnRequest) { + authnRequest.isForceAuthn = true + } + } + it.marshallerFactory.registerMarshaller(AuthnRequest.DEFAULT_ELEMENT_NAME, marshaller) + } + } +} +---- +==== + +The `requireInitialize` method may only be called once per application instance. + +[[servlet-saml2login-sansboot]] +=== Overriding or Replacing Boot Auto Configuration + +There are two `@Bean` s that Spring Boot generates for a relying party. + +The first is a `WebSecurityConfigurerAdapter` that configures the app as a relying party. +When including `spring-security-saml2-service-provider`, the `WebSecurityConfigurerAdapter` looks like: + +.Default JWT Configuration +==== +.Java +[source,java,role="primary"] +---- +protected void configure(HttpSecurity http) { + http + .authorizeRequests(authorize -> authorize + .anyRequest().authenticated() + ) + .saml2Login(withDefaults()); +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +fun configure(http: HttpSecurity) { + http { + authorizeRequests { + authorize(anyRequest, authenticated) + } + saml2Login { } + } +} +---- +==== + +If the application doesn't expose a `WebSecurityConfigurerAdapter` bean, then Spring Boot will expose the above default one. + +You can replace this by exposing the bean within the application: + +.Custom SAML 2.0 Login Configuration +==== +.Java +[source,java,role="primary"] +---- +@EnableWebSecurity +public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter { + protected void configure(HttpSecurity http) { + http + .authorizeRequests(authorize -> authorize + .mvcMatchers("/messages/**").hasAuthority("ROLE_USER") + .anyRequest().authenticated() + ) + .saml2Login(withDefaults()); + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@EnableWebSecurity +class MyCustomSecurityConfiguration : WebSecurityConfigurerAdapter() { + override fun configure(http: HttpSecurity) { + http { + authorizeRequests { + authorize("/messages/**", hasAuthority("ROLE_USER")) + authorize(anyRequest, authenticated) + } + saml2Login { + } + } + } +} +---- +==== + +The above requires the role of `USER` for any URL that starts with `/messages/`. + +[[servlet-saml2login-relyingpartyregistrationrepository]] +The second `@Bean` Spring Boot creates is a {security-api-url}org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistrationRepository.html[`RelyingPartyRegistrationRepository`], which represents the asserting party and relying party metadata. +This includes things like the location of the SSO endpoint the relying party should use when requesting authentication from the asserting party. + +You can override the default by publishing your own `RelyingPartyRegistrationRepository` bean. +For example, you can look up the asserting party's configuration by hitting its metadata endpoint like so: + +.Relying Party Registration Repository +==== +.Java +[source,java,role="primary"] +---- +@Value("${metadata.location}") +String assertingPartyMetadataLocation; + +@Bean +public RelyingPartyRegistrationRepository relyingPartyRegistrations() { + RelyingPartyRegistration registration = RelyingPartyRegistrations + .fromMetadataLocation(assertingPartyMetadataLocation) + .registrationId("example") + .build(); + return new InMemoryRelyingPartyRegistrationRepository(registration); +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@Value("\${metadata.location}") +var assertingPartyMetadataLocation: String? = null + +@Bean +open fun relyingPartyRegistrations(): RelyingPartyRegistrationRepository? { + val registration = RelyingPartyRegistrations + .fromMetadataLocation(assertingPartyMetadataLocation) + .registrationId("example") + .build() + return InMemoryRelyingPartyRegistrationRepository(registration) +} +---- +==== + +Or you can provide each detail manually, as you can see below: + +.Relying Party Registration Repository Manual Configuration +==== +.Java +[source,java,role="primary"] +---- +@Value("${verification.key}") +File verificationKey; + +@Bean +public RelyingPartyRegistrationRepository relyingPartyRegistrations() throws Exception { + X509Certificate certificate = X509Support.decodeCertificate(this.verificationKey); + Saml2X509Credential credential = Saml2X509Credential.verification(certificate); + RelyingPartyRegistration registration = RelyingPartyRegistration + .withRegistrationId("example") + .assertingPartyDetails(party -> party + .entityId("https://idp.example.com/issuer") + .singleSignOnServiceLocation("https://idp.example.com/SSO.saml2") + .wantAuthnRequestsSigned(false) + .verificationX509Credentials(c -> c.add(credential)) + ) + .build(); + return new InMemoryRelyingPartyRegistrationRepository(registration); +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@Value("\${verification.key}") +var verificationKey: File? = null + +@Bean +open fun relyingPartyRegistrations(): RelyingPartyRegistrationRepository { + val certificate: X509Certificate? = X509Support.decodeCertificate(verificationKey!!) + val credential: Saml2X509Credential = Saml2X509Credential.verification(certificate) + val registration = RelyingPartyRegistration + .withRegistrationId("example") + .assertingPartyDetails { party: AssertingPartyDetails.Builder -> + party + .entityId("https://idp.example.com/issuer") + .singleSignOnServiceLocation("https://idp.example.com/SSO.saml2") + .wantAuthnRequestsSigned(false) + .verificationX509Credentials { c: MutableCollection -> + c.add( + credential + ) + } + } + .build() + return InMemoryRelyingPartyRegistrationRepository(registration) +} +---- +==== + +[NOTE] +Note that `X509Support` is an OpenSAML class, used here in the snippet for brevity + +[[servlet-saml2login-relyingpartyregistrationrepository-dsl]] + +Alternatively, you can directly wire up the repository using the DSL, which will also override the auto-configured `WebSecurityConfigurerAdapter`: + +.Custom Relying Party Registration DSL +==== +.Java +[source,java,role="primary"] +---- +@EnableWebSecurity +public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter { + protected void configure(HttpSecurity http) { + http + .authorizeRequests(authorize -> authorize + .mvcMatchers("/messages/**").hasAuthority("ROLE_USER") + .anyRequest().authenticated() + ) + .saml2Login(saml2 -> saml2 + .relyingPartyRegistrationRepository(relyingPartyRegistrations()) + ); + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@EnableWebSecurity +class MyCustomSecurityConfiguration : WebSecurityConfigurerAdapter() { + override fun configure(http: HttpSecurity) { + http { + authorizeRequests { + authorize("/messages/**", hasAuthority("ROLE_USER")) + authorize(anyRequest, authenticated) + } + saml2Login { + relyingPartyRegistrationRepository = relyingPartyRegistrations() + } + } + } +} +---- +==== + +[NOTE] +A relying party can be multi-tenant by registering more than one relying party in the `RelyingPartyRegistrationRepository`. + +[[servlet-saml2login-relyingpartyregistration]] +=== RelyingPartyRegistration +A {security-api-url}org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistration.html[`RelyingPartyRegistration`] +instance represents a link between an relying party and assering party's metadata. + +In a `RelyingPartyRegistration`, you can provide relying party metadata like its `Issuer` value, where it expects SAML Responses to be sent to, and any credentials that it owns for the purposes of signing or decrypting payloads. + +Also, you can provide asserting party metadata like its `Issuer` value, where it expects AuthnRequests to be sent to, and any public credentials that it owns for the purposes of the relying party verifying or encrypting payloads. + +The following `RelyingPartyRegistration` is the minimum required for most setups: + +==== +.Java +[source,java,role="primary"] +---- +RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistrations + .fromMetadataLocation("https://ap.example.org/metadata") + .registrationId("my-id") + .build(); +---- +.Kotlin +[source,kotlin,role="secondary"] +---- +val relyingPartyRegistration = RelyingPartyRegistrations + .fromMetadataLocation("https://ap.example.org/metadata") + .registrationId("my-id") + .build() +---- +==== + +Note that you can also create a `RelyingPartyRegistration` from an arbitrary `InputStream` source. +One such example is when the metadata is stored in a database: + +[source,java] +---- +String xml = fromDatabase(); +try (InputStream source = new ByteArrayInputStream(xml.getBytes())) { + RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistrations + .fromMetadata(source) + .registrationId("my-id") + .build(); +} +---- + +Though a more sophisticated setup is also possible, like so: + +==== +.Java +[source,java,role="primary"] +---- +RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistration.withRegistrationId("my-id") + .entityId("{baseUrl}/{registrationId}") + .decryptionX509Credentials(c -> c.add(relyingPartyDecryptingCredential())) + .assertionConsumerServiceLocation("/my-login-endpoint/{registrationId}") + .assertingPartyDetails(party -> party + .entityId("https://ap.example.org") + .verificationX509Credentials(c -> c.add(assertingPartyVerifyingCredential())) + .singleSignOnServiceLocation("https://ap.example.org/SSO.saml2") + ) + .build(); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val relyingPartyRegistration = + RelyingPartyRegistration.withRegistrationId("my-id") + .entityId("{baseUrl}/{registrationId}") + .decryptionX509Credentials { c: MutableCollection -> + c.add(relyingPartyDecryptingCredential()) + } + .assertionConsumerServiceLocation("/my-login-endpoint/{registrationId}") + .assertingPartyDetails { party -> party + .entityId("https://ap.example.org") + .verificationX509Credentials { c -> c.add(assertingPartyVerifyingCredential()) } + .singleSignOnServiceLocation("https://ap.example.org/SSO.saml2") + } + .build() +---- +==== + +[TIP] +The top-level metadata methods are details about the relying party. +The methods inside `assertingPartyDetails` are details about the asserting party. + +[NOTE] +The location where a relying party is expecting SAML Responses is the Assertion Consumer Service Location. + +The default for the relying party's `entityId` is `+{baseUrl}/saml2/service-provider-metadata/{registrationId}+`. +This is this value needed when configuring the asserting party to know about your relying party. + +The default for the `assertionConsumerServiceLocation` is `+/login/saml2/sso/{registrationId}+`. +It's mapped by default to <> in the filter chain. + +[[servlet-saml2login-rpr-uripatterns]] +==== URI Patterns + +You probably noticed in the above examples the `+{baseUrl}+` and `+{registrationId}+` placeholders. + +These are useful for generating URIs. As such, the relying party's `entityId` and `assertionConsumerServiceLocation` support the following placeholders: + +* `baseUrl` - the scheme, host, and port of a deployed application +* `registrationId` - the registration id for this relying party +* `baseScheme` - the scheme of a deployed application +* `baseHost` - the host of a deployed application +* `basePort` - the port of a deployed application + +For example, the `assertionConsumerServiceLocation` defined above was: + +`+/my-login-endpoint/{registrationId}+` + +which in a deployed application would translate to + +`+/my-login-endpoint/adfs+` + +The `entityId` above was defined as: + +`+{baseUrl}/{registrationId}+` + +which in a deployed application would translate to + +`+https://rp.example.com/adfs+` + +[[servlet-saml2login-rpr-credentials]] +==== Credentials + +You also likely noticed the credential that was used. + +Oftentimes, a relying party will use the same key to sign payloads as well as decrypt them. +Or it will use the same key to verify payloads as well as encrypt them. + +Because of this, Spring Security ships with `Saml2X509Credential`, a SAML-specific credential that simplifies configuring the same key for different use cases. + +At a minimum, it's necessary to have a certificate from the asserting party so that the asserting party's signed responses can be verified. + +To construct a `Saml2X509Credential` that you'll use to verify assertions from the asserting party, you can load the file and use +the `CertificateFactory` like so: + +==== +.Java +[source,java,role="primary"] +---- +Resource resource = new ClassPathResource("ap.crt"); +try (InputStream is = resource.getInputStream()) { + X509Certificate certificate = (X509Certificate) + CertificateFactory.getInstance("X.509").generateCertificate(is); + return Saml2X509Credential.verification(certificate); +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val resource = ClassPathResource("ap.crt") +resource.inputStream.use { + return Saml2X509Credential.verification( + CertificateFactory.getInstance("X.509").generateCertificate(it) as X509Certificate? + ) +} +---- +==== + +Let's say that the asserting party is going to also encrypt the assertion. +In that case, the relying party will need a private key to be able to decrypt the encrypted value. + +In that case, you'll need an `RSAPrivateKey` as well as its corresponding `X509Certificate`. +You can load the first using Spring Security's `RsaKeyConverters` utility class and the second as you did before: + +==== +.Java +[source,java,role="primary"] +---- +X509Certificate certificate = relyingPartyDecryptionCertificate(); +Resource resource = new ClassPathResource("rp.crt"); +try (InputStream is = resource.getInputStream()) { + RSAPrivateKey rsa = RsaKeyConverters.pkcs8().convert(is); + return Saml2X509Credential.decryption(rsa, certificate); +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val certificate: X509Certificate = relyingPartyDecryptionCertificate() +val resource = ClassPathResource("rp.crt") +resource.inputStream.use { + val rsa: RSAPrivateKey = RsaKeyConverters.pkcs8().convert(it) + return Saml2X509Credential.decryption(rsa, certificate) +} +---- +==== + +[TIP] +When you specify the locations of these files as the appropriate Spring Boot properties, then Spring Boot will perform these conversions for you. + +[[servlet-saml2login-rpr-relyingpartyregistrationresolver]] +==== Resolving the Relying Party from the Request + +As seen so far, Spring Security resolves the `RelyingPartyRegistration` by looking for the registration id in the URI path. + +There are a number of reasons you may want to customize. Among them: + +* You may know that you will never be a multi-tenant application and so want to have a simpler URL scheme +* You may identify tenants in a way other than by the URI path + +To customize the way that a `RelyingPartyRegistration` is resolved, you can configure a custom `Converter`. +The default looks up the registration id from the URI's last path element and looks it up in your `RelyingPartyRegistrationRepository`. + +You can provide a simpler resolver that, for example, always returns the same relying party: + +==== +.Java +[source,java,role="primary"] +---- +public class SingleRelyingPartyRegistrationResolver + implements Converter { + + @Override + public RelyingPartyRegistration convert(HttpServletRequest request) { + return this.relyingParty; + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +class SingleRelyingPartyRegistrationResolver : Converter { + override fun convert(request: HttpServletRequest?): RelyingPartyRegistration? { + return this.relyingParty + } +} +---- +==== + +Then, you can provide this resolver to the appropriate filters that <` s>>, <` s>>, and <` metadata>>. + +[NOTE] +Remember that if you have any placeholders in your `RelyingPartyRegistration`, your resolver implementation should resolve them. + +[[servlet-saml2login-rpr-duplicated]] +==== Duplicated Relying Party Configurations + +When an application uses multiple asserting parties, some configuration is duplicated between `RelyingPartyRegistration` instances: + +* The relying party's `entityId` +* Its `assertionConsumerServiceLocation`, and +* Its credentials, for example its signing or decryption credentials + +What's nice about this setup is credentials may be more easily rotated for some identity providers vs others. + +The duplication can be alleviated in a few different ways. + +First, in YAML this can be alleviated with references, like so: + +[source,yaml] +---- +spring: + security: + saml2: + relyingparty: + okta: + signing.credentials: &relying-party-credentials + - private-key-location: classpath:rp.key + - certificate-location: classpath:rp.crt + identityprovider: + entity-id: ... + azure: + signing.credentials: *relying-party-credentials + identityprovider: + entity-id: ... +---- + +Second, in a database, it's not necessary to replicate `RelyingPartyRegistration` 's model. + +Third, in Java, you can create a custom configuration method, like so: + +==== +.Java +[source,java,role="primary"] +---- +private RelyingPartyRegistration.Builder + addRelyingPartyDetails(RelyingPartyRegistration.Builder builder) { + + Saml2X509Credential signingCredential = ... + builder.signingX509Credentials(c -> c.addAll(signingCredential)); + // ... other relying party configurations +} + +@Bean +public RelyingPartyRegistrationRepository relyingPartyRegistrations() { + RelyingPartyRegistration okta = addRelyingPartyDetails( + RelyingPartyRegistrations + .fromMetadataLocation(oktaMetadataUrl) + .registrationId("okta")).build(); + + RelyingPartyRegistration azure = addRelyingPartyDetails( + RelyingPartyRegistrations + .fromMetadataLocation(oktaMetadataUrl) + .registrationId("azure")).build(); + + return new InMemoryRelyingPartyRegistrationRepository(okta, azure); +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +private fun addRelyingPartyDetails(builder: RelyingPartyRegistration.Builder): RelyingPartyRegistration.Builder { + val signingCredential: Saml2X509Credential = ... + builder.signingX509Credentials { c: MutableCollection -> + c.add( + signingCredential + ) + } + // ... other relying party configurations +} + +@Bean +open fun relyingPartyRegistrations(): RelyingPartyRegistrationRepository? { + val okta = addRelyingPartyDetails( + RelyingPartyRegistrations + .fromMetadataLocation(oktaMetadataUrl) + .registrationId("okta") + ).build() + val azure = addRelyingPartyDetails( + RelyingPartyRegistrations + .fromMetadataLocation(oktaMetadataUrl) + .registrationId("azure") + ).build() + return InMemoryRelyingPartyRegistrationRepository(okta, azure) +} +---- +==== + +[[servlet-saml2login-sp-initiated-factory]] +=== Producing `` s + +As stated earlier, Spring Security's SAML 2.0 support produces a `` to commence authentication with the asserting party. + +Spring Security achieves this in part by registering the `Saml2WebSsoAuthenticationRequestFilter` in the filter chain. +This filter by default responds to endpoint `+/saml2/authenticate/{registrationId}+`. + +For example, if you were deployed to `https://rp.example.com` and you gave your registration an ID of `okta`, you could navigate to: + +`https://rp.example.org/saml2/authenticate/ping` + +and the result would be a redirect that included a `SAMLRequest` parameter containing the signed, deflated, and encoded ``. + +[[servlet-saml2login-sp-initiated-factory-signing]] +==== Changing How the `` Gets Sent + +By default, Spring Security signs each `` and send it as a GET to the asserting party. + +Many asserting parties don't require a signed ``. +This can be configured automatically via `RelyingPartyRegistrations`, or you can supply it manually, like so: + + +.Not Requiring Signed AuthnRequests +==== +.Boot +[source,yaml,role="primary"] +---- +spring: + security: + saml2: + relyingparty: + okta: + identityprovider: + entity-id: ... + singlesignon.sign-request: false +---- + +.Java +[source,java,role="secondary"] +---- +RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistration.withRegistrationId("okta") + // ... + .assertingPartyDetails(party -> party + // ... + .wantAuthnRequestsSigned(false) + ) + .build(); +---- + +.Kotlin +[source,java,role="secondary"] +---- +var relyingPartyRegistration: RelyingPartyRegistration = + RelyingPartyRegistration.withRegistrationId("okta") + // ... + .assertingPartyDetails { party: AssertingPartyDetails.Builder -> party + // ... + .wantAuthnRequestsSigned(false) + } + .build(); +---- +==== + +Otherwise, you will need to specify a private key to `RelyingPartyRegistration#signingX509Credentials` so that Spring Security can sign the `` before sending. + +[[servlet-saml2login-sp-initiated-factory-algorithm]] +By default, Spring Security will sign the `` using `rsa-sha256`, though some asserting parties will require a different algorithm, as indicated in their metadata. + +You can configure the algorithm based on the asserting party's <>. + +Or, you can provide it manually: + +==== +.Java +[source,java,role="primary"] +---- +String metadataLocation = "classpath:asserting-party-metadata.xml"; +RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistrations.fromMetadataLocation(metadataLocation) + // ... + .assertingPartyDetails((party) -> party + // ... + .signingAlgorithms((sign) -> sign.add(SignatureConstants.ALGO_ID_SIGNATURE_RSA_SHA512)) + ) + .build(); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +var metadataLocation = "classpath:asserting-party-metadata.xml" +var relyingPartyRegistration: RelyingPartyRegistration = + RelyingPartyRegistrations.fromMetadataLocation(metadataLocation) + // ... + .assertingPartyDetails { party: AssertingPartyDetails.Builder -> party + // ... + .signingAlgorithms { sign: MutableList -> + sign.add( + SignatureConstants.ALGO_ID_SIGNATURE_RSA_SHA512 + ) + } + } + .build(); +---- +==== + +NOTE: The snippet above uses the OpenSAML `SignatureConstants` class to supply the algorithm name. +But, that's just for convenience. +Since the datatype is `String`, you can supply the name of the algorithm directly. + +[[servlet-saml2login-sp-initiated-factory-binding]] +Some asserting parties require that the `` be POSTed. +This can be configured automatically via `RelyingPartyRegistrations`, or you can supply it manually, like so: + +==== +.Java +[source,java,role="primary"] +---- +RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistration.withRegistrationId("okta") + // ... + .assertingPartyDetails(party -> party + // ... + .singleSignOnServiceBinding(Saml2MessageBinding.POST) + ) + .build(); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +var relyingPartyRegistration: RelyingPartyRegistration? = + RelyingPartyRegistration.withRegistrationId("okta") + // ... + .assertingPartyDetails { party: AssertingPartyDetails.Builder -> party + // ... + .singleSignOnServiceBinding(Saml2MessageBinding.POST) + } + .build() +---- +==== + +[[servlet-saml2login-sp-initiated-factory-custom-authnrequest]] +==== Customizing OpenSAML's `AuthnRequest` Instance + +There are a number of reasons that you may want to adjust an `AuthnRequest`. +For example, you may want `ForceAuthN` to be set to `true`, which Spring Security sets to `false` by default. + +If you don't need information from the `HttpServletRequest` to make your decision, then the easiest way is to <>. +This will give you access to post-process the `AuthnRequest` instance before it's serialized. + +But, if you do need something from the request, then you can use create a custom `Saml2AuthenticationRequestContext` implementation and then a `Converter` to build an `AuthnRequest` yourself, like so: + +==== +.Java +[source,java,role="primary"] +---- +@Component +public class AuthnRequestConverter implements + Converter { + + private final AuthnRequestBuilder authnRequestBuilder; + private final IssuerBuilder issuerBuilder; + + // ... constructor + + public AuthnRequest convert(Saml2AuthenticationRequestContext context) { + MySaml2AuthenticationRequestContext myContext = (MySaml2AuthenticationRequestContext) context; + Issuer issuer = issuerBuilder.buildObject(); + issuer.setValue(myContext.getIssuer()); + + AuthnRequest authnRequest = authnRequestBuilder.buildObject(); + authnRequest.setIssuer(issuer); + authnRequest.setDestination(myContext.getDestination()); + authnRequest.setAssertionConsumerServiceURL(myContext.getAssertionConsumerServiceUrl()); + + // ... additional settings + + authRequest.setForceAuthn(myContext.getForceAuthn()); + return authnRequest; + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@Component +class AuthnRequestConverter : Converter { + private val authnRequestBuilder: AuthnRequestBuilder? = null + private val issuerBuilder: IssuerBuilder? = null + + // ... constructor + override fun convert(context: MySaml2AuthenticationRequestContext): AuthnRequest { + val myContext: MySaml2AuthenticationRequestContext = context + val issuer: Issuer = issuerBuilder.buildObject() + issuer.value = myContext.getIssuer() + val authnRequest: AuthnRequest = authnRequestBuilder.buildObject() + authnRequest.issuer = issuer + authnRequest.destination = myContext.getDestination() + authnRequest.assertionConsumerServiceURL = myContext.getAssertionConsumerServiceUrl() + + // ... additional settings + authRequest.setForceAuthn(myContext.getForceAuthn()) + return authnRequest + } +} +---- +==== + +Then, you can construct your own `Saml2AuthenticationRequestContextResolver` and `Saml2AuthenticationRequestFactory` and publish them as `@Bean` s: + +==== +.Java +[source,java,role="primary"] +---- +@Bean +Saml2AuthenticationRequestContextResolver authenticationRequestContextResolver() { + Saml2AuthenticationRequestContextResolver resolver = + new DefaultSaml2AuthenticationRequestContextResolver(); + return request -> { + Saml2AuthenticationRequestContext context = resolver.resolve(request); + return new MySaml2AuthenticationRequestContext(context, request.getParameter("force") != null); + }; +} + +@Bean +Saml2AuthenticationRequestFactory authenticationRequestFactory( + AuthnRequestConverter authnRequestConverter) { + + OpenSaml4AuthenticationRequestFactory authenticationRequestFactory = + new OpenSaml4AuthenticationRequestFactory(); + authenticationRequestFactory.setAuthenticationRequestContextConverter(authnRequestConverter); + return authenticationRequestFactory; +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@Bean +open fun authenticationRequestContextResolver(): Saml2AuthenticationRequestContextResolver { + val resolver: Saml2AuthenticationRequestContextResolver = DefaultSaml2AuthenticationRequestContextResolver() + return Saml2AuthenticationRequestContextResolver { request: HttpServletRequest -> + val context = resolver.resolve(request) + MySaml2AuthenticationRequestContext( + context, + request.getParameter("force") != null + ) + } +} + +@Bean +open fun authenticationRequestFactory( + authnRequestConverter: AuthnRequestConverter? +): Saml2AuthenticationRequestFactory? { + val authenticationRequestFactory = OpenSaml4AuthenticationRequestFactory() + authenticationRequestFactory.setAuthenticationRequestContextConverter(authnRequestConverter) + return authenticationRequestFactory +} +---- +==== + +[[servlet-saml2login-authenticate-responses]] +=== Authenticating `` s + +To verify SAML 2.0 Responses, Spring Security uses <> by default. + +You can configure this in a number of ways including: + +1. Setting a clock skew to timestamp validation +2. Mapping the response to a list of `GrantedAuthority` instances +3. Customizing the strategy for validating assertions +4. Customizing the strategy for decrypting response and assertion elements + +To configure these, you'll use the `saml2Login#authenticationManager` method in the DSL. + +[[servlet-saml2login-opensamlauthenticationprovider-clockskew]] +==== Setting a Clock Skew + +It's not uncommon for the asserting and relying parties to have system clocks that aren't perfectly synchronized. +For that reason, you can configure `OpenSaml4AuthenticationProvider` 's default assertion validator with some tolerance: + +==== +.Java +[source,java,role="primary"] +---- +@EnableWebSecurity +public class SecurityConfig extends WebSecurityConfigurerAdapter { + + @Override + protected void configure(HttpSecurity http) throws Exception { + OpenSaml4AuthenticationProvider authenticationProvider = new OpenSaml4AuthenticationProvider(); + authenticationProvider.setAssertionValidator(OpenSaml4AuthenticationProvider + .createDefaultAssertionValidator(assertionToken -> { + Map params = new HashMap<>(); + params.put(CLOCK_SKEW, Duration.ofMinutes(10).toMillis()); + // ... other validation parameters + return new ValidationContext(params); + }) + ); + + http + .authorizeRequests(authz -> authz + .anyRequest().authenticated() + ) + .saml2Login(saml2 -> saml2 + .authenticationManager(new ProviderManager(authenticationProvider)) + ); + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@EnableWebSecurity +open class SecurityConfig : WebSecurityConfigurerAdapter() { + override fun configure(http: HttpSecurity) { + val authenticationProvider = OpenSaml4AuthenticationProvider() + authenticationProvider.setAssertionValidator( + OpenSaml4AuthenticationProvider + .createDefaultAssertionValidator(Converter { + val params: MutableMap = HashMap() + params[CLOCK_SKEW] = + Duration.ofMinutes(10).toMillis() + ValidationContext(params) + }) + ) + http { + authorizeRequests { + authorize(anyRequest, authenticated) + } + saml2Login { + authenticationManager = ProviderManager(authenticationProvider) + } + } + } +} +---- +==== + +[[servlet-saml2login-opensamlauthenticationprovider-userdetailsservice]] +==== Coordinating with a `UserDetailsService` + +Or, perhaps you would like to include user details from a legacy `UserDetailsService`. +In that case, the response authentication converter can come in handy, as can be seen below: + +==== +.Java +[source,java,role="primary"] +---- +@EnableWebSecurity +public class SecurityConfig extends WebSecurityConfigurerAdapter { + @Autowired + UserDetailsService userDetailsService; + + @Override + protected void configure(HttpSecurity http) throws Exception { + OpenSaml4AuthenticationProvider authenticationProvider = new OpenSaml4AuthenticationProvider(); + authenticationProvider.setResponseAuthenticationConverter(responseToken -> { + Saml2Authentication authentication = OpenSaml4AuthenticationProvider + .createDefaultResponseAuthenticationConverter() <1> + .convert(responseToken); + Assertion assertion = responseToken.getResponse().getAssertions().get(0); + String username = assertion.getSubject().getNameID().getValue(); + UserDetails userDetails = this.userDetailsService.loadUserByUsername(username); <2> + return MySaml2Authentication(userDetails, authentication); <3> + }); + + http + .authorizeRequests(authz -> authz + .anyRequest().authenticated() + ) + .saml2Login(saml2 -> saml2 + .authenticationManager(new ProviderManager(authenticationProvider)) + ); + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@EnableWebSecurity +open class SecurityConfig : WebSecurityConfigurerAdapter() { + @Autowired + var userDetailsService: UserDetailsService? = null + + override fun configure(http: HttpSecurity) { + val authenticationProvider = OpenSaml4AuthenticationProvider() + authenticationProvider.setResponseAuthenticationConverter { responseToken: OpenSaml4AuthenticationProvider.ResponseToken -> + val authentication = OpenSaml4AuthenticationProvider + .createDefaultResponseAuthenticationConverter() <1> + .convert(responseToken) + val assertion: Assertion = responseToken.response.assertions[0] + val username: String = assertion.subject.nameID.value + val userDetails = userDetailsService!!.loadUserByUsername(username) <2> + MySaml2Authentication(userDetails, authentication) <3> + } + http { + authorizeRequests { + authorize(anyRequest, authenticated) + } + saml2Login { + authenticationManager = ProviderManager(authenticationProvider) + } + } + } +} +---- +==== +<1> First, call the default converter, which extracts attributes and authorities from the response +<2> Second, call the <> using the relevant information +<3> Third, return a custom authentication that includes the user details + +[NOTE] +It's not required to call `OpenSaml4AuthenticationProvider` 's default authentication converter. +It returns a `Saml2AuthenticatedPrincipal` containing the attributes it extracted from `AttributeStatement` s as well as the single `ROLE_USER` authority. + +[[servlet-saml2login-opensamlauthenticationprovider-additionalvalidation]] +==== Performing Additional Response Validation + +`OpenSaml4AuthenticationProvider` validates the `Issuer` and `Destination` values right after decrypting the `Response`. +You can customize the validation by extending the default validator concatenating with your own response validator, or you can replace it entirely with yours. + +For example, you can throw a custom exception with any additional information available in the `Response` object, like so: +[source,java] +---- +OpenSaml4AuthenticationProvider provider = new OpenSaml4AuthenticationProvider(); +provider.setResponseValidator((responseToken) -> { + Saml2ResponseValidatorResult result = OpenSamlAuthenticationProvider + .createDefaultResponseValidator() + .convert(responseToken) + .concat(myCustomValidator.convert(responseToken)); + if (!result.getErrors().isEmpty()) { + String inResponseTo = responseToken.getInResponseTo(); + throw new CustomSaml2AuthenticationException(result, inResponseTo); + } + return result; +}); +---- + +==== Performing Additional Assertion Validation +`OpenSaml4AuthenticationProvider` performs minimal validation on SAML 2.0 Assertions. +After verifying the signature, it will: + +1. Validate `` and `` conditions +2. Validate `` s, expect for any IP address information + +To perform additional validation, you can configure your own assertion validator that delegates to `OpenSaml4AuthenticationProvider` 's default and then performs its own. + +[[servlet-saml2login-opensamlauthenticationprovider-onetimeuse]] +For example, you can use OpenSAML's `OneTimeUseConditionValidator` to also validate a `` condition, like so: + +==== +.Java +[source,java,role="primary"] +---- +OpenSaml4AuthenticationProvider provider = new OpenSaml4AuthenticationProvider(); +OneTimeUseConditionValidator validator = ...; +provider.setAssertionValidator(assertionToken -> { + Saml2ResponseValidatorResult result = OpenSaml4AuthenticationProvider + .createDefaultAssertionValidator() + .convert(assertionToken); + Assertion assertion = assertionToken.getAssertion(); + OneTimeUse oneTimeUse = assertion.getConditions().getOneTimeUse(); + ValidationContext context = new ValidationContext(); + try { + if (validator.validate(oneTimeUse, assertion, context) == ValidationResult.VALID) { + return result; + } + } catch (Exception e) { + return result.concat(new Saml2Error(INVALID_ASSERTION, e.getMessage())); + } + return result.concat(new Saml2Error(INVALID_ASSERTION, context.getValidationFailureMessage())); +}); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +var provider = OpenSaml4AuthenticationProvider() +var validator: OneTimeUseConditionValidator = ... +provider.setAssertionValidator { assertionToken -> + val result = OpenSaml4AuthenticationProvider + .createDefaultAssertionValidator() + .convert(assertionToken) + val assertion: Assertion = assertionToken.assertion + val oneTimeUse: OneTimeUse = assertion.conditions.oneTimeUse + val context = ValidationContext() + try { + if (validator.validate(oneTimeUse, assertion, context) == ValidationResult.VALID) { + return@setAssertionValidator result + } + } catch (e: Exception) { + return@setAssertionValidator result.concat(Saml2Error(INVALID_ASSERTION, e.message)) + } + result.concat(Saml2Error(INVALID_ASSERTION, context.validationFailureMessage)) +} +---- +==== + +[NOTE] +While recommended, it's not necessary to call `OpenSaml4AuthenticationProvider` 's default assertion validator. +A circumstance where you would skip it would be if you don't need it to check the `` or the `` since you are doing those yourself. + +[[servlet-saml2login-opensamlauthenticationprovider-decryption]] +==== Customizing Decryption + +Spring Security decrypts ``, ``, and `` elements automatically by using the decryption <> registered in the <>. + +`OpenSaml4AuthenticationProvider` exposes <>. +The response decrypter is for decrypting encrypted elements of the ``, like ``. +The assertion decrypter is for decrypting encrypted elements of the ``, like `` and ``. + +You can replace `OpenSaml4AuthenticationProvider`'s default decryption strategy with your own. +For example, if you have a separate service that decrypts the assertions in a ``, you can use it instead like so: + +==== +.Java +[source,java,role="primary"] +---- +MyDecryptionService decryptionService = ...; +OpenSaml4AuthenticationProvider provider = new OpenSaml4AuthenticationProvider(); +provider.setResponseElementsDecrypter((responseToken) -> decryptionService.decrypt(responseToken.getResponse())); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val decryptionService: MyDecryptionService = ... +val provider = OpenSaml4AuthenticationProvider() +provider.setResponseElementsDecrypter { responseToken -> decryptionService.decrypt(responseToken.response) } +---- +==== + +If you are also decrypting individual elements in a ``, you can customize the assertion decrypter, too: + +==== +.Java +[source,java,role="primary"] +---- +provider.setAssertionElementsDecrypter((assertionToken) -> decryptionService.decrypt(assertionToken.getAssertion())); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +provider.setAssertionElementsDecrypter { assertionToken -> decryptionService.decrypt(assertionToken.assertion) } +---- +==== + +NOTE: There are two separate decrypters since assertions can be signed separately from responses. +Trying to decrypt a signed assertion's elements before signature verification may invalidate the signature. +If your asserting party signs the response only, then it's safe to decrypt all elements using only the response decrypter. + +[[servlet-saml2login-authenticationmanager-custom]] +==== Using a Custom Authentication Manager + +[[servlet-saml2login-opensamlauthenticationprovider-authenticationmanager]] +Of course, the `authenticationManager` DSL method can be also used to perform a completely custom SAML 2.0 authentication. +This authentication manager should expect a `Saml2AuthenticationToken` object containing the SAML 2.0 Response XML data. + +==== +.Java +[source,java,role="primary"] +---- +@EnableWebSecurity +public class SecurityConfig extends WebSecurityConfigurerAdapter { + + @Override + protected void configure(HttpSecurity http) throws Exception { + AuthenticationManager authenticationManager = new MySaml2AuthenticationManager(...); + http + .authorizeRequests(authorize -> authorize + .anyRequest().authenticated() + ) + .saml2Login(saml2 -> saml2 + .authenticationManager(authenticationManager) + ) + ; + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@EnableWebSecurity +open class SecurityConfig : WebSecurityConfigurerAdapter() { + override fun configure(http: HttpSecurity) { + val customAuthenticationManager: AuthenticationManager = MySaml2AuthenticationManager(...) + http { + authorizeRequests { + authorize(anyRequest, authenticated) + } + saml2Login { + authenticationManager = customAuthenticationManager + } + } + } +} +---- +==== + +[[servlet-saml2login-authenticatedprincipal]] +=== Using `Saml2AuthenticatedPrincipal` + +With the relying party correctly configured for a given asserting party, it's ready to accept assertions. +Once the relying party validates an assertion, the result is a `Saml2Authentication` with a `Saml2AuthenticatedPrincipal`. + +This means that you can access the principal in your controller like so: + +==== +.Java +[source,java,role="primary"] +---- +@Controller +public class MainController { + @GetMapping("/") + public String index(@AuthenticationPrincipal Saml2AuthenticatedPrincipal principal, Model model) { + String email = principal.getFirstAttribute("email"); + model.setAttribute("email", email); + return "index"; + } +} +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@Controller +class MainController { + @GetMapping("/") + fun index(@AuthenticationPrincipal principal: Saml2AuthenticatedPrincipal, model: Model): String { + val email = principal.getFirstAttribute("email") + model.setAttribute("email", email) + return "index" + } +} +---- +==== + +[TIP] +Because the SAML 2.0 specification allows for each attribute to have multiple values, you can either call `getAttribute` to get the list of attributes or `getFirstAttribute` to get the first in the list. +`getFirstAttribute` is quite handy when you know that there is only one value. + +[[servlet-saml2login-metadata]] +=== Producing `` Metadata + +You can publish a metadata endpoint by adding the `Saml2MetadataFilter` to the filter chain, as you'll see below: + +==== +.Java +[source,java,role="primary"] +---- +Converter relyingPartyRegistrationResolver = + new DefaultRelyingPartyRegistrationResolver(this.relyingPartyRegistrationRepository); +Saml2MetadataFilter filter = new Saml2MetadataFilter( + relyingPartyRegistrationResolver, + new OpenSamlMetadataResolver()); + +http + // ... + .saml2Login(withDefaults()) + .addFilterBefore(filter, Saml2WebSsoAuthenticationFilter.class); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val relyingPartyRegistrationResolver: Converter = + DefaultRelyingPartyRegistrationResolver(this.relyingPartyRegistrationRepository) +val filter = Saml2MetadataFilter( + relyingPartyRegistrationResolver, + OpenSamlMetadataResolver() +) + +http { + //... + saml2Login { } + addFilterBefore(filter) +} +---- +==== + +You can use this metadata endpoint to register your relying party with your asserting party. +This is often as simple as finding the correct form field to supply the metadata endpoint. + +By default, the metadata endpoint is `+/saml2/service-provider-metadata/{registrationId}+`. +You can change this by calling the `setRequestMatcher` method on the filter: + +==== +.Java +[source,java,role="primary"] +---- +filter.setRequestMatcher(new AntPathRequestMatcher("/saml2/metadata/{registrationId}", "GET")); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +filter.setRequestMatcher(AntPathRequestMatcher("/saml2/metadata/{registrationId}", "GET")) +---- +==== + +ensuring that the `registrationId` hint is at the end of the path. + +Or, if you have registered a custom relying party registration resolver in the constructor, then you can specify a path without a `registrationId` hint, like so: + +==== +.Java +[source,java,role="primary"] +---- +filter.setRequestMatcher(new AntPathRequestMatcher("/saml2/metadata", "GET")); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +filter.setRequestMatcher(AntPathRequestMatcher("/saml2/metadata", "GET")) +---- +==== + +[[servlet-saml2login-logout]] +=== Performing Single Logout + +Spring Security does not yet support single logout. + +Generally speaking, though, you can achieve this by creating and registering a custom `LogoutSuccessHandler` and `RequestMatcher`: + +==== +.Java +[source,java,role="primary"] +---- +http + // ... + .logout(logout -> logout + .logoutSuccessHandler(myCustomSuccessHandler()) + .logoutRequestMatcher(myRequestMatcher()) + ) +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +http { + logout { + // ... + logoutSuccessHandler = myCustomSuccessHandler() + logoutRequestMatcher = myRequestMatcher() + } +} +---- +==== + +The success handler will send logout requests to the asserting party. + +The request matcher will detect logout requests from the asserting party. + diff --git a/docs/modules/ROOT/pages/servlet/test/method.adoc b/docs/modules/ROOT/pages/servlet/test/method.adoc index 82a2f9ceb9..e5e639464e 100644 --- a/docs/modules/ROOT/pages/servlet/test/method.adoc +++ b/docs/modules/ROOT/pages/servlet/test/method.adoc @@ -1,5 +1,5 @@ [[test-method]] -== Testing Method Security += Testing Method Security This section demonstrates how to use Spring Security's Test support to test method based security. We first introduce a `MessageService` that requires the user to be authenticated in order to access it. @@ -41,7 +41,7 @@ Hello org.springframework.security.authentication.UsernamePasswordAuthentication ---- [[test-method-setup]] -=== Security Test Setup +== Security Test Setup Before we can use Spring Security Test support, we must perform some setup. An example can be seen below: @@ -98,7 +98,7 @@ fun getMessageUnauthenticated() { ==== [[test-method-withmockuser]] -=== @WithMockUser +== @WithMockUser The question is "How could we most easily run the test as a specific user?" The answer is to use `@WithMockUser`. @@ -294,7 +294,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut [[test-method-withanonymoususer]] -=== @WithAnonymousUser +== @WithAnonymousUser Using `@WithAnonymousUser` allows running as an anonymous user. This is especially convenient when you wish to run most of your tests with a specific user, but want to run a few tests as an anonymous user. @@ -358,7 +358,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut [[test-method-withuserdetails]] -=== @WithUserDetails +== @WithUserDetails While `@WithMockUser` is a very convenient way to get started, it may not work in all instances. For example, it is common for applications to expect that the `Authentication` principal be of a specific type. @@ -462,7 +462,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut [[test-method-withsecuritycontext]] -=== @WithSecurityContext +== @WithSecurityContext We have seen that `@WithMockUser` is an excellent choice if we are not using a custom `Authentication` principal. Next we discovered that `@WithUserDetails` would allow us to use a custom `UserDetailsService` to create our `Authentication` principal but required the user to exist. @@ -596,7 +596,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut [[test-method-meta-annotations]] -=== Test Meta Annotations +== Test Meta Annotations If you reuse the same user within your tests often, it is not ideal to have to repeatedly specify the attributes. For example, if there are many tests related to an administrative user with the username "admin" and the roles `ROLE_USER` and `ROLE_ADMIN` you would have to write: diff --git a/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc b/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc index f28c866ae0..5a58d3118d 100644 --- a/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc +++ b/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc @@ -1,10 +1,10 @@ [[test-mockmvc]] -== Spring MVC Test Integration += Spring MVC Test Integration Spring Security provides comprehensive integration with https://docs.spring.io/spring/docs/current/spring-framework-reference/html/testing.html#spring-mvc-test-framework[Spring MVC Test] [[test-mockmvc-setup]] -=== Setting Up MockMvc and Spring Security +== Setting Up MockMvc and Spring Security In order to use Spring Security with Spring MVC Test it is necessary to add the Spring Security `FilterChainProxy` as a `Filter`. It is also necessary to add Spring Security's `TestSecurityContextHolderPostProcessor` to support <>. @@ -68,7 +68,7 @@ class CsrfShowcaseTests { <1> `SecurityMockMvcConfigurers.springSecurity()` will perform all of the initial setup we need to integrate Spring Security with Spring MVC Test [[test-mockmvc-smmrpp]] -=== SecurityMockMvcRequestPostProcessors +== SecurityMockMvcRequestPostProcessors Spring MVC Test provides a convenient interface called a `RequestPostProcessor` that can be used to modify a request. Spring Security provides a number of `RequestPostProcessor` implementations that make testing easier. @@ -89,7 +89,7 @@ import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequ ==== [[test-mockmvc-csrf]] -==== Testing with CSRF Protection +=== Testing with CSRF Protection When testing any non-safe HTTP methods and using Spring Security's CSRF protection, you must be sure to include a valid CSRF Token in the request. To specify a valid CSRF token as a request parameter using the following: @@ -150,7 +150,7 @@ mvc.post("/") { ==== [[test-mockmvc-securitycontextholder]] -==== Running a Test as a User in Spring MVC Test +=== Running a Test as a User in Spring MVC Test It is often desirable to run tests as a specific user. There are two simple ways of populating the user: @@ -159,7 +159,7 @@ There are two simple ways of populating the user: * <> [[test-mockmvc-securitycontextholder-rpp]] -==== Running as a User in Spring MVC Test with RequestPostProcessor +=== Running as a User in Spring MVC Test with RequestPostProcessor There are a number of options available to associate a user to the current `HttpServletRequest`. For example, the following will run as a user (which does not need to exist) with the username "user", the password "password", and the role "ROLE_USER": @@ -364,7 +364,7 @@ mvc.get("/") { ---- ==== -===== Running as a User in Spring MVC Test with Annotations +==== Running as a User in Spring MVC Test with Annotations As an alternative to using a `RequestPostProcessor` to create your user, you can use annotations described in <>. For example, the following will run the test with the user with username "user", password "password", and role "ROLE_USER": @@ -423,7 +423,7 @@ fun requestProtectedUrlWithUser() { ---- ==== -==== Testing HTTP Basic Authentication +=== Testing HTTP Basic Authentication While it has always been possible to authenticate with HTTP Basic, it was a bit tedious to remember the header name, format, and encode the values. Now this can be done using Spring Security's `httpBasic` `RequestPostProcessor`. @@ -454,7 +454,7 @@ Authorization: Basic dXNlcjpwYXNzd29yZA== ---- [[testing-oauth2]] -==== Testing OAuth 2.0 +=== Testing OAuth 2.0 When it comes to OAuth 2.0, the same principles covered earlier still apply: Ultimately, it depends on what your method under test is expecting to be in the `SecurityContextHolder`. @@ -507,7 +507,7 @@ fun foo(@AuthenticationPrincipal user: OidcUser): String { then Spring Security's test support can come in handy. [[testing-oidc-login]] -==== Testing OIDC Login +=== Testing OIDC Login Testing the method above with Spring MVC Test would require simulating some kind of grant flow with an authorization server. Certainly this would be a daunting task, which is why Spring Security ships with support for removing this boilerplate. @@ -589,7 +589,7 @@ Further, it also links that `OidcUser` to a simple instance of `OAuth2Authorized This can be handy if your tests <>.. [[testing-oidc-login-authorities]] -===== Configuring Authorities +==== Configuring Authorities In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request. @@ -619,7 +619,7 @@ mvc.get("/endpoint") { ==== [[testing-oidc-login-claims]] -===== Configuring Claims +==== Configuring Claims And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0. @@ -678,7 +678,7 @@ mvc.get("/endpoint") { since `OidcUser` collects its claims from `OidcIdToken`. [[testing-oidc-login-user]] -===== Additional Configurations +==== Additional Configurations There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects: @@ -724,7 +724,7 @@ mvc.get("/endpoint") { ==== [[testing-oauth2-login]] -==== Testing OAuth 2.0 Login +=== Testing OAuth 2.0 Login As with <>, testing OAuth 2.0 Login presents a similar challenge of mocking a grant flow. And because of that, Spring Security also has test support for non-OIDC use cases. @@ -812,7 +812,7 @@ Further, it also links that `OAuth2User` to a simple instance of `OAuth2Authoriz This can be handy if your tests <>. [[testing-oauth2-login-authorities]] -===== Configuring Authorities +==== Configuring Authorities In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request. @@ -842,7 +842,7 @@ mvc.get("/endpoint") { ==== [[testing-oauth2-login-claims]] -===== Configuring Claims +==== Configuring Claims And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0. @@ -897,7 +897,7 @@ mvc.get("/endpoint") { ==== [[testing-oauth2-login-user]] -===== Additional Configurations +==== Additional Configurations There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects: @@ -942,7 +942,7 @@ mvc.get("/endpoint") { ==== [[testing-oauth2-client]] -==== Testing OAuth 2.0 Clients +=== Testing OAuth 2.0 Clients Independent of how your user authenticates, you may have other tokens and client registrations that are in play for the request you are testing. For example, your controller may be relying on the client credentials grant to get a token that isn't associated with the user at all: @@ -1054,7 +1054,7 @@ assertThat(authorizedClient.accessToken.scopes).containsExactly("read") The client can then be retrieved as normal using `@RegisteredOAuth2AuthorizedClient` in a controller method. [[testing-oauth2-client-scopes]] -===== Configuring Scopes +==== Configuring Scopes In many circumstances, the OAuth 2.0 access token comes with a set of scopes. If your controller inspects these, say like so: @@ -1121,7 +1121,7 @@ mvc.get("/endpoint") { ==== [[testing-oauth2-client-registration]] -===== Additional Configurations +==== Additional Configurations There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects: @@ -1167,7 +1167,7 @@ mvc.get("/endpoint") { ==== [[testing-jwt]] -==== Testing JWT Authentication +=== Testing JWT Authentication In order to make an authorized request on a resource server, you need a bearer token. @@ -1177,7 +1177,7 @@ All of this can be quite daunting, especially when this isn't the focus of your Fortunately, there are a number of simple ways that you can overcome this difficulty and allow your tests to focus on authorization and not on representing bearer tokens. We'll look at two of them now: -===== `jwt() RequestPostProcessor` +==== `jwt() RequestPostProcessor` The first way is via a `RequestPostProcessor`. The simplest of these would look something like this: @@ -1357,7 +1357,7 @@ mvc.get("/endpoint") { ---- ==== -===== `authentication()` `RequestPostProcessor` +==== `authentication()` `RequestPostProcessor` The second way is by using the `authentication()` `RequestPostProcessor`. Essentially, you can instantiate your own `JwtAuthenticationToken` and provide it in your test, like so: @@ -1399,7 +1399,7 @@ mvc.get("/endpoint") { Note that as an alternative to these, you can also mock the `JwtDecoder` bean itself with a `@MockBean` annotation. [[testing-opaque-token]] -==== Testing Opaque Token Authentication +=== Testing Opaque Token Authentication Similar to <>, opaque tokens require an authorization server in order to verify their validity, which can make testing more difficult. To help with that, Spring Security has test support for opaque tokens. @@ -1484,7 +1484,7 @@ assertThat(token.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read Spring Security does the necessary work to make sure that the `BearerTokenAuthentication` instance is available for your controller methods. [[testing-opaque-token-authorities]] -===== Configuring Authorities +==== Configuring Authorities In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request. @@ -1514,7 +1514,7 @@ mvc.get("/endpoint") { ==== [[testing-opaque-token-attributes]] -===== Configuring Claims +==== Configuring Claims And while granted authorities are quite common across all of Spring Security, we also have attributes in the case of OAuth 2.0. @@ -1569,7 +1569,7 @@ mvc.get("/endpoint") { ==== [[testing-opaque-token-principal]] -===== Additional Configurations +==== Additional Configurations There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects. @@ -1616,7 +1616,7 @@ mvc.get("/endpoint") { Note that as an alternative to using `opaqueToken()` test support, you can also mock the `OpaqueTokenIntrospector` bean itself with a `@MockBean` annotation. -=== SecurityMockMvcRequestBuilders +== SecurityMockMvcRequestBuilders Spring MVC Test also provides a `RequestBuilder` interface that can be used to create the `MockHttpServletRequest` used in your test. Spring Security provides a few `RequestBuilder` implementations that can be used to make testing easier. @@ -1636,7 +1636,7 @@ import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequ ---- ==== -==== Testing Form Based Authentication +=== Testing Form Based Authentication You can easily create a request to test a form based authentication using Spring Security's testing support. For example, the following will submit a POST to "/login" with the username "user", the password "password", and a valid CSRF token: @@ -1696,7 +1696,7 @@ mvc ==== [[test-logout]] -==== Testing Logout +=== Testing Logout While fairly trivial using standard Spring MVC Test, you can use Spring Security's testing support to make testing log out easier. For example, the following will submit a POST to "/logout" with a valid CSRF token: @@ -1736,7 +1736,7 @@ mvc ---- ==== -=== SecurityMockMvcResultMatchers +== SecurityMockMvcResultMatchers At times it is desirable to make various security related assertions about a request. To accommodate this need, Spring Security Test support implements Spring MVC Test's `ResultMatcher` interface. @@ -1757,7 +1757,7 @@ import org.springframework.security.test.web.servlet.response.SecurityMockMvcRes ---- ==== -==== Unauthenticated Assertion +=== Unauthenticated Assertion At times it may be valuable to assert that there is no authenticated user associated with the result of a `MockMvc` invocation. For example, you might want to test submitting an invalid username and password and verify that no user is authenticated. @@ -1781,7 +1781,7 @@ mvc ---- ==== -==== Authenticated Assertion +=== Authenticated Assertion It is often times that we must assert that an authenticated user exists. For example, we may want to verify that we authenticated successfully.