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

726: Finalize v1.0 for release with Schema Registry

Task-Url: https://minfba.de.dariah.eu/mantisbt/view.php?id=726
parent 0eafe9f0
...@@ -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.
``` ```
$ openssl pkcs12 -export -name dfa.de.dariah.eu -in dfa-de-dariah-eu.crt -inkey dfa-de-dariah-eu.key > dfa-de-dariah-eu.p12 $ 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 #### 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.
``` ```
$ keytool -importkeystore -alias dfa.de.dariah.eu -srckeystore dfa-de-dariah-eu.p12 -destkeystore dfa-de-dariah-eu.jks -srcstoretype pkcs12 $ 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 #### 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/). 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 dfa-de-dariah-eu.jks $ 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 dfa-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 dfa-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 #### GUI Support for Java Keystores
...@@ -42,7 +42,7 @@ Local user accounts are configured in the central configuration file of the samp ...@@ -42,7 +42,7 @@ Local user accounts are configured in the central configuration file of the samp
To then create bcrypt passwords from a shell: 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 $ java -cp dariahsp-core-0.0.4-SNAPSHOT-jar-with-dependencies.jar eu.dariah.de.dariahsp.local.BCryptPasswordCreator
``` ```
## Implementing security ## Implementing security
...@@ -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'
passhash: '$2a$10$nbXRnAx5wKurTrbaUkT/MOLXKAJgpT8R71/jujzPwgXXrG.OqlBKW'
roles: ["ROLE_ADMINISTRATOR"]
saml:
keystore:
path: /path/to/keystore.jks
#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'
sp:
requiredAttributes:
- stage: ATTRIBUTES
required: true
attributeGroup:
- check: AND
attributes:
- friendlyName: mail
name: urn:oid:0.9.2342.19200300.100.1.3
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- stage: ATTRIBUTES
required: true
attributeGroup:
- check: OR
attributes:
- friendlyName: dariahTermsOfUse
name: urn:oid:1.3.6.1.4.1.10126.1.52.4.15
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
value: Terms_of_Use_v5.pdf
- friendlyName: dariahTermsOfUse
name: urn:oid:1.3.6.1.4.1.10126.1.52.4.15
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
value: foobar-service-agreement_version1.pdf
- stage: AUTHENTICATION
required: true
attributeGroup:
- check: AND
attributes:
- friendlyName: eduPersonPrincipalName
name: urn:oid:1.3.6.1.4.1.5923.1.1.1.6
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- stage: AUTHENTICATION
required: false
attributeGroup:
- check: OPTIONAL
attributes:
- friendlyName: mail
name: urn:oid:0.9.2342.19200300.100.1.3
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- friendlyName: displayName
name: urn:oid:2.16.840.1.113730.3.1.241
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
```
#### Metadata generation
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
* *Signature security profile*: leave default
* *SSL/TLS security profile*: leave default
* *SSL/TLS hostname verification*: leave default
* *Sign metadata*: Yes
* *Sign metadata*: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
* *Sign sent AuthNRequests: Yes
* *Require signed authentication Assertion*: Yes
* *Require signed attribute Assertion*: Yes
* *Require signed LogoutRequest*: Yes
* *Require signed LogoutResponse*: No
* *Require signed ArtifactResolve*: Yes
* *Single sign-on bindings*: leave defaults
* *Supported NameIDs*: leave defaults
* *Enable IDP discovery profile*: Yes
* *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
local:
users:
- username: 'admin'
passhash: '$2a$10$nbXRnAx5wKurTrbaUkT/MOLXKAJgpT8R71/jujzPwgXXrG.OqlBKW'
roles: ["ROLE_ADMINISTRATOR"]
saml:
keystore:
path: /path/to/keystore.jks
#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'
metadata:
url: https://www.aai.dfn.de/fileadmin/metadata/dfn-aai-test-metadata.xml
#url: https://www.aai.dfn.de/fileadmin/metadata/dfn-aai-basic-metadata.xml
sp:
externalMetadata: /path/to/metadata/in/filesystem/spring_saml_metadata.xml
alias: dariahsp
baseUrr: https://minfba.de.dariah.eu/dariahsp
entityId: minfba.de.dariah.eu_dariahsp
securityProfile: metaiop
sslSecurityProfile: pkix
sslHostnameVerification: default
signMetadata: true
signingAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
signingKey: minfba.de.dariah.eu
encryptionKey: minfba.de.dariah.eu
tlsKey: minfba.de.dariah.eu
requireArtifactResolveSigned: true
requireAttributeQuerySigned: false
requireLogoutRequestSigned: true
requireLogoutResponseSigned: false
discovery:
enabled: true
url: https://minfba.de.dariah.eu/dariahsp/saml/login/alias/dariahsp?disco:true
return: https://minfba.de.dariah.eu/dariahsp/saml/discovery/alias/dariahsp
allowedNameIds : EMAIL, TRANSIENT, PERSISTENT, UNSPECIFIED, X509_SUBJECT
# Attribute querying (if required)
attributeQuery:
enabled: true
excludedEndpoints:
urls: ["https://ldap-dariah-clone.esc.rzg.mpg.de/idp/shibboleth", "https://idp.de.dariah.eu/idp/shibboleth"]
assumeAttributesComplete: true
queryIdp: https://ldap-dariah-clone.esc.rzg.mpg.de/idp/shibboleth
#queryIdp: https://idp.de.dariah.eu/idp/shibboleth
queryByNameID: false
queryAttribute:
friendlyName: eduPersonPrincipalName
name: urn:oid:1.3.6.1.4.1.5923.1.1.1.6
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
# For now without parameters bc DARIAH Self Service is broken
incompleteAttributesRedirect: "https://dariah.daasi.de/Shibboleth.sso/Login?target=/cgi-bin/selfservice/ldapportal.pl"
#incompleteAttributesRedirect: "https://dariah.daasi.de/Shibboleth.sso/Login?target=/cgi-bin/selfservice/ldapportal.pl%3Fmode%3Dauthenticate%3Bshibboleth%3D1%3Bnextpage%3Dregistration%3Breturnurl%3D{returnUrl}&entityID={entityId}"
#incompleteAttributesRedirect: "https://auth.dariah.eu/Shibboleth.sso/Login?target=/cgi-bin/selfservice/ldapportal.pl%3Fmode%3Dauthenticate%3Bshibboleth%3D1%3Bnextpage%3Dregistration%3Breturnurl%3D{returnUrl}&entityID={entityId}"
requiredAttributes:
- stage: ATTRIBUTES
required: true
attributeGroup:
- check: AND
attributes:
- friendlyName: mail
name: urn:oid:0.9.2342.19200300.100.1.3
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- stage: ATTRIBUTES
required: true
attributeGroup:
- check: OR
attributes:
- friendlyName: dariahTermsOfUse
name: urn:oid:1.3.6.1.4.1.10126.1.52.4.15
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
value: Terms_of_Use_v5.pdf
- friendlyName: dariahTermsOfUse
name: urn:oid:1.3.6.1.4.1.10126.1.52.4.15
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
value: foobar-service-agreement_version1.pdf
- stage: AUTHENTICATION
required: true
attributeGroup:
- check: AND
attributes:
- friendlyName: eduPersonPrincipalName
name: urn:oid:1.3.6.1.4.1.5923.1.1.1.6
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- stage: AUTHENTICATION
required: false
attributeGroup:
- check: OPTIONAL
attributes:
- friendlyName: mail
name: urn:oid:0.9.2342.19200300.100.1.3
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- friendlyName: displayName
name: urn:oid:2.16.840.1.113730.3.1.241
nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
```
### Further information
* 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)
\ No newline at end of file
...@@ -8,7 +8,7 @@ ...@@ -8,7 +8,7 @@
<context:annotation-config/> <context:annotation-config/>
<bean id="configLocation" class="java.lang.String"> <bean id="configLocation" class="java.lang.String">
<constructor-arg value="classpath:dariahsp_local_sample.yml" /> <constructor-arg value="classpath:dariahsp.yml" />
</bean> </bean>
<bean id="properties" class="org.springframework.beans.factory.config.YamlPropertiesFactoryBean"> <bean id="properties" class="org.springframework.beans.factory.config.YamlPropertiesFactoryBean">
<property name="resources" ref="configLocation"/> <property name="resources" ref="configLocation"/>
......
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