diff --git a/docs/sessions/3pid-views.md b/docs/sessions/3pid-views.md new file mode 100644 index 0000000..cf3d115 --- /dev/null +++ b/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 +`text` 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 +`text` 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. diff --git a/docs/sessions/3pid.md b/docs/sessions/3pid.md index 0f3a0ba..23ac730 100644 --- a/docs/sessions/3pid.md +++ b/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! - - 'https://matrix.org' + configExample: # Not to be included in config! Already present in default config! + - 'https://example.org' threepid: medium: email: - connector: 'smtp' - generator: 'template' + connector: 'example1' # Not to be included in config! Already present in default config! + generator: 'example2' # Not to be included in config! Already present in default config! connectors: - smtp: - host: '' - port: 587 - tls: 1 - login: '' - password: '' + example1: generators: - template: # Not to be included in config! Already present in default config! - invite: 'classpath:email/invite-template.eml' - session: - validation: - local: 'classpath:email/validate-local-template.eml' - remote: 'classpath:email/validate-remote-template.eml' + example1: + key: "value" + example2: + key: "value" 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. diff --git a/docs/threepids/email/notifications/smtp-connector.md b/docs/threepids/email/notifications/smtp-connector.md new file mode 100644 index 0000000..8bff396 --- /dev/null +++ b/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' +``` diff --git a/docs/threepids/email/notifications/template-generator.md b/docs/threepids/email/notifications/template-generator.md new file mode 100644 index 0000000..04b6548 --- /dev/null +++ b/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. | diff --git a/src/main/groovy/io/kamax/mxisd/threepid/notification/email/EmailNotificationGenerator.java b/src/main/groovy/io/kamax/mxisd/threepid/notification/email/EmailNotificationGenerator.java index 85739db..e39afc0 100644 --- a/src/main/groovy/io/kamax/mxisd/threepid/notification/email/EmailNotificationGenerator.java +++ b/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("%VALIDATION_TOKEN%", session.getToken()); + templateBody = templateBody.replace("%NEXT_URL%", validationLink); return templateBody; } diff --git a/src/main/resources/email/validate-remote-template.eml b/src/main/resources/email/validate-remote-template.eml index b4888c6..5bcca92 100644 --- a/src/main/resources/email/validate-remote-template.eml +++ b/src/main/resources/email/validate-remote-template.eml @@ -81,7 +81,7 @@ pre, code {

If you would still like to continue, you will need to:

    -
  1. Go to your private Public registration process page
    2. +
  2. Go to your private Public registration process page
  3. Follow the registration process of the central Identity Server, usually another email with similar content
  4. Once your email address validated with the central Identity Server, click on "Continue" on page of step #1
  5. If your public association is found by our Identity server, the next step will be given to you.