More 3PID sessions configuration documentation
This commit is contained in:
Maxime Dor
82
docs/sessions/3pid-views.md
Normal file
82
docs/sessions/3pid-views.md
Normal file
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user