12: Compose some initial documentation

Task-Url: #12

dariahsp-core/src/main/java/eu/dariah/de/dariahsp/config/web/AuthInfoConfigurer.java

@@ -8,10 +8,20 @@ import eu.dariah.de.dariahsp.web.AuthInfoHandlerInterceptor;
 import eu.dariah.de.dariahsp.web.AuthInfoHelper;
 import lombok.extern.slf4j.Slf4j;
 
+/**
+ * WebMvcConfigurer responsible for injecting the {@link AuthInfoHandlerInterceptor} into the filter chain, an interceptor
+ *  that is responsible for providing basic authentication and authorization information into the model.
+ * 
+ * @author Tobias Gradl
+ *
+ */
 @Slf4j
 public class AuthInfoConfigurer implements WebMvcConfigurer {
 	@Autowired private AuthInfoHelper authInfoHelper;
 	
+	/**
+	 * Adds an {@link AuthInfoHandlerInterceptor} to the {@link InterceptorRegistry}
+	 */
 	@Override
 	public void addInterceptors(InterceptorRegistry registry) {
 	    registry.addInterceptor(authInfoHandlerInterceptor());

dariahsp-core/src/main/java/eu/dariah/de/dariahsp/web/AuthInfoHandlerInterceptor.java

@@ -10,6 +10,11 @@ import org.springframework.web.servlet.support.RequestContextUtils;
 
 import eu.dariah.de.dariahsp.web.model.AuthPojo;
 
+/**
+ * Interceptor that adds basic authentication and authorization information as {@link AuthPojo} to each request model 
+ * 
+ * @author Tobias Gradl
+ */
 public class AuthInfoHandlerInterceptor extends HandlerInterceptorAdapter {
 	private AuthInfoHelper authInfoHelper;
 	
@@ -17,6 +22,9 @@ public class AuthInfoHandlerInterceptor extends HandlerInterceptorAdapter {
 	public void setAuthInfoHelper(AuthInfoHelper authInfoHelper) { this.authInfoHelper = authInfoHelper; }
 
 	
+	/*
+	 * Adds the _sessionId and _auth request model attributes
+	 */
 	@Override
 	public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
 		if (modelAndView==null) {

dariahsp-sample-boot/README.md

-## DARIAHSP - Sample boot app
\ No newline at end of file
+## 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.
+
+> See the JavaDoc for further explanation on the components of the sample application
+
+### Initialization
+1. [`SampleApplication`](/src/main/java/eu/dariah/de/dariahsp/sample/SampleApplication.java) is the Spring Boot application class and handles initialization
+
+### Configuration
+
+2. [`SampleConfig`](/src/main/java/eu/dariah/de/dariahsp/sample/SampleApplication.java) serves as primary application configuration class; it defines the beans of 
+  * `profileActionPostprocessor` for processing of login and logout activity, 
+  * `samlMetadataController`, a controller bean that facilitates access to metadata of the SP and
+  * `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
+

dariahsp-sample-boot/build.gradle

@@ -6,19 +6,7 @@ dependencies {
 	implementation 'org.apache.tomcat.embed:tomcat-embed-jasper'
 	implementation "javax.servlet:jstl"
 	
-	//providedCompile "javax.servlet:javax.servlet-api"
-	//providedCompile "javax.servlet.jsp:javax.servlet.jsp-api:$jspApiVersion"
-    
-	compileOnly 'org.projectlombok:lombok'
 	developmentOnly 'org.springframework.boot:spring-boot-devtools'
-	annotationProcessor 'org.projectlombok:lombok'
-	//providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
-	
-	
-	testImplementation librarySets.commonTest
-	testImplementation('org.springframework.boot:spring-boot-starter-test') {
-		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
-	}
 }
 
 bootJar {

dariahsp-sample-boot/src/main/java/eu/dariah/de/dariahsp/sample/SampleApplication.java

@@ -3,22 +3,15 @@ package eu.dariah.de.dariahsp.sample;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.ComponentScan;
-
-import eu.dariah.de.dariahsp.ProfileActionHandler;
-import eu.dariah.de.dariahsp.sample.profiles.SampleProfileActionHandler;
 
+/**
+ * Spring Boot application class
+ * 
+ * @author Tobias Gradl
+ */
 @SpringBootApplication
 @ConfigurationPropertiesScan
-@ComponentScan({"eu.dariah.de.dariahsp.sample", "eu.dariah.de.dariahsp.web.controller"})
-public class SampleApplication {
-	
-	@Bean
-	public ProfileActionHandler profileActionPostprocessor() {
-		return new SampleProfileActionHandler();
-	}
-	
+public class SampleApplication {	
 	public static void main(String[] args) {
 		SpringApplication.run(SampleApplication.class, args);
 	}

dariahsp-sample-boot/src/main/java/eu/dariah/de/dariahsp/sample/config/SampleConfig.java

 package eu.dariah.de.dariahsp.sample.config;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.boot.web.server.WebServerFactoryCustomizer;
 import org.springframework.boot.web.servlet.server.ConfigurableServletWebServerFactory;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
-import lombok.Data;
-import lombok.extern.slf4j.Slf4j;
+import eu.dariah.de.dariahsp.CustomizableProfileManager;
+import eu.dariah.de.dariahsp.ProfileActionHandler;
+import eu.dariah.de.dariahsp.sample.profiles.SampleProfileActionHandler;
+import eu.dariah.de.dariahsp.web.controller.SAMLMetadataController;
 
-@Data
-@Slf4j
 @Configuration
 @ConfigurationProperties
 public class SampleConfig {
+	private static final Logger log = LoggerFactory.getLogger(SampleConfig.class);
 	
 	private String contextPath = "";
 	
+	public String getContextPath() { return contextPath; }
+ 	public void setContextPath(String contextPath) { this.contextPath = contextPath; }
+
+	/**
+	 * WebServerFactoryCustomizer bean that adapts to a configured context path for the application. This adaption is not 
+	 *  necessary for implementation of the dariahsp-core library, but helps with setting up the application as it might 
+	 *  be available or proxied at their deployments
+	 * 
+	 * @return WebServerFactoryCustomizer
+	 */
 	@Bean
 	public WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> webServerFactoryCustomizer() {
 		log.info("Web server context path set to {}", contextPath.isEmpty() ? "/" : contextPath);
 	    return factory -> factory.setContextPath(contextPath);
 	}
+
+	/**
+	 * Bean that is injected into {@link CustomizableProfileManager} to facilitate observation of login and logout actions
+	 *  Implementations can provide custom implementations of the {@link ProfileActionHandler} interface e.g. to log such
+	 *  actions into a database
+	 *    
+	 * @return SampleProfileActionHandler bean
+	 */
+	@Bean
+	public ProfileActionHandler profileActionPostprocessor() {
+		return new SampleProfileActionHandler();
+	}
+	
+	/**
+	 * Controller bean that facilitates access to generated or stored SAML SP metadata
+	 * 
+	 * @return SAMLMetadataController bean
+	 */
+	@Bean
+	public SAMLMetadataController samlMetadataController() {
+		return new SAMLMetadataController();
+	}
 }

dariahsp-sample-boot/src/main/java/eu/dariah/de/dariahsp/sample/config/SampleSecurityConfig.java

@@ -6,11 +6,15 @@ import org.springframework.context.annotation.Import;
 
 import eu.dariah.de.dariahsp.config.SecurityConfig;
 import eu.dariah.de.dariahsp.config.web.AuthInfoConfigurer;
-import lombok.Data;
-import lombok.EqualsAndHashCode;
 
-@Data
-@EqualsAndHashCode(callSuper=false)
+/**
+ * Main security configuration extends {@link SecurityConfig}. The auth namespace of the configuration properties 
+ *  is utilized for the configuration of the extended {@link SecurityConfig}.
+ *  
+ * Import of the {@link AuthInfoConfigurer} class ultimately ensures configuration of the {@link AuthInfoHandlerInterceptor} 
+ * 
+ * @author Tobias Gradl
+ */
 @Configuration
 @ConfigurationProperties(prefix = "auth")
 @Import({AuthInfoConfigurer.class})

dariahsp-sample-boot/src/main/resources/application.yml

@@ -56,7 +56,7 @@ auth:
       path: classpath:sample_keystore.jks
       pass: keystore_password
       alias: keypair_alias
-      aliaspass: private_key_password
+      aliaspass: keypass
     metadata:
       url: https://aaiproxy.de.dariah.eu/idp/
     sp: