726: Finalize v1.0 for release with Schema Registry

Task-Url: https://minfba.de.dariah.eu/mantisbt/view.php?id=726

README.md

@@ -2,21 +2,69 @@
 
 This library contains a wrapper for Spring Security SAML, along with extensions useful particularly for the context of DARIAH-DE. Fundamentally, this library distinguishes two authentication methods: the *local* method is intended primarily for developer and test setups, the *saml* method is targeted towards production environments.
 
-## Authentication methods
+Both methods can easily be tested with the dariahsp-sample web application. By setting the *saml* environment variable to true (`-Dsaml=true`), the SAML service provider configuration is activated. Without the parameter, local logins (default user: *admin/password*) are supported.
 
-### Local
+## Prerequisites
 
-To support local authentication, configure this library as in the *security-local-context.xml* template. To complete the setup for this method, applications might want to implement the *UserService* interface (base implementation *BaseUserService*) to provide access to persisted user information.
+### Java Keystore 
+Even with the *local* authentication method, the dariahsp-sample application requires the configuration of a Java keystore (jks). This is mainly due to the SAML metadata generation functionality, which is available when local logins are used in order to help with installations of SAML service providers: starting the sample application in local authentication mode, the home screen of the application shows two links *SAML metadata...*, which support SAML metadata management (see SAML section below).
 
-The implementation needs to be provided to the *LocalAuthenticationProvider*.
+Based on a X.509 keypair and certificate chains, a keystore can easily be consolidated with `openssl` and the `keytool` (comes with Java installation). The followings steps show the commands for the example of the keystore for dfa.de.dariah.eu and the appropriate input. Please modify accordingly:
 
-In cases that do not require user detail persistence, no implementation of the *UserDetails* should be provided to the *LocalAuthenticationProvider*.  
+#### 1. Convert pem/pem keypair to p12 for easier input
+For the -name argument make sure to chose as *name* the later alias of the keypair in the keystore.
 
-To create bcrypt passwords from a shell:
+```
+$ openssl pkcs12 -export -name dfa.de.dariah.eu -in dfa-de-dariah-eu.crt -inkey dfa-de-dariah-eu.key > dfa-de-dariah-eu.p12
+```
+
+#### 2. Import p12 keypair and create Java keystore
+Specified in the following step with the -alias argument note the reuse of the same key name as above. Basically this step imports an existing PKCS based "keystore" into a newly created jks.
+
+```
+$ keytool -importkeystore -alias dfa.de.dariah.eu -srckeystore dfa-de-dariah-eu.p12 -destkeystore dfa-de-dariah-eu.jks -srcstoretype pkcs12
+```
+
+#### 3. Import required trusted ca certificates 
+In the particular DARIAH-DE case this means 1) the chain of our keypair and 2) the trusted SAML metadata provider keychains of the [DFN AAI](https://www.aai.dfn.de/teilnahme/metadaten/).
+
+```
+$ keytool -import -trustcacerts -alias gwdg_certificate_chain_g2 -file gwdg_certificate_chain_g2.pem -keystore dfa-de-dariah-eu.jks 
+$ keytool -import -trustcacerts -alias dfn-aai -file dfn-aai.pem -keystore dfa-de-dariah-eu.jks
+$ keytool -import -trustcacerts -alias dfn-aai-g2 -file dfn-aai.g2.pem -keystore dfa-de-dariah-eu.jks
+```
+
+#### GUI Support for Java Keystores
+A convenient GUI-based option to view and edit Java keystore can be found in the [KeyStore Explorer](http://keystore-explorer.org/) 
+
+### Local user accounts
+Local user accounts are configured in the central configuration file of the sample application. Passwords are encoded as Bcrypt hashes. In order to create your own hashes a convenience method has been implemented within the dariahsp-core library. As there are some required dependencies, you can download the latest [dariahsp-core-*-jar-with-dependencies.jar](https://minfba.de.dariah.eu/artifactory/list/dariah-minfba-snapshots/eu/dariah/de/dariahsp-core/).
+
+To then create bcrypt passwords from a shell:
 ```
 java -cp dariahsp-core-0.0.4-SNAPSHOT-jar-with-dependencies.jar eu.dariah.de.dariahsp.local.BCryptPasswordCreator
 ```
 
+## Implementing security
+
+Spring security related configuration is packed in three context files:
+* security-context-common.xml contains 
+* security-context-local.xml
+* security-context-saml.xml
+
+
+### Local user database
+
+Without specifying the saml environment parameter, the sample application starts in local authentication mode. 
+
+To support local authentication, configure this library as in the *security-local-context.xml* template. To complete the setup for this method, applications might want to implement the *UserService* interface (base implementation *BaseUserService*) to provide access to persisted user information.
+
+The implementation needs to be provided to the *LocalAuthenticationProvider*.
+
+In cases that do not require user detail persistence, no implementation of the *UserDetails* should be provided to the *LocalAuthenticationProvider*.  
+
+
+
 ### SAML
 
 ## Further info

dariahsp-sample/src/main/resources/spring/config-context.xml

@@ -8,7 +8,7 @@
 	<context:annotation-config/>
 	
 	<bean id="configLocation" class="java.lang.String">
-		<constructor-arg value="classpath:dariahsp.yml" />
+		<constructor-arg value="classpath:dariahsp_local_sample.yml" />
 	</bean>
 	<bean id="properties" class="org.springframework.beans.factory.config.YamlPropertiesFactoryBean">
 	    <property name="resources" ref="configLocation"/>