12: Compose some initial documentation

Task-Url: #12

dariahsp-core/src/main/resources/config.sample.yml

 # Config options of the dariahsp core library
 # Commented properties reflect default values
 auth:
+  # Base externally visible URL
   #baseUrl: http://localhost:8080
+  # Default redirected URL post login
   #defaultLoginUrl: ${auth.baseUrl}
+  # Default redirected URL post logout
   #defaultLogoutUrl: ${auth.baseUrl}
+  # Salt for signing and encryption purposes
   salt: Qmwp4CO7LDkOUDouAcCcUqd9ZGNbRG5Jyr5lpntOuB9
+  # Hierarchy used in role-based authorization voting 
   permissionHierarchy: ROLE_ADMINISTRATOR > ROLE_CONTRIBUTOR > ROLE_USER
+  # Permission sets to code against and mapping to 'external' roles
   permissionDefinitions:
-    - permissionSet: ADMINISTRATOR
+      # Name of the permission set (internal role)
+    - permissionSet: ROLE_ADMINISTRATOR
+      # Numerical authorization level allowing security expressions as level gte 50
       level: 100
       roleMappings: 
+        # Role mapping to locally configured roles
         local: ["application_admin"]
+        # Role mapping to SAML (typically memberOf) roles
         saml: ["application_admin"]       
-    - permissionSet: CONTRIBUTOR
+    - permissionSet: ROLE_CONTRIBUTOR
       level: 50
       roleMappings:
         local: ["application_contributor"]
         saml: ["application_contributor"]
-    - permissionSet: USER
+    - permissionSet: ROLE_USER
       level: 10
       roleMappings:
         local: ["application_user"]
         saml: ["application_user"]
   local:
+    # Enable local authentication
     enabled: true
-    authorizerName: local
+    # Name of the method
+    #authorizerName: local
     # Same password for each user: 1234
     users:
+        # Username
       - username: 'admin'
+        # BCrypt hashed password
         passhash: '$2y$10$nmTcpRxs.RFUstkJJms6U.AW61Jmr64s9VNQLuhpU8gYrgzCapwka'
+        # Pseudo-external role
         roles: ["application_admin"]
       - username: 'contributor'
         passhash: '$2y$10$nmTcpRxs.RFUstkJJms6U.AW61Jmr64s9VNQLuhpU8gYrgzCapwka'
@@ -37,40 +52,57 @@ auth:
         passhash: '$2y$10$nmTcpRxs.RFUstkJJms6U.AW61Jmr64s9VNQLuhpU8gYrgzCapwka'
         roles: ["application_user"]
   saml:
+    # Enable SAML authentication
     enabled: false
-    authorizerName: saml
+    # Name of the method
+    #authorizerName: saml
+    # Java KeyStore configuration
     keystore:
       path: /path/to/keystore.jks
       pass: keystore_password
       alias: keypair_alias
       aliaspass: private_key_password
+    # IdP configuration
     metadata:
+      # URL of IdP metadata
       url: https://aaiproxy.de.dariah.eu/idp/
+    # Hosted SP configuration
     sp:
+      # Metadata in filesystem (if available, otherwise generated)
       #metadataResource: /data/_srv/dariahsp/sp_metadata.xml
-      maxAuthAge: -1
+      # Maximum authentication lifetime in seconds
+      # maxAuthAge: 3600
       #entityId: ${baseUrl}
-      signMetadata: true
+      # Signature configuration
+      #signMetadata: true
       #signingMethods: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
       #digestMethods: http://www.w3.org/2001/04/xmlenc#sha256, http://www.w3.org/2001/04/xmlenc#sha512
+      #authnRequestSigned: true
+      #logoutRequestSigned: true
+      #wantsAssertionsSigned: true
+      #wantsResponsesSigned: false
+      # SAML SP protocol configuration
       #supportedProtocols: urn:oasis:names:tc:SAML:2.0:protocol
-      authnRequestSigned: truevv
-      logoutRequestSigned: true
-      wantsAssertionsSigned: true
-      wantsResponsesSigned: false
-      httpClientTimoutMs: 2000
+      # Timeout for interaction with configured IdP
+      #httpClientTimoutMs: 2000
+      # URL for redirection after RequiredAttributesException is raised
       attributesIncompleteRedirectUrl: https://auth.de.dariah.eu/cgi-bin/selfservice/ldapportal.pl
+      # Attribute groups for attribute mapping and required attribute definition
       attributeGroups:
+          # All attributes are required
         - 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
+              # A required value of the attribute can be defined
               #value: Terms_of_Use_germ_engl_v6.pdf
             - 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
+          # Optional attributes are typically used for mapping SAML attributes to ExtendedUserProfile propeties
+          #  like username, externalRoles below
         - check: OPTIONAL
           attributes:
             - friendlyName: mail

dariahsp-sample-boot/src/main/resources/application.yml

-contextPath: /dme
+contextPath: /contextpath
 #baseUrl: http://localhost:8080${contextPath:/}
-baseUrl: https://c105-229.cloud.gwdg.de${contextPath:/}
+baseUrl: https://externally.visible.example.com${contextPath:/}
 
 spring:
   mvc:
@@ -19,17 +19,17 @@ auth:
   salt: Qmwp4CO7LDkOUDouAcCcUqd9ZGNbRG5Jyr5lpntOuB9
   permissionHierarchy: ROLE_ADMINISTRATOR > ROLE_CONTRIBUTOR > ROLE_USER
   permissionDefinitions:
-    - permissionSet: ADMINISTRATOR
+    - permissionSet: ROLE_ADMINISTRATOR
       level: 100
       roleMappings: 
         local: ["application_admin"]
         saml: ["generic-search-admins"]       
-    - permissionSet: CONTRIBUTOR
+    - permissionSet: ROLE_CONTRIBUTOR
       level: 50
       roleMappings:
         local: ["application_contributor"]
         saml: ["generic-search-contributors"]
-    - permissionSet: USER
+    - permissionSet: ROLE_USER
       level: 10
       roleMappings:
         local: ["application_user"]