Commit b4cef6cf authored by Gradl, Tobias's avatar Gradl, Tobias
Browse files

12: Compose some initial documentation

Task-Url: #12
parent be1c3e67
Pipeline #17893 passed with stage
in 1 minute and 53 seconds
## DARIAHSP - Sample boot app ## DARIAHSP - Sample boot app
This Spring Boot application serves as simple reference implementation of the [dariahsp-core](../dariashp-core) library. The sample is based on Java ServerPages (JSP) for view rendering and presents itself as an index page that provides important links to login, logout and protected areas. This Spring Boot application serves as simple reference implementation of the [dariahsp-core](../dariashp-core) library. The sample is based on Java ServerPages (JSP) for view rendering and presents itself with login, logout and protected areas.
> See the JavaDoc for further explanation on the components of the sample application > See the JavaDoc for further explanation on the components of the sample application
### Initialization ### Initialization
1. [`SampleApplication`](/src/main/java/eu/dariah/de/dariahsp/sample/SampleApplication.java) is the Spring Boot application class and handles initialization 1. [`SampleApplication`](/src/main/java/eu/dariah/de/dariahsp/sample/SampleApplication.java) is the Spring Boot application class and handles initialization
### Configuration ### Configuration
2. [`SampleConfig`](/src/main/java/eu/dariah/de/dariahsp/sample/SampleApplication.java) serves as primary application configuration class; it defines the beans of 2. [`SampleConfig`](/src/main/java/eu/dariah/de/dariahsp/sample/config/SampleApplication.java) serves as primary application configuration class; it defines the beans of
* `profileActionPostprocessor` for processing of login and logout activity, * `profileActionPostprocessor` (optional) for processing of login and logout activity,
* `samlMetadataController`, a controller bean that facilitates access to metadata of the SP and * `samlMetadataController`, a controller bean that facilitates access to metadata of the SP and
* `webServerFactoryCustomizer` for changing the context path of the application * `webServerFactoryCustomizer` for changing the context path of the application
3. [`SampleSecurityConfig`](/src/main/java/eu/dariah/de/dariahsp/sample/SampleApplication.java) - by extending the basic `SecurityConfig` class - imports the beans and configuration of the core library; it further imports configuration of the `AuthInfoConfigurer` class; The `@ConfigurationProperties(prefix = "auth")` annotation provides all configuration properties to the implemented `dariahsp-core` configuration
> With a optional custom implementation of the `profileActionPostprocessor`, the `SampleConfig` class can be used as a starting point for configuring futher aspects of the implementing application
3. [`SampleSecurityConfig`](/src/main/java/eu/dariah/de/dariahsp/sample/config/SampleSecurityConfig.java) - by extending the basic `SecurityConfig` class - imports the beans and configuration of the core library; it further imports configuration of the `AuthInfoConfigurer` class; The `@ConfigurationProperties(prefix = "auth")` annotation provides all configuration properties to the implemented `dariahsp-core` configuration
> The `SampleSecurityConfig` can be used 'as is' in other implementations as all security-related beans are soundly configured
4. [`SampleWebSecurityConfig`](/src/main/java/eu/dariah/de/dariahsp/sample/config/SampleWebSecurityConfig.java) is the basic `WebSecurityConfigurerAdapter` of the sample application and specifies URL and authorization patterns that are specific to the sample application
> The `SampleWebSecurityConfig` can be used as a starting point for configuring protected areas of the implementing application, but will probably require adaption to existing requirements
### Controllers
5. The [`SampleController`](/src/main/java/eu/dariah/de/dariahsp/sample/controller/SampleController.java) configures the request mappings and views of the sample application
6. [`ErrorController`](/src/main/java/eu/dariah/de/dariahsp/sample/controller/ErrorController.java) as implementation of Spring's `BasicErrorController` configures handling of exceptions that could occur in the application. For the sample application, all errors (e.g. 403 errors attempting to access protected areas) are dispatched to the `index` view, providing error messages
### Profile actions
7. [`SampleProfileActionHandler`](/src/main/java/eu/dariah/de/dariahsp/sample/profiles/SampleProfileActionHandler.java) is an empty implementation of the `ProfileActionHandler` interface - a bean provided that is setup in [`SampleConfig`](/src/main/java/eu/dariah/de/dariahsp/sample/config/SampleApplication.java). Customize behavior upon login and logout e.g. to persist user information in a database or to load save custom attributes of users and adding them to the attribute set of the handled `ExtendedUserProfile`
### Resources
8. [`application.yml`](/src/main/resources/application.yml) is a sample application configuration provided with this application
9. [`logback.xml`](/src/main/resources/application.yml) customizes logging through [logback](http://logback.qos.ch/)
10. [`sample_keystore.jks`](/src/main/resources/application.yml) is an example Java KeyStore that can be used for initial testing
### JSP views
11. [`index.jsp`](/src/main/webapp/WEB-INF/views/index.jsp) is the main view of the sample application that serves all succeeding and error requests.
12. [`login.jsp`](/src/main/webapp/WEB-INF/views/login.jsp) is the form for querying username and passwords of `local` logins.
\ No newline at end of file
...@@ -6,6 +6,7 @@ import org.springframework.context.annotation.Import; ...@@ -6,6 +6,7 @@ import org.springframework.context.annotation.Import;
import eu.dariah.de.dariahsp.config.SecurityConfig; import eu.dariah.de.dariahsp.config.SecurityConfig;
import eu.dariah.de.dariahsp.config.web.AuthInfoConfigurer; import eu.dariah.de.dariahsp.config.web.AuthInfoConfigurer;
import eu.dariah.de.dariahsp.web.AuthInfoHandlerInterceptor;
/** /**
* Main security configuration extends {@link SecurityConfig}. The auth namespace of the configuration properties * Main security configuration extends {@link SecurityConfig}. The auth namespace of the configuration properties
......
...@@ -9,9 +9,19 @@ import org.springframework.security.config.annotation.web.configuration.WebSecur ...@@ -9,9 +9,19 @@ import org.springframework.security.config.annotation.web.configuration.WebSecur
import eu.dariah.de.dariahsp.config.web.SecurityConfigurerAdapter; import eu.dariah.de.dariahsp.config.web.SecurityConfigurerAdapter;
import eu.dariah.de.dariahsp.config.web.DefaultFiltersConfigurerAdapter; import eu.dariah.de.dariahsp.config.web.DefaultFiltersConfigurerAdapter;
/**
* Web security configuration addressing protected areas and authorization patterns for this sample application
*
* @author Tobias Gradl
*/
@EnableWebSecurity @EnableWebSecurity
public class SampleWebSecurityConfig extends WebSecurityConfigurerAdapter { public class SampleWebSecurityConfig extends WebSecurityConfigurerAdapter {
/**
* Adapt this as required in a target application
*
* @author Tobias Gradl
*/
@Configuration @Configuration
@Order(1) @Order(1)
public static class WebSecurityConfigAdapter extends SecurityConfigurerAdapter { public static class WebSecurityConfigAdapter extends SecurityConfigurerAdapter {
...@@ -32,6 +42,11 @@ public class SampleWebSecurityConfig extends WebSecurityConfigurerAdapter { ...@@ -32,6 +42,11 @@ public class SampleWebSecurityConfig extends WebSecurityConfigurerAdapter {
} }
} }
/**
* Make sure to include this for logout, login and callback filters
*
* @author Tobias Gradl
*/
@Configuration @Configuration
@Order(2) @Order(2)
public static class CallbackLoginLogoutConfigurationAdapter extends DefaultFiltersConfigurerAdapter {} public static class CallbackLoginLogoutConfigurationAdapter extends DefaultFiltersConfigurerAdapter {}
......
...@@ -19,16 +19,30 @@ import org.springframework.web.servlet.ModelAndView; ...@@ -19,16 +19,30 @@ import org.springframework.web.servlet.ModelAndView;
import eu.dariah.de.dariahsp.config.SecurityConfig; import eu.dariah.de.dariahsp.config.SecurityConfig;
import eu.dariah.de.dariahsp.error.RequiredAttributesException; import eu.dariah.de.dariahsp.error.RequiredAttributesException;
/**
* Error controller for the sample application
*
* @author Tobias Gradl
*/
@Controller @Controller
@RequestMapping({"${server.error.path:${error.path:/error}}"}) @RequestMapping({"${server.error.path:${error.path:/error}}"})
public class ErrorController extends BasicErrorController { public class ErrorController extends BasicErrorController {
@Autowired private SecurityConfig securityConfig; @Autowired private SecurityConfig securityConfig;
/**
* Constructor with autowired ErrorAttributes
*
* @param errorAttributes
*/
@Autowired @Autowired
public ErrorController(ErrorAttributes errorAttributes) { public ErrorController(ErrorAttributes errorAttributes) {
super(errorAttributes, new ErrorProperties()); super(errorAttributes, new ErrorProperties());
} }
/**
* Error handling method dispatching all errors as messages to the default index view.
* Particular attention lies on the treatment of the {@link RequiredAttributesException}
*/
@Override @Override
@RequestMapping(produces = {"text/html"}) @RequestMapping(produces = {"text/html"})
public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) { public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
...@@ -57,7 +71,7 @@ public class ErrorController extends BasicErrorController { ...@@ -57,7 +71,7 @@ public class ErrorController extends BasicErrorController {
return new ModelAndView("index", attr); return new ModelAndView("index", attr);
} }
/* Do not do this in production as users should not see reasons openly */ /* Do not do this in production as users should not see all reasons openly */
@Override @Override
protected boolean isIncludeMessage(HttpServletRequest request, MediaType produces) { protected boolean isIncludeMessage(HttpServletRequest request, MediaType produces) {
return true; return true;
......
...@@ -19,6 +19,13 @@ import eu.dariah.de.dariahsp.config.SecurityConfig; ...@@ -19,6 +19,13 @@ import eu.dariah.de.dariahsp.config.SecurityConfig;
import eu.dariah.de.dariahsp.error.AuthenticatorNotAvailable; import eu.dariah.de.dariahsp.error.AuthenticatorNotAvailable;
import eu.dariah.de.dariahsp.web.AuthInfoHelper; import eu.dariah.de.dariahsp.web.AuthInfoHelper;
/**
* Main controller of the sample application. All views are handled in the index JSP.
* protectedMethod(-) handles security in a REST-oriented way with a @Secured annotation
*
* @author Tobias Gradl
*
*/
@Controller @Controller
public class SampleController { public class SampleController {
private static String INDEX_PAGE = "index"; private static String INDEX_PAGE = "index";
......
package eu.dariah.de.dariahsp.sample.profiles; package eu.dariah.de.dariahsp.sample.profiles;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import eu.dariah.de.dariahsp.ProfileActionHandler; import eu.dariah.de.dariahsp.ProfileActionHandler;
import eu.dariah.de.dariahsp.model.ExtendedUserProfile; import eu.dariah.de.dariahsp.model.ExtendedUserProfile;
import lombok.extern.slf4j.Slf4j;
@Slf4j /**
* Placeholder implementation of the {@link ProfileActionHandler} interface merely logging actions.
* Common real implementations include logging and database persistence, potentially extending the
* {@link ExtendedUserProfile} by locally managed user attributes and properties
*
* @author Tobias Gradl
*/
public class SampleProfileActionHandler implements ProfileActionHandler { public class SampleProfileActionHandler implements ProfileActionHandler {
private static final Logger log = LoggerFactory.getLogger(SampleProfileActionHandler.class);
@Override @Override
public void handleLogin(ExtendedUserProfile profile) { public void handleLogin(ExtendedUserProfile profile) {
log.debug("User has logged in: {}", profile.getId()); log.debug("User has logged in: {}", profile.getId());
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment