diff --git a/docs/features/experimental/application-service.md b/docs/features/experimental/application-service.md index 114e197..bd6f36b 100644 --- a/docs/features/experimental/application-service.md +++ b/docs/features/experimental/application-service.md @@ -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: '' + 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. diff --git a/docs/features/experimental/profile.md b/docs/features/experimental/profile.md new file mode 100644 index 0000000..f2b42a2 --- /dev/null +++ b/docs/features/experimental/profile.md @@ -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" +``` diff --git a/docs/features/profile.md b/docs/features/profile.md deleted file mode 100644 index f614629..0000000 --- a/docs/features/profile.md +++ /dev/null @@ -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" -``` diff --git a/docs/stores/firebase.md b/docs/stores/firebase.md index 8f8a585..6fea670 100644 --- a/docs/stores/firebase.md +++ b/docs/stores/firebase.md @@ -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 diff --git a/docs/stores/ldap.md b/docs/stores/ldap.md index 826ef9c..acdbdc9 100644 --- a/docs/stores/ldap.md +++ b/docs/stores/ldap.md @@ -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 diff --git a/docs/stores/rest.md b/docs/stores/rest.md index f08d4cc..4d6035f 100644 --- a/docs/stores/rest.md +++ b/docs/stores/rest.md @@ -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 | diff --git a/docs/stores/sql.md b/docs/stores/sql.md index 7c312df..ec16d33 100644 --- a/docs/stores/sql.md +++ b/docs/stores/sql.md @@ -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 diff --git a/docs/stores/synapse.md b/docs/stores/synapse.md index 37c2c97..b1d4ea2 100644 --- a/docs/stores/synapse.md +++ b/docs/stores/synapse.md @@ -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. diff --git a/docs/stores/wordpress.md b/docs/stores/wordpress.md index 545824a..a9eb8c9 100644 --- a/docs/stores/wordpress.md +++ b/docs/stores/wordpress.md @@ -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 diff --git a/docs/threepids/notification/template-generator.md b/docs/threepids/notification/template-generator.md index e67a21a..89ca0dc 100644 --- a/docs/threepids/notification/template-generator.md +++ b/docs/threepids/notification/template-generator.md @@ -19,6 +19,8 @@ threepid.medium.: 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.