README.md 4.85 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
## Implementing security

Spring security related configuration is packed in three context files:
51
52
53
54
55
* *security-context-common.xml* contains all security related beans that are relevant for both local and SAML based authentication methods. The common context is included in the -local and -saml context files.
* *security-context-local.xml* defines beans only necessary in local authentication enviroments.
* *security-context-saml.xml* respectively only includes beans that are required for SAML processing.

With the environment flag `-Dsaml=true` the local context is no longer loaded and the saml context comes into play. When set to false or missing, the local context is loaded.
56
57
58
59
60
61


### Local user database

Without specifying the saml environment parameter, the sample application starts in local authentication mode. 

62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
A sample dariahsp.yml configuration 

```yaml
auth:
  local: 
    users:  
      - username: 'admin'
        #this hash represents the BCrypt encoded 'password'
        passhash: '$2a$10$nbXRnAx5wKurTrbaUkT/MOLXKAJgpT8R71/jujzPwgXXrG.OqlBKW'
        roles: ["ROLE_ADMINISTRATOR"]
  saml:
    keystore:
      path: /path/to/keystore.jks
      #Uncomment if keystore is not protected by password
      #pass: 'somepass'
      alias: minfba.de.dariah.eu
      #leave aliaspass empty if no password has been set
      aliaspass: 'aliaspass'
```


































115
116
117
118
119





120
121
122
123
124
125
126
127
128









129

130