Adapt AS doc to new format and capabilities
This commit is contained in:
@@ -1,25 +1,106 @@
|
||||
# Integration as an Application Service
|
||||
# Application Service
|
||||
**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.
|
||||
All the features requires a Homeserver capable of connecting [Application Services](https://matrix.org/docs/spec/application_service/r0.1.0.html).
|
||||
|
||||
## Email notification for Room invites by Matrix ID
|
||||
The following capabilities are provided in this features:
|
||||
- [Admin commands](#admin-commands)
|
||||
- [Email Notification about room invites by Matrix IDs](#email-notification-about-room-invites-by-matrix-ids)
|
||||
- [Auto-reject of expired 3PID invites](#auto-reject-of-expired-3pid-invites)
|
||||
|
||||
## Setup
|
||||
> **NOTE:** Make sure you are familiar with [configuration format and rules](../../configure.md).
|
||||
|
||||
Integration as an Application service is a three steps process:
|
||||
1. Create the baseline mxisd configuration to allow integration.
|
||||
2. Integrate with the homeserver.
|
||||
3. Configure the specific capabilities, if applicable.
|
||||
|
||||
### Configuration
|
||||
#### Variables
|
||||
Under the `appsvc` namespace:
|
||||
|
||||
| Key | Type | Required | Default | Purpose |
|
||||
|-----------------------|---------|----------|---------|----------------------------------------------------------------|
|
||||
| `enabled` | boolean | No | `true` | Globally enable/disable the feature |
|
||||
| `user.main` | string | No | `mxisd` | Localpart for the main appservice user |
|
||||
| `endpoint.toHS.url` | string | Yes | *None* | Base URL to the Homeserver |
|
||||
| `endpoint.toHS.token` | string | Yes | *None* | Token to use when sending requests to the Homeserver |
|
||||
| `endpoint.toAS.url` | string | Yes | *None* | Base URL to mxisd from the Homeserver |
|
||||
| `endpoint.toHS.token` | string | Yes | *None* | Token for the Homeserver to use when sending requests to mxisd |
|
||||
|
||||
#### Example
|
||||
```yaml
|
||||
appsvc:
|
||||
endpoint:
|
||||
toHS:
|
||||
url: 'http://localhost:8008'
|
||||
token: 'ExampleTokenToHS-ChangeMe!'
|
||||
toAS:
|
||||
url: 'http://localhost:8090'
|
||||
token: 'ExampleTokenToAS-ChangeMe!'
|
||||
```
|
||||
### Integration
|
||||
#### Synapse
|
||||
Under the `appsvc.registration.synapse` namespace:
|
||||
|
||||
| Key | Type | Required | Default | Purpose |
|
||||
|--------|--------|----------|--------------------|--------------------------------------------------------------------------|
|
||||
| `id` | string | No | `appservice-mxisd` | The unique, user-defined ID of this application service. See spec. |
|
||||
| `file` | string | Yes | *None* | If defined, the synapse registration file that should be created/updated |
|
||||
|
||||
##### Example
|
||||
```yaml
|
||||
appsvc:
|
||||
registration:
|
||||
synapse:
|
||||
file: '/etc/matrix-synapse/mxisd-appservice-registration.yaml'
|
||||
```
|
||||
|
||||
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/mxisd-appservice-registration.yaml'
|
||||
- ...
|
||||
```
|
||||
|
||||
Restart synapse when done to register mxisd.
|
||||
|
||||
#### Others
|
||||
See your Homeserver documentation on how to integrate.
|
||||
|
||||
## Capabilities
|
||||
### Admin commands
|
||||
#### Setup
|
||||
Min config:
|
||||
```yaml
|
||||
appsvc:
|
||||
feature:
|
||||
admin:
|
||||
allowedRoles:
|
||||
- '+aMatrixCommunity:example.org'
|
||||
- 'SomeLdapGroup'
|
||||
- 'AnyOtherArbitraryRoleFromIdentityStores'
|
||||
```
|
||||
|
||||
#### Use
|
||||
The following steps assume:
|
||||
- `matrix.domain` set to `example.org`
|
||||
- `appsvc.user.main` set to `mxisd` or not set
|
||||
|
||||
1. Invite `@mxisd:example.org` to a new direct chat
|
||||
2. Type `!help`
|
||||
|
||||
### Email Notification about room invites by Matrix IDs
|
||||
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
|
||||
#### 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
|
||||
#### 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'
|
||||
|
||||
synapseSql:
|
||||
enabled: false ## Do not use this line if Synapse is used as an Identity Store
|
||||
type: '<DB TYPE>'
|
||||
@@ -33,40 +114,8 @@ If you do not configure it, some placeholders will not be available in the notif
|
||||
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
|
||||
#### Test
|
||||
Invite a user which is part of your domain while an appropriate Identity store is used.
|
||||
|
||||
### Auto-reject of expired 3PID invites
|
||||
*TBC*
|
||||
|
Reference in New Issue
Block a user