12: Compose some initial documentation

Task-Url: #12

README.md

@@ -7,13 +7,13 @@ The library is a wrapper around [Spring Security](https://spring.io/projects/spr
 While still being used, the former v1.4 is discontinued and - being based on OpenSAML 2 ([also discontinued](https://wiki.shibboleth.net/confluence/display/OpenSAML/Home)) - should be replaced with a recent version.
 
 ## 1. Getting started
-The library and sample application are deployed to a Maven repository at [https://minfba.de.dariah.eu/nexus]. Repository configuration can be included in Maven and Gradle settings and build configurations with the following snippets.
+The library and sample application are deployed to the Maven repository available at https://minfba.de.dariah.eu/nexus. Repository configuration can be included in Maven and Gradle settings and build configurations with the following snippets.
 
 ### 1.1 Maven setup
 
 Please find information on the current version of dariahsp-core at the [respective package](https://minfba.de.dariah.eu/nexus/#browse/browse:minfba-central:eu%2Fdariah%2Fde%2Fdariahsp-core) in the deployment repository:
 
-#### Maven: Repository configuration
+#### Repository configuration
 
 The Proxy repository _minfba-central_ provides combined access to releases and snapshots.
 
@@ -40,7 +40,7 @@ The release and snapshot repositories can be used selectively as well.
 </snapshotRepository>
 ```
 
-#### Maven: Dependency to dariahsp-core
+#### Dependency to dariahsp-core
 
 Include the dependency to dariahsp-core in your `pom.xml`.
 
@@ -54,7 +54,7 @@ Include the dependency to dariahsp-core in your `pom.xml`.
 
 ### 1.2 Gradle setup
 
-#### Gradle: Repository configuration
+#### Repository configuration
 
 For combined access to releases and snapshots, the Proxy repository _minfba-central_ can be utilized.
 
@@ -81,7 +81,7 @@ repositories {
   }
 }
 ```
-#### Gradle: Dependency to dariahsp-core
+#### Dependency to dariahsp-core
 
 Include the dependency to dariahsp-core in your `build.gradle`.
 
@@ -89,6 +89,25 @@ Include the dependency to dariahsp-core in your `build.gradle`.
 implementation 'eu.dariah.de:dariahsp-core:2.0.0-SNAPSHOT'
 ```
 
+## 2. Security concepts and entry points
+
+As this library is based on Spring Security, concepts such as _Java-based configuration_, _filters_, _interceptors_ or _global method security_ can be referenced in the respective Spring documentation, e.g. [here](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html) or [here](https://docs.spring.io/spring-framework/docs/current/reference/html/web.html) or [here](https://spring.io/guides/topicals/spring-security-architecture).
+
+For a reference implementation of the security concepts, please see the [dariahsp-sample-boot](dariahsp-sample-boot) application.
+
+Components that _only need import and activation_ in the target application:
+
+* `SecurityConfig`: Main configuration contains all security-related beans and can be imported into the applications configuration
+* `AuthInfoHandlerInterceptor` provides access to authentication information in every view-model as `_auth` attribute
+* `DefaultFiltersConfigurerAdapter` provides filters for logout and intermediat-authentication callback (SAML)
+* `SAMLMetadataController` provides easy web access to SAML SP metadata that can be used to register the implementing application at identity providers or federations
+* `GlobalMethodSecurityConfig` enables and configures annotation-based method security and thus simplifies security for REST controllers
+
+One component requires _adaption_ in implementing applications:
+
+* `SecurityConfigurerAdapter` is intended to be extended by a concrete adapter that defines protected paths of the application.
+
+## 3. Configuration
 
 
 
@@ -187,12 +206,7 @@ $ java -cp dariahsp-core-0.0.4-SNAPSHOT-jar-with-dependencies.jar eu.dariah.de.d
 
 ## dariahsp-core library
 
-* Enable configuration in SecurityConfig
-* SAMLMetadataController allows web access to SAML metadata
-* AuthInfoHandlerInterceptor puts auth information in every model (through AuthInfoConfigurer)
-* DefaultFiltersConfigurerAdapter for central logout and callback
-* GlobalMethodSecurityConfig for method security (annotations)
-* SecurityConfigurerAdapter for path and expression based security
+
 
 
 ## dariahsp-sample-boot app