More 3PID sessions configuration documentation

docs/sessions/3pid-views.md

@@ -0,0 +1,82 @@
+# Web pages for the 3PID session processes
+You can customize the various pages used during a 3PID validation using [Thymeleaf templates](http://www.thymeleaf.org/).
+
+## Configuration
+```
+view:
+  session:
+    local:
+      onTokenSubmit:
+        success: '/path/to/session/local/tokenSubmitSuccess-page.html'
+        failure: '/path/to/session/local/tokenSubmitFailure-page.html'
+    localRemote:
+      onTokenSubmit:
+        success: '/path/to/session/localRemote/tokenSubmitSuccess-page.html'
+        failure: '/path/to/session/local/tokenSubmitFailure-page.html'
+    remote:
+      onRequest:
+        success: '/path/to/session/remote/requestSuccess-page.html'
+        failure: '/path/to/session/remote/requestFailure-page.html'
+      onCheck:
+        success: '/path/to/session/remote/checkSuccess-page.html'
+        failure: '/path/to/session/remote/checkFailure-page.html'
+```
+3PID session are divided into three config sections:
+- `local` for local-only 3PID sessions
+- `localRemote` for local 3PID sessions that can also be turned into remote sessions, if the user so desires
+- `remote` for remote-only 3PID sessions
+
+Each section contains a sub-key per support event. Finally, a `success` and `failure` key is available depending on the
+outcome of the request.
+
+## Local
+### onTokenSubmit
+This is triggered when a user submit a validation token for a 3PID session. It is typically visited when clicking the
+link in a validation email.
+
+The template should typically inform the user that the validation was successful and to go back in their Matrix client
+to finish the validation process.
+
+#### Placeholders
+No object/placeholder are currently available.
+
+## Local & Remote
+### onTokenSubmit
+This is triggered when a user submit a validation token for a 3PID session. It is typically visited when clicking the
+link in a validation email.
+
+The template should typically inform the user that their 3PID address will not yet be publicly/globally usable. In case
+they want to make it, they should start a Remote 3PID session with a given link or that they can go back to their Matrix
+client if they do not wish to proceed any further.
+
+#### Placeholders
+##### Success
+`<a th:href="${remoteSessionLink}">text</a>` can be used to display the link to start a Remote 3PID session.
+
+##### Failure
+No object/placeholder are currently available.
+
+## Remote
+### onRequest
+This is triggered when a user starts a Remote 3PID session, usually from a link produced in the `local.onTokenSubmit`
+view or in a remote-only 3PID notification.
+
+The template should typically inform the user that the remote creation was successful, followed the instructions sent by
+the remote Identity server and, once that is done, click a link to validate the session.
+
+#### Placeholders
+##### Success
+`<a th:href="${checkLink}">text</a>` can be used to display the link to validate the Remote 3PID session.
+
+##### Failure
+No object/placeholder are currently available.
+
+### onCheck
+This is triggered when a user attempts to inform the Identity server that the Remote 3PID session has been validated
+with the remote Identity server.
+
+The template should typically inform the user that the validation was successful and to go back in their Matrix client
+to finish the validation process.
+
+#### Placeholders
+No object/placeholder are currently available.

docs/sessions/3pid.md

@@ -114,29 +114,22 @@ Please refer to the full example config file to see which keys are mandatory and
 matrix:
   identity:
     servers:
-      root: # Not to be included in config! Already present in default config!
+      configExample: # Not to be included in config! Already present in default config!
-        - 'https://matrix.org'
+        - 'https://example.org'
 
 
 threepid:
   medium:
     email:
-      connector: 'smtp'
+      connector: 'example1' # Not to be included in config! Already present in default config! 
-      generator: 'template'
+      generator: 'example2' # Not to be included in config! Already present in default config!
       connectors:
-        smtp:
+        example1:
-          host: ''
-          port: 587
-          tls: 1
-          login: ''
-          password: ''
       generators:
-        template:  # Not to be included in config! Already present in default config!
+        example1:
-          invite: 'classpath:email/invite-template.eml'
+          key: "value"
-          session:
+        example2:
-            validation:
+          key: "value"
-              local: 'classpath:email/validate-local-template.eml'
-              remote: 'classpath:email/validate-remote-template.eml'
 
 session:
   policy:
@@ -157,7 +150,7 @@ session:
 ```
 
 `matrix.identity.servers` is the namespace to configure arbitrary list of Identity servers with a label as parent key.  
-In the above example, the list with label `configExample` contains a single server entry pointing to `https://matrix.org`.  
+In the above example, the list with label `configExample` contains a single server entry pointing to `https://example.org`.  
 
 **NOTE:** The server list is set to `root` by default and should typically NOT be included in your config.  
 
@@ -181,14 +174,18 @@ ID for each generator.
 - `connector` is given the ID of the connector to be used at runtime.
 - `generator` is given the ID of the generator to be used at runtime.
 
-In the above example, emails notifications are generated by the `template` module and sent with the `smtp` module.
+In the above example, emails notifications are generated by the `example2` module and sent with the `example1` module.  
+By default, `template` is used as generator and `smtp` as connector.
 
 mxisd comes with the following IDs built-in:  
 **Connectors**
 - `smtp` for a basic SMTP connector, attempting STARTLS by default.
+See [the dedicated document](https://github.com/kamax-io/mxisd/tree/master/docs/threepids/email/notifications/smtp-connector.md)
 
 **Generators**
 - `template`, loading content from template files, using built-in mxisd templates by default.
+See [the dedicated document](https://github.com/kamax-io/mxisd/tree/master/docs/threepids/email/notifications/template-generator.md)
+for further configuration and customization options.
 
 ---
 
@@ -207,6 +204,14 @@ Each scope is divided into three parts:
 If both `toLocal` and `toRemote` are enabled, the user will be offered to initiate a remote session once their 3PID
 locally validated.
 
+### Web views
+Once a user click on a validation link, it is taken to the Identity Server validation page where the token is submited.  
+If the session or token is invalid, an error page is displayed.  
+Workflow pages are also available for the remote 3PID session process.
+
+See [the dedicated document](https://github.com/kamax-io/mxisd/tree/master/docs/sessions/3pid-views.md)
+on how to configure/customize/brand those pages to your liking.
+
 ### Scenarios
 It is important to keep in mind that mxisd does not create bindings, irrelevant if a user added a 3PID to their profile.  
 Instead, when queried for bindings, mxisd will query Identity backends which are responsible to store this kind of information.

docs/threepids/email/notifications/smtp-connector.md

@@ -0,0 +1,17 @@
+# Email notifications - SMTP connector
+The following configuration items are available:
+```
+threepid:
+  medium:
+    email:
+      identity:
+        from: 'identityServerEmail@example.org'
+        name: 'My Identity Server'
+      connectors:
+        smtp:
+          host: 'smtpHostname'
+          port: 587
+          tls: 1 # 0 = no STARTLS, 1 = try, 2 = force
+          login: 'smtpLogin'
+          password: 'smtpPassword'
+```

docs/threepids/email/notifications/template-generator.md

@@ -0,0 +1,72 @@
+# Email notifications: Generate from templates
+To create notification content, you can use the `template` generator which will read MIME email body, including headers,
+encoded as UTF-8.
+
+Placeholders can be integrated into the templates to dynamically populate such content with relevant information like
+the 3PID that was requested, the domain of your Identity server, etc.
+
+Templates can be configured for each event that would send a notification to the end user. Events share a set of common
+placeholders and also have their own individual set of placeholders.
+
+## Configuration
+To configure paths to the various templates:
+```
+threepid:
+  medium:
+    email:
+      generators:
+        template:
+          invite: '/path/to/invite-template.eml'
+          session:
+            validation:
+              local: '/path/to/validate-local-template.eml'
+              remote: 'path/to/validate-remote-template.eml'
+```
+The `template` generator is the default, so no further configuration is needed.
+
+##  Global placeholders
+| Placeholder           | Purpose                                                                      |
+|-----------------------|------------------------------------------------------------------------------|
+| `%DOMAIN%`            | Identity server authoritative domain, as configured in `matrix.domain`       |
+| `%DOMAIN_PRETTY%`     | Same as `%DOMAIN%` with the first letter upper case and all other lower case |
+| `%FROM_EMAIL%`        | Email address configured in `threepid.medium.email.identity.from`            |
+| `%FROM_NAME%`         | Name configured in `threepid.medium.email.identity.name`                     |
+| `%RECIPIENT_MEDIUM%`  | Set as `email`                                                               |
+| `%RECIPIENT_ADDRESS%` | The address to which the notification is sent                                |
+
+## Events
+### Room invitation
+This template is used when someone is invited into a room using an email address which has no known bind to a Matrix ID.
+#### Placeholders
+| Placeholder           | Purpose                                                                                  |
+|-----------------------|------------------------------------------------------------------------------------------|
+| `%SENDER_ID%`         | Matrix ID of the user who made the invite                                                |
+| `%SENDER_NAME%`       | Display name of the user who made the invite, if not available/set, empty                |
+| `%SENDER_NAME_OR_ID%` | Display name of the user who made the invite. If not available/set, its Matrix ID        |
+| `%INVITE_MEDIUM%`     | The 3PID medium for the invite. Always set to `email`                                    |
+| `%INVITE_ADDRESS%`    | The 3PID address for the invite.                                                         |
+| `%ROOM_ID%`           | The Matrix ID of the Room in which the invite took place                                 |
+| `%ROOM_NAME%`         | The Name of the room in which the invite took place. If not available/set, empty         |
+| `%ROOM_NAME_OR_ID%`   | The Name of the room in which the invite took place. If not available/set, its Matrix ID |
+
+### Local validation of 3PID Session
+This template is used when to user which added their email address to their profile/settings and the session policy
+allows at least local sessions.  
+
+#### Placeholders
+| Placeholder          | Purpose                                                                              |
+|----------------------|--------------------------------------------------------------------------------------|
+| `%VALIDATION_LINK%`  | URL, including token, to validate the 3PID session.                                  |
+| `%VALIDATION_TOKEN%` | The token needed to validate the local session, in case the user cannot use the link |
+
+### Remote validation of 3PID Session
+This template is used when to user which added their email address to their profile/settings and the session policy only
+allows remote sessions.
+
+**NOTE:** 3PID session always require local validation of a token, even if a remote session is enforced.  
+One cannot bind a MXID to the session until the remote
+
+#### Placeholders
+| Placeholder  | Purpose                                                |
+|--------------|--------------------------------------------------------|
+| `%NEXT_URL%` | URL to continue with remote validation of the session. |

src/main/groovy/io/kamax/mxisd/threepid/notification/email/EmailNotificationGenerator.java

@@ -145,8 +145,7 @@ public class EmailNotificationGenerator implements IEmailNotificationGenerator {
                 "/submitToken?sid=" + session.getId() + "&client_secret=" + session.getSecret() +
                 "&token=" + session.getToken();
 
-        templateBody = templateBody.replace("%VALIDATION_LINK%", validationLink);
+        templateBody = templateBody.replace("%NEXT_URL%", validationLink);
-        templateBody = templateBody.replace("%VALIDATION_TOKEN%", session.getToken());
 
         return templateBody;
     }

src/main/resources/email/validate-remote-template.eml

@@ -81,7 +81,7 @@ pre, code {
 
                     <p>If you would still like to continue, you will need to:
                         <ol>
-                            <li>Go to your private <a href="%VALIDATION_LINK%">Public registration process page</a></li>
+                            <li>Go to your private <a href="%NEXT_URL%">Public registration process page</a></li>
                             <li>Follow the registration process of the central Identity Server, usually another email with similar content</li>
                             <li>Once your email address validated with the central Identity Server, click on "Continue" on page of step #1</li>
                             <li>If your public association is found by our Identity server, the next step will be given to you.</li>