README.md 6.1 KB
Newer Older
1
2
3
4
# dariahsp

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.

5
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.
6

7
## Prerequisites
8

9
10
### 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).
11

12
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:
13

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
#### 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.

```
$ 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
```
36

37
38
39
40
41
42
43
#### 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:
44
```
45
java -cp dariahsp-core-0.0.4-SNAPSHOT-jar-with-dependencies.jar eu.dariah.de.dariahsp.local.BCryptPasswordCreator
46
47
```

48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
## 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*.  



68
69
70
71
72
73
74
75
76
### SAML

## Further info

### Java keystore

Based on a X.509 keypair and certificate chains, the required Java 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:

**Convert pem/pem keypair to p12 for easier input:**
77
For the -name argument make sure to chose the later alias of the keypair in the keystore -- specified in the following step with the -alias argument.
78
79

```
80
$ openssl pkcs12 -export -name dfa.de.dariah.eu -in dfa-de-dariah-eu-signed.pem -inkey dfa-de-dariah-eu-privatekey.pem > dfa-de-dariah-eu.p12
81
82
83
84
85
```

**Import p12 keypair and create Java keystore**

```
86
$ keytool -importkeystore -alias dfa.de.dariah.eu -srckeystore dfa-de-dariah-eu.p12 -destkeystore dfa-de-dariah-eu.jks -srcstoretype pkcs12
87
88
89
90
91
92
93
94
```

**Import required trusted ca certificates (in our case the chain of our keypair and the trusted SAML metadata provider keychains)**

```
$ 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
95
96
```

97
98
99
100
101
102
103
104
105
A more or less convenient option to view and edit Java keystore can be found in the [KeyStore Explorer](http://keystore-explorer.org/) 

**Specify configuration parameters**
```
saml.keystore.path = /path/to/dfa-de-dariah-eu.jks
saml.keystore.pass = password 		# as entered in step 2 (keytool -importkeystore)
saml.keystore.alias = dfa.de.dariah.eu
saml.keystore.aliaspass = password	# as entered in step 1 (openssl pkcs12 -export) 
```