Improve remote vetting certificate documentation

app/config/parameters.yml.dist

@@ -64,19 +64,30 @@ parameters:
     session_max_relative_lifetime: 600  # 10 minutes * 60 seconds
 
     # remote vetting
-    saml_rv_publickey: /src/Stepup-SelfService/src/Surfnet/StepupSelfService/SelfServiceBundle/Tests/Resources/test.crt
-    saml_rv_privatekey: /src/Stepup-SelfService/src/Surfnet/StepupSelfService/SelfServiceBundle/Tests/Resources/test.key
+
+    # For each remote vetting IdP we require some parameters.
     remote_vetting_idps:
+          # The display name
         - name: "IRMA"
+          # The logo that is displayed in the UI, should be a transparent PNG, preferably monochrome coloured
           logo: "/images/remote-vetting/irma.png"
+          # This discription is presented to the user choosing a remote vetting IdP, make sure this description amply
+          # describes the service.
           description:
             nl_NL: Met IRMA kunt u op een privacy-vriendelijke, beveiligde manier eigenschappen (attributen) van uzelf onthullen.
             en_GB: IRMA is a unique privacy-friendly identity platform for both authentication and signing.
+          # The slug is used in the URL to keep track of which remote vetting IdP was chosen by the user. Should not contain
+          # special characters, alphanumeric (lower case) characters and dashes are allowed.
           slug: irma
+          # The entity id of the remote vetting IdP
           entityId: https://selfservice.stepup.example.com/mock/metadata
+          # The SSO url of the remote vetting IdP
           ssoUrl: https://selfservice.stepup.example.com/second-factor/mock/sso
+          # Certificates for the remote vetting IdP
           certificateFile: "%saml_rv_publickey%"
           privateKey: "%saml_rv_privatekey%"
+          # The attribute mapping should map the institute IdP attributes with the ones received from the remote vetting
+          # IdP.
           attributeMapping:
             givenName: firstName
             surname: lastName
@@ -106,12 +117,16 @@ parameters:
           attributeMapping:
             givenName: firstName
             surname: lastName
+    # SelfService acts as the remote vetting SP, this metadata is used by the remote vetting IdP's to post their SAML
+    # responses to
     remote_vetting_sp:
       entityId: https://selfservice.stepup.example.com/saml/metadata
       assertionConsumerUrl: https://selfservice.stepup.example.com/second-factor/acs
       privateKey: '%saml_rv_privatekey%'
 
     identity_encryption_configuration:
+      # The public key used to encrypt the remote vetting user data. The private key matching this is used to decrypt,
+      # but is not configured in the application. The application can not be used to decrypt the data.
       encryption_public_key: |
         -----BEGIN CERTIFICATE-----
         MIIC6jCCAdICCQC9cRx5wiwWOjANBgkqhkiG9w0BAQsFADA3MRwwGgYDVQQDDBNT
@@ -131,4 +146,10 @@ parameters:
         qxaUW4nfb5DtK33bZBYMeyV6BZtSggc5Z/19aPx/s0bf6ySTUyB3lRqe5d3etCns
         4bGidORCl/6EZiXwVcPvmYmxYXqmuNWfps7isUvo
         -----END CERTIFICATE-----
-      storage_location: '%kernel.project_dir%/app/rv'
+
+      # The location on disk where the encrypted remote vetting user data is stored
+      storage_location: '%kernel.project_dir%/app/rv'
+
+    # For test, we use a mock remote vetting IdP, these certificates are used for that.
+    saml_rv_publickey: /src/Stepup-SelfService/src/Surfnet/StepupSelfService/SelfServiceBundle/Tests/Resources/test.crt
+    saml_rv_privatekey: /src/Stepup-SelfService/src/Surfnet/StepupSelfService/SelfServiceBundle/Tests/Resources/test.key