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.
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.
## Prerequisites
### 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.
#### 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.
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/).
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/).
Spring security related configuration is packed in three context files:
**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.
### 1. Local authentication
Without specifying the saml environment parameter, the sample application starts in local authentication mode.
A sample **dariahsp.yml** (`src/main/resources`) configuration
```yaml
auth:
local:
users:
-username:'admin'
#this hash represents the BCrypt encoded 'password'
#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'
```
### 2. SAML SP metadata
Once the application is set up two SAML metadata related links are shown on the homepage:
**SAML metadata link* (`/saml/metadata`) allows you to download the current SAML metadata. Please note: if you have not configured any SAML related configuration parameters, a (probably too) simple metadata set is generated automatically.
**SAML metadata management* (`/saml/web/metadata`) leads you to SAML metadata management functionalities that allows the configuration of SAML related options
#### Important for attribute queries
In DARIAH-DE SAML attribute queries are utilized to aggregate account information for non-DARIAH users. If a user e.g. authenticates with his home-university account, he needs to accept the DARIAH-DE Terms of Use in order to operate DARIAH-DE services. The attribute indicating whether or not the TOU have been accepted are stored centrally within the DARIAH-DE infrastructure - not with the home-account of the user. For this reason - after initially logging in - an attribute query to the central DARIAH-DE IdP is necessary.
Required attributes currently need to be preconfigured before creating the SAML SP metadata in the next step. The following configuration shows you the parameters currently applied for DARIAH-DE services. Please note that this configuration still relies on local authentication and merely defines the reqired attributes for metadata generation:
```yaml
auth:
local:
users:
-username:'admin'
#this hash represents the BCrypt encoded 'password'
After successfully restarting the application with the required attributes (if there are any), follow the link to *SAML metadata management* and confirm the *Generate metadata* button.
In the following list, appropriate options for DARIAH-DE SPs are indicated. For other use-cases please change the selections accordingly:
**Store for current session*: Yes (allows you to later download the metadata file)
**Entity ID*: Identifier for the service provider (e.g. 'https://minfba.de.dariah.eu'; note: must be a URL for registration with DFN AAI)
**Entity base URL*: Hosted URL of the SP (e.g. 'https://minfba.de.dariah.eu:443/dariahsp')
**Entity alias*: alias of the SP (e.g. 'dariahsp')
**Signing key*, *Encryption key*, *SSL/TLS client authentication*: select available key in configured keystore
**Custom URL for IDP discovery*: **leave empty** (in this case custom **local** URL, not WAYF)
**Include IDP discovery extension in metadata*: Yes
After selecting *Generate metadata* both the required metadata and configuration parameters are created. Click on *Download entity metadata* and store the file persistently in your server's file system.
### 3. Switch to SAML Authentication
With the generated metadata and configuration options, the application has complete information to switch to the SAML authentication method.
#### Register metadata
In addition to setting up your SP, relevant SAML identity providers need to know your metadata in order to provide remote authentication. In the case of DARIAH-DE and the DFN-AAI, metadata can be registered and managed on the pages of the [DFN](https://www.aai.dfn.de/verwaltung/). Seek assistance of the SAML/Shibboleth expert within your organization, project or at the hotline of the DFN.
#### Complete your configuration
Putting it all together, a sample configuration file is presented in the following. As always, modify accordingly.
```yaml
auth:
# Local options are not respected when SAML is activated.
# Options can stay configured, however, in order to simplify method switching in case of problems
* The library and sample are based on the [Spring Security SAML Extension](http://projects.spring.io/spring-security-saml/) where you can find more information on some of the configuration parameters and options
* Information on attribute querying and the AAI in DARIAH-DE can be found in the [DARIAH-DE Wiki](https://wiki.de.dariah.eu/display/publicde/DARIAH+AAI+Documentation)
## Dependencies
The library and sample application are currently deployed to a Maven repository:
The [current release version](https://minfba.de.dariah.eu/artifactory/webapp/#/artifacts/browse/tree/General/dariah-minfba-releases/eu/dariah/de/dariahsp-core/1.0.0/dariahsp-core-1.0.0.jar) of the library:
