README.md 10.7 KB
Newer Older
1
# dariahsp: service provider implementation for DARIAH services
Gradl, Tobias's avatar
Gradl, Tobias committed
2

3
This project contains the [dariahsp-core](dariahsp-core) library and the Spring Boot based [dariahsp-sample-boot](dariahsp-sample-boot) application. Implementations that are based on the core library need to include the dariahsp-core dependency and provide configuration for the primary security entry points.
4

5
The library is a wrapper around [Spring Security](https://spring.io/projects/spring-security), [PAC4J](https://www.pac4j.org/) and [OpenSAML 4](https://build.shibboleth.net/nexus/content/repositories/releases/org/opensaml/opensaml-core/) and implements two security methods that are commonly used in the context of DARIAH: the _local_ method is intended primarily for developer and test setups, the _saml_ method is targeted towards production environments. Both methods can easily be tested within the dariahsp-sample-boot web application. Opposed to earlier version, a choice between the methods is no longer determined by an environment flag, but by setting enabled properties within application properties. Methods can be enabled simultaneously and can work in parallel.
6

7 8
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.

9 10
## 1. Quickstart

11
A reference implementation and quick-start guide can be found in the [dariahsp-sample-boot](dariahsp-sample-boot) application.
12

13
## 2. Repository and dependency setup
14
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.
15

16
### 2.1 Maven setup
17

18 19
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:

20
#### Repository configuration
21 22

The Proxy repository _minfba-central_ provides combined access to releases and snapshots.
23 24 25 26 27 28 29 30 31 32

```xml
<repository>
    <id>minfba-central</id>
    <name>minfba-central</name>
    <url>https://minfba.de.dariah.eu/nexus/repository/minfba-central/</url>
</repository>
```

The release and snapshot repositories can be used selectively as well.
33 34 35 36 37 38 39 40 41 42 43 44 45 46

```xml
<repository>
    <id>minfba-releases</id>
    <name>minfba-releases</name>
    <url>https://minfba.de.dariah.eu/nexus/repository/minfba-releases/</url>
</repository>
<snapshotRepository>
    <id>minfba-snapshots</id>
    <name>minfba-snapshots</name>
    <url>https://minfba.de.dariah.eu/nexus/repository/minfba-snapshots/</url>
</snapshotRepository>
```

47
#### Dependency to dariahsp-core
48

49
Include the dependency to dariahsp-core in your `pom.xml`.
50 51 52 53 54 55 56 57 58

```xml
<dependency>
  <groupId>eu.dariah.de</groupId>
  <artifactId>dariahsp-core</artifactId>
  <version>2.0.0-SNAPSHOT</version>
</dependency>
```

59
### 2.2 Gradle setup
60

61
#### Repository configuration
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

For combined access to releases and snapshots, the Proxy repository _minfba-central_ can be utilized.

```groovy
repositories {
  maven {
    url "https://minfba.de.dariah.eu/nexus/repository/minfba-central/"
  }
}
```

Immediate access to either releases or snapshots can be configured based on the respective repositories.

```groovy
repositories {
  maven {
    url "https://minfba.de.dariah.eu/nexus/repository/minfba-central/"
  }
  maven {
    url "https://minfba.de.dariah.eu/nexus/repository/minfba-releases/"
  }
  maven {
    url "https://minfba.de.dariah.eu/nexus/repository/minfba-snapshots/"
  }
}
```
88
#### Dependency to dariahsp-core
89 90 91

Include the dependency to dariahsp-core in your `build.gradle`.

92 93 94 95
```
implementation 'eu.dariah.de:dariahsp-core:2.0.0-SNAPSHOT'
```

96
## 3. Security concepts and entry points
97

98
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. the [Spring Core reference](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html), the [Spring Web reference](https://docs.spring.io/spring-framework/docs/current/reference/html/web.html) and the [Spring Security Architecture](https://spring.io/guides/topicals/spring-security-architecture).
99 100 101

Components that _only need import and activation_ in the target application:

102
* [`SecurityConfig`](dariahsp-core/src/main/java/eu/dariah/de/dariahsp/config/SecurityConfig.java): Main configuration contains all security-related beans and can be imported into the applications configuration
103
* [`AuthInfoHandlerInterceptor`](dariahsp-core/src/main/java/eu/dariah/de/dariahsp/web/AuthInfoHandlerInterceptor.java) provides access to authentication information in every view-model as `_auth` attribute
104
* [`DefaultFiltersConfigurerAdapter`](dariahsp-core/src/main/java/eu/dariah/de/dariahsp/config/web/DefaultFiltersConfigurerAdapter.java) provides filters for logout and intermediat-authentication callback (SAML)
105
* [`SAMLMetadataController`](dariahsp-core/src/main/java/eu/dariah/de/dariahsp/web/controller/SAMLMetadataController.java) provides easy web access to SAML SP metadata that can be used to register the implementing application at identity providers or federations
106
* [`GlobalMethodSecurityConfig`](dariahsp-core/src/main/java/eu/dariah/de/dariahsp/config/web/GlobalMethodSecurityConfig.java) enables and configures annotation-based method security and thus simplifies security for REST controllers
107 108 109

One component requires _adaption_ in implementing applications:

110
* [`SecurityConfigurerAdapter`](dariahsp-core/src/main/java/eu/dariah/de/dariahsp/config/web/SecurityConfigurerAdapter.java) is intended to be extended by a concrete adapter that defines protected paths of the application.
111

112
## 4. Configuration
113

114 115 116
### Minimal working configuration

A minimal working configuration enables the local authentication method and provides local user accounts. 
117 118


119 120 121 122
## Local user accounts

The library supports a local authentication method that is purely based on application configuration properties. A working example including all configurable aspects:

123 124 125 126 127 128 129 130 131 132 133 134 135 136

```yaml
#Minimal working sample configuration with local authentication enabled and one configured user
auth:
  local:
    enabled: true
    #Password hash for: 1234
    users:
      - username: 'admin'
        passhash: '$2y$10$nmTcpRxs.RFUstkJJms6U.AW61Jmr64s9VNQLuhpU8gYrgzCapwka'
```

A more sophisticated configuration of the local authentication method could involve roles and role mappings along with a configured hierarchy between the roles

137 138 139 140 141 142 143 144
```yaml
auth:
  #settings under roleHierarchy and roleDefinitions apply to all supported authentication methods
  rolehierarchy: ROLE_ADMINISTRATOR > ROLE_CONTRIBUTOR > ROLE_USER
  roleDefinitions:
    - role: ADMINISTRATOR
      level: 100
      mappings: 
145
        local: ["application_admin"]      
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
    - role: CONTRIBUTOR
      level: 50
      mappings:
        local: ["application_contributor"]
    - role: USER
      level: 10
      mappings:
        local: ["application_user"]
  #Enabled local authentication method with three configured users
  local:
    enabled: true
    authorizerName: local
    #Same password for each user: 1234
    users:
      - username: 'admin'
        passhash: '$2y$10$nmTcpRxs.RFUstkJJms6U.AW61Jmr64s9VNQLuhpU8gYrgzCapwka'
        roles: ["application_admin"]
      - username: 'contributor'
        passhash: '$2y$10$nmTcpRxs.RFUstkJJms6U.AW61Jmr64s9VNQLuhpU8gYrgzCapwka'
        roles: ["application_contributor"]
      - username: 'user'
        passhash: '$2y$10$nmTcpRxs.RFUstkJJms6U.AW61Jmr64s9VNQLuhpU8gYrgzCapwka'
        roles: ["application_user"]
```


### 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).

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 minfba.de.dariah.eu and the appropriate input. Please modify accordingly:

#### 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 minfba.de.dariah.eu -in minfba-de-dariah-eu.crt -inkey minfba-de-dariah-eu.key > minfba-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 minfba.de.dariah.eu -srckeystore minfba-de-dariah-eu.p12 -destkeystore minfba-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 minfba-de-dariah-eu.jks 
$ keytool -import -trustcacerts -alias dfn-aai -file dfn-aai.pem -keystore minfba-de-dariah-eu.jks
$ keytool -import -trustcacerts -alias dfn-aai-g2 -file dfn-aai.g2.pem -keystore minfba-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
```


## dariahsp-core library
213

214

215 216 217 218 219 220 221


## dariahsp-sample-boot app

The Spring Boot based application is documented in its module: [dariahsp-sample-boot]