Commit dad25ff8 authored by Gradl, Tobias's avatar Gradl, Tobias
Browse files

12: Compose some initial documentation

Task-Url: #12
parent 11190306
Pipeline #17818 passed with stages
in 3 minutes and 57 seconds
Complete rewrite of the DARIAH-SP sample app and libraries (v2.0-dev)
# dariahsp: service provider implementation for DARIAH services
The former and still used libraries are tagged as v1.4 and discontinued
This project contains the [dariahsp-core] library and the Spring Boot based [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.
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.
## Important entry points
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.
## Dependencies
The library and sample application are deployed to a Maven repository:
```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>
```
For the [current snapshot version](https://minfba.de.dariah.eu/nexus/#browse/browse:minfba-central:eu%2Fdariah%2Fde%2Fdariahsp-core) of the library:
#### Maven
```xml
<dependency>
<groupId>eu.dariah.de</groupId>
<artifactId>dariahsp-core</artifactId>
<version>2.0.0-SNAPSHOT</version>
</dependency>
```
#### Gradle
```
implementation 'eu.dariah.de:dariahsp-core:2.0.0-SNAPSHOT'
```
## 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:
```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:
local: ["application_admin"]
saml: ["application_admin"]
- role: CONTRIBUTOR
level: 50
mappings:
local: ["application_contributor"]
saml: ["application_contributor"]
- role: USER
level: 10
mappings:
local: ["application_user"]
saml: ["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
* 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
\ No newline at end of file
* SecurityConfigurerAdapter for path and expression based security
## dariahsp-sample-boot app
The Spring Boot based application is documented in its module: [dariahsp-sample-boot]
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment