Commit 9b5cea4e authored by Gradl, Tobias's avatar Gradl, Tobias
Browse files

12: Compose some initial documentation

Task-Url: #12
parent bdbd525f
Pipeline #17856 passed with stage
in 2 minutes and 1 second
......@@ -202,7 +202,7 @@ auth:
## 4.3 SAML-based authentication
The configuration sample below shows important attributes that should be adapted for enabling SAML-based authentication.
There are various configuration options to control SAML-related behavior, which are set to sound defaults and not shown in the sample below. The full set of configuration properties can be reviewed in the [config.sample.yml](dariahsp-core/src/main/resources/config.sample.yml). The configuration sample below only shows such attributes that should be adapted for enabling SAML-based authentication.
```yaml
......@@ -241,9 +241,6 @@ auth:
attributeGroups:
- 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
- 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
......@@ -267,12 +264,11 @@ auth:
```
### 4.3.1 IdP metadata
### 4.3.1 Java KeyStore (JKS)
This library requires an existing Java KeyStore (JKS) that contains a private/public keypair that can be used for signature and encryption purposes. Depending on the addressed IdP or proxy, different requirements to used keys could apply. Once setup, set the appropriate configuration parameters of `saml.keystore.{path,pass,alias,aliaspass}`
Provide the URL of the desired **IdP or metadata federation**. In case of DARIAH/CLARIAH implementations, all current services use the URL as detailed in the sample above.
> **WARNING**: Although the sample implementation alreadly includes a Java KeyStore (JKS) for development purposes, please be advised to **NOT** use this keystore in deployed environments
### 4.3.2 Java KeyStore (JKS)
This library requires an existing Java KeyStore (JKS) that contains a private/public keypair that can be used for signature and encryption purposes. Depending on the addressed IdP or proxy, different requirements to used keys could apply. Once setup, set the appropriate configuration parameters of `saml.keystore.{path,pass,alias,aliaspass}`
#### Simple KeyStore generation
......@@ -282,7 +278,7 @@ If you are setting up a DARIAH/CLARIAH service, a keystore - along with the requ
keytool -genkeypair -alias keypair_alias -keypass private_key_password -keystore sample_keystore.jks -storepass keystore_password -keyalg RSA -keysize 4096 -validity 3650
```
### Creating a KeyStore from an existing keypair
#### Creating a KeyStore from an existing keypair
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
......@@ -308,5 +304,37 @@ $ keytool -import -trustcacerts -alias dfn-aai -file dfn-aai.pem -keystore minfb
$ keytool -import -trustcacerts -alias dfn-aai-g2 -file dfn-aai.g2.pem -keystore minfba-de-dariah-eu.jks
```
### 4.3.2 IdP metadata
Provide the URL of the desired **IdP or metadata federation**. In case of DARIAH/CLARIAH implementations, all current services use the URL as detailed in the sample above.
### 4.3.3 Attribute groups
#### Attribute mapping
SAML attributes can be **mapped to properties of user profiles**, that are created upon successful authentication. As such, the following configuration snipped assigns eduPersonPrincipalName values to the internal id attibute - rendering users persistently recognizable by their id.
```yaml
- friendlyName: eduPersonPrincipalName
mappedAttribute: id
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
```
#### Attribute requirements
Requirements to the existance of SAML attributes as well as their exact values can be specified in terms of `attributeGroups`. In case of the DARIAH AAI, authentication of users can only be accepted, if they have previously accepted the *DARIAH Terms of Use*, which is attested by the `dariahTermsOfUse` SAML attribute. The configuration snippet below ensures that both the `dariahTermsOfUse` and the `eduPersonPrincipalName` attributes are provided with a SAML authentication. The `check: OR` directive specifies that at least one attribute out of a defined set needs to be provided.
```yaml
- check: AND
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
- friendlyName: eduPersonPrincipalName
mappedAttribute: id
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
```
If required attribute conditions are not satisfied, a `RequiredAttributesException` is thrown, which the [dariahsp-sample-boot](dariahsp-sample-boot) application handles by redirecting the user to the URL specified at `attributesIncompleteRedirectUrl`. Implementations of the library are free to handle caught exceptions in a differently.
\ No newline at end of file
......@@ -63,9 +63,6 @@ auth:
attributeGroups:
- 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
- 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
......
......@@ -75,9 +75,6 @@ auth:
attributeGroups:
- 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
- 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
......
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