Commit 8897f567 authored by Gradl, Tobias's avatar Gradl, Tobias
Browse files

Merge branch 'documentation' into 'v2.0'

Documentation

See merge request !1
parents dad25ff8 883398cd
Pipeline #17895 passed with stage
in 1 minute and 55 seconds
......@@ -14,12 +14,24 @@ cache:
- .gradle/caches
stages:
- test
- build
- deploy
test:
stage: test
script:
- ./gradlew check
build:
stage: build
script: ./gradlew assemble
artifacts:
paths:
- dariahsp-core/build/libs/*.jar
- dariahsp-sample-boot/build/libs/*.jar
only:
- v2.0
deploy:
stage: deploy
......
# dariahsp: service provider implementation for DARIAH services
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.
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.
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.
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:
## 1. Quickstart
A reference implementation and quick-start guide can be found in the [dariahsp-sample-boot](dariahsp-sample-boot) application.
## 2. Repository and dependency setup
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.
### 2.1 Maven setup
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:
#### Repository configuration
The Proxy repository _minfba-central_ provides combined access to releases and snapshots.
```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.
```xml
<repository>
......@@ -22,9 +44,10 @@ The library and sample application are deployed to a Maven repository:
</snapshotRepository>
```
For the [current snapshot version](https://minfba.de.dariah.eu/nexus/#browse/browse:minfba-central:eu%2Fdariah%2Fde%2Fdariahsp-core) of the library:
#### Dependency to dariahsp-core
Include the dependency to dariahsp-core in your `pom.xml`.
#### Maven
```xml
<dependency>
<groupId>eu.dariah.de</groupId>
......@@ -33,15 +56,84 @@ For the [current snapshot version](https://minfba.de.dariah.eu/nexus/#browse/bro
</dependency>
```
#### Gradle
### 2.2 Gradle setup
#### Repository configuration
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/"
}
}
```
#### Dependency to dariahsp-core
Include the dependency to dariahsp-core in your `build.gradle`.
```
implementation 'eu.dariah.de:dariahsp-core:2.0.0-SNAPSHOT'
```
## 3. Security concepts and entry points
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).
Components that _only need import and activation_ in the target application:
* [`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
* [`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
* [`DefaultFiltersConfigurerAdapter`](dariahsp-core/src/main/java/eu/dariah/de/dariahsp/config/web/DefaultFiltersConfigurerAdapter.java) provides filters for logout and intermediat-authentication callback (SAML)
* [`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
* [`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
One component requires _adaption_ in implementing applications:
* [`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.
## 4. Configuration
### Minimal working configuration
A minimal working configuration enables the local authentication method and provides local user accounts.
## 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
#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
```yaml
auth:
#settings under roleHierarchy and roleDefinitions apply to all supported authentication methods
......@@ -51,17 +143,14 @@ auth:
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
......@@ -122,12 +211,7 @@ $ java -cp dariahsp-core-0.0.4-SNAPSHOT-jar-with-dependencies.jar eu.dariah.de.d
## 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
## dariahsp-sample-boot app
......
plugins {
id 'java-library'
id 'io.spring.dependency-management' version "1.0.8.RELEASE"
id 'io.spring.dependency-management' version "1.0.10.RELEASE"
id 'org.springframework.boot' version "2.3.5.RELEASE" apply false
}
allprojects {
......@@ -18,9 +18,9 @@ allprojects {
springPac4jVersion = "5.1.0"
webmvcPac4jVersion = "4.0.1"
pac4jVersion = "4.1.0"
lombokVersion = "1.18.14"
/*lombokVersion = "1.18.14"
servletApiVersion = "4.0.1"
jspApiVersion = "2.3.3"
jspApiVersion = "2.3.3"*/
librarySets = [
commonTest: [
......@@ -41,6 +41,13 @@ subprojects {
apply plugin: 'java'
apply plugin: 'maven-publish'
apply plugin: 'eclipse'
apply plugin: 'io.spring.dependency-management'
dependencyManagement {
imports {
mavenBom(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
}
}
publishing {
publications {
......
......@@ -11,10 +11,10 @@ dependencies {
api "org.pac4j:pac4j-saml:$pac4jVersion"
api "org.pac4j:pac4j-http:$pac4jVersion"
implementation "org.springframework:spring-webmvc"
implementation "javax.servlet:javax.servlet-api:$servletApiVersion"
implementation "javax.servlet:javax.servlet-api"
compileOnly "org.projectlombok:lombok:$lombokVersion"
annotationProcessor "org.projectlombok:lombok:$lombokVersion"
compileOnly "org.projectlombok:lombok"
annotationProcessor "org.projectlombok:lombok"
testImplementation librarySets.commonTest
}
......@@ -23,12 +23,33 @@ jar {
enabled = true
}
task customFatJar(type: Jar) {
manifest {
attributes 'Main-Class': ' eu.dariah.de.dariahsp.BCryptPasswordCreator'
}
archiveClassifier = 'fatjar'
dependsOn configurations.runtimeClasspath
from {
configurations.runtimeClasspath.findAll { it.name.endsWith('jar') }.collect { zipTree(it) }
}
exclude 'META-INF/*.RSA'
exclude 'META-INF/*.SF'
exclude 'META-INF/*.DSA'
with jar
}
artifacts {
archives customFatJar
}
publishing {
publications {
maven(MavenPublication) {
from(components.java)
artifact(sourcesJar) {}
artifact(javadocJar) {}
artifact(customFatJar) {}
}
}
}
\ No newline at end of file
......@@ -10,9 +10,6 @@ public class BCryptPasswordCreator {
Scanner scanner = new Scanner (System.in);
System.out.println("CLI Tool to create BCrypt passwords to be used with a dariahsp derived application");
System.out.println("------------------------------------------------------");
System.out.println("Please make sure to provide BCrypt initialization arguments exactly \n as they are configured in the security-context-common.xml");
System.out.println("If you have not changed the default initialization of the BCryptPasswordEncoder \n (and you dont have to), choose the default values for rounds:");
System.out.println("------------------------------------------------------");
System.out.println("Please choose rounds [4-31; default: 10]");
......
plugins {
id 'war'
id 'org.springframework.boot' version "2.3.4.RELEASE"
id 'io.spring.dependency-management'
}
apply plugin: 'org.springframework.boot'
dependencies {
implementation project(':dariahsp-core')
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.apache.tomcat.embed:tomcat-embed-jasper'
implementation "javax.servlet:jstl"
providedCompile "javax.servlet:javax.servlet-api"
providedCompile "javax.servlet.jsp:javax.servlet.jsp-api:$jspApiVersion"
//providedCompile "javax.servlet:javax.servlet-api"
//providedCompile "javax.servlet.jsp:javax.servlet.jsp-api:$jspApiVersion"
compileOnly 'org.projectlombok:lombok'
developmentOnly 'org.springframework.boot:spring-boot-devtools'
annotationProcessor 'org.projectlombok:lombok'
providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
//providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
testImplementation librarySets.commonTest
......@@ -26,6 +23,7 @@ dependencies {
bootJar {
enabled = true
mainClassName = 'eu.dariah.de.dariahsp.sample.SampleApplication'
}
publishing {
......
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