@@ -9,29 +9,29 @@ Both methods can easily be tested with the dariahsp-sample web application. By s
...
@@ -9,29 +9,29 @@ Both methods can easily be tested with the dariahsp-sample web application. By s
### Java Keystore
### 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).
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 dfa.de.dariah.eu and the appropriate input. Please modify accordingly:
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
#### 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.
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
#### 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.
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/).
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/).
@@ -55,11 +55,11 @@ Spring security related configuration is packed in three context files:
...
@@ -55,11 +55,11 @@ Spring security related configuration is packed in three context files:
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.
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.
### Local user database
### 1. Local authentication
Without specifying the saml environment parameter, the sample application starts in local authentication mode.
Without specifying the saml environment parameter, the sample application starts in local authentication mode.
A sample dariahsp.yml configuration
A sample **dariahsp.yml** (`src/main/resources`) configuration
```yaml
```yaml
auth:
auth:
...
@@ -79,52 +79,217 @@ auth:
...
@@ -79,52 +79,217 @@ auth:
aliaspass:'aliaspass'
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)
