Add documentation for new AS Notification/Profile feature

This commit is contained in:
Max Dor
2018-10-10 01:02:40 +02:00
parent 407138e972
commit cdb56aec1f
10 changed files with 81 additions and 13 deletions

View File

@@ -1,6 +1,63 @@
# Integration as an Application Service
**WARNING: **These features are highly experimental. They can be removed or modified without notice.
Support is only available via a paid subscription or consultancy.
**WARNING:** These features are currently highly experimental. They can be removed or modified without notice.
All the features requires a Homeserver capable of connecting Application Services.
## 3PID notification for Matrix ID Room invites
*TBC*
## Email notification for Room invites by Matrix ID
This feature allows for users found in Identity stores to be instantly notified about Room Invites, regardless if their
account was already provisioned on the Homeserver.
### Requirements
- [Identity store(s)](../../stores/README.md) supporting the Profile feature
- At least one email entry in the identity store for each user that could be invited.
### Configuration
In your mxisd config file:
```yaml
matrix:
listener:
url: '<URL TO THE CS API OF THE HOMESERVER>'
localpart: 'appservice-mxisd'
token:
hs: 'HS_TOKEN_CHANGE_ME'
```
You can also change the default template of the notification using the `generic.matrixId` template option.
See [the Template generator documentation](../../threepids/notification/template-generator.md) for more info.
### Homeserver integration
#### Synapse
Create a new appservice registration file. Futher config will assume it is in `/etc/matrix-synapse/appservice-mxisd.yaml`
```yaml
id: "appservice-mxisd"
url: "http://127.0.0.1:8090"
as_token: "AS_TOKEN_CHANGE_ME"
hs_token: "HS_TOKEN_CHANGE_ME"
sender_localpart: "appservice-mxisd"
namespaces:
users:
- regex: "@*"
exclusive: false
aliases: []
rooms: []
```
`id`: An arbitrary unique string to identify the AS.
`url`: mxisd to reach mxisd. This ideally should be HTTP and not going through any reverse proxy.
`as_token`: Arbitrary value used by mxisd when talking to the HS. Not currently used.
`hs_token`: Arbitrary value used by synapse when talking to mxisd. Must match `token.hs` in mxisd config.
`sender_localpart`: Username for the mxisd itself on the HS. Default configuration should be kept.
`namespaces`: To be kept as is.
Edit your `homeserver.yaml` and add a new entry to the appservice config file, which should look something like this:
```yaml
app_service_config_files:
- '/etc/matrix-synapse/appservice-mxisd.yaml'
- ...
```
Restart synapse when done to register mxisd.
#### Others
See your Homeserver documentation on how to integrate.
### Test
Invite a user which is part of your domain while an appropriate Identity store is used.

View File

@@ -0,0 +1,12 @@
# Profile enhancement
**WARNING**: Alpha feature, not officially supported. Do not use.
This feature allows to enhance a profile query with more info than just Matrix ID and Display name, allowing for custom
applications to retrieve custom data not currently provided by synapse, per example.
## Configuration
### Reverse proxy
#### Apache
```apache
ProxyPassMatch "^/_matrix/client/r0/profile/([^/]+)$" "http://127.0.0.1:8090/_matrix/client/r0/profile/$1"
```

View File

@@ -1,9 +0,0 @@
# Profile enhancement
**WARNING**: Alpha feature not officially supported. Do not use.
## Configuration
### Reverse proxy
#### Apache
```apache
ProxyPassMatch "^/_matrix/client/r0/profile/([^/]+)$" "http://127.0.0.1:8090/_matrix/client/r0/profile/$1"
```

View File

@@ -7,6 +7,7 @@ https://firebase.google.com/
| Authentication | Yes |
| Directory | No |
| Identity | Yes |
| Profile | No |
## Requirements
This backend requires a suitable Matrix client capable of performing Firebase authentication and passing the following

View File

@@ -13,6 +13,7 @@ For NetIQ, replace all the `ldap` prefix in the configuration by `netiq`.
| Authentication | Yes |
| Directory | Yes |
| Identity | Yes |
| Profile | Yes |
## Getting started
### Base

View File

@@ -13,6 +13,7 @@ To integrate this backend with your webapp, you will need to implement three spe
| Authentication | Yes |
| Directory | Yes |
| Identity | Yes |
| Profile | No |
## Configuration
| Key | Default | Description |

View File

@@ -11,6 +11,7 @@
| Authentication | No |
| Directory | Yes |
| Identity | Yes |
| Profile | Yes |
Due to the implementation complexity of supporting arbitrary hashing/encoding mechanisms or auth flow, Authentication
will be out of scope of SQL Identity stores and should be done via one of the other identity stores, typically

View File

@@ -7,6 +7,7 @@ Synapse's Database itself can be used as an Identity store.
| Authentication | No |
| Directory | Yes |
| Identity | Yes |
| Profile | Yes |
Authentication is done by Synapse itself.

View File

@@ -10,6 +10,7 @@ Two types of connections are required for full support:
| Authentication | Yes |
| Directory | Yes |
| Identity | Yes |
| Profile | No |
## Requirements
- [Wordpress](https://wordpress.org/download/) >= 4.4

View File

@@ -19,6 +19,8 @@ threepid.medium.<YOUR 3PID MEDIUM HERE>:
validation:
local: '/path/to/validate-local-template.eml'
remote: 'path/to/validate-remote-template.eml'
generic:
matrixId: '/path/to/mxid-invite-template.eml'
```
The `template` generator is usually the default, so no further configuration is needed.