Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kamax-matrix/mxgwd

Policy Gateway for the Matrix REST API
https://github.com/kamax-matrix/mxgwd

Last synced: about 1 month ago
JSON representation

Policy Gateway for the Matrix REST API

Host: GitHub
URL: https://github.com/kamax-matrix/mxgwd
Owner: kamax-matrix
License: agpl-3.0
Archived: true
Created: 2018-03-11T00:36:57.000Z (almost 7 years ago)
Default Branch: master
Last Pushed: 2019-06-20T21:18:52.000Z (over 5 years ago)
Last Synced: 2024-08-01T12:29:51.831Z (4 months ago)
Language: Java
Homepage:
Size: 118 KB
Stars: 8
Watchers: 3
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-starred - kamax-matrix/mxgwd - Policy Gateway for the Matrix REST API (others)

README

# mxgwd - Matrix Policy Gateway Daemon
[![Build Status](https://travis-ci.org/kamax-matrix/mxgwd.svg?branch=master)](https://travis-ci.org/kamax-matrix/mxgwd)

---

**This project is no longer maintained.**

---

- [Overview](#overview)
- [Concepts](#concepts)
- [Getting Started](#getting-started)

## Overview
mxgwd is a gateway/reverse proxy for the Matrix REST API that aims to:
- Control what users can do with the Matrix API, depending on roles backed by an extended Identity server.
- Control what federation calls are allowed and from which server(s).
- Filter and/or transform endpoints.
- Perform additional actions for matching requests.

mxgwd wishes to be client and server agnostic, so policies can be consistently applied across implementations.

**THIS SOFTWARE IS CURRENTLY ALPHA, USAGE IN PRODUCTION IS DISCOURAGED**

## Concepts
mxgwd processes requests of configured hosts by matching endpoints/actions and processing ACLs linked to them.
If all applicable ACLs allow the request, it is then sent to the backend.

### Host
A host matches the `host:port` of the requested [URL](https://en.wikipedia.org/wiki/URL#Syntax).
There is currently no catch-all or wildcard/regexp support, and each host must be fully configured.

If a request's host is not matched in the configuration, it will be denied.

### Endpoint
An endpoint matches either:
- A well-identified action from the client, which is translated to the appropriate HTTP method and URL path
- A custom HTTP method and/or URL path

The following configuration keys are available:
- `action` to match Actions
- `method` to match HTTP methods
- `path` to match URL paths
- `match` to specify the type of matching on `path`
- `to` to overwrite the target URL defined at the host level

The following `match` type are available:
- `regexp`: perform a regexp match.
- Anything else (or key not present) will be used with `startsWith()` on the requested URL.

#### Actions
As actions represent well-defined messages and/or endpoints from the Matrix specification, the default Matrix naming scheme
has been kept which is based on the Java packages naming scheme.

The following actions are available:
- `m.room.create`: When a client attempts to create a room.

### ACL
ACLs are the rules applied to a matched endpoint, allowing or disallowing the request.

#### Types
##### Whitelist
With: `whitelist`

Grant access if the condition is true.

##### Blacklist
With: `blacklist`

Deny access if the condition is true.

#### Targets
##### HTTP Method
With: `method`

The HTTP method value (e.g. `GET`, `POST`, etc.), if the provided value is a match.

##### Authenticated user's groups
With: `group`

The groups the authenticated user belongs to, if the provided value matches one of the groups in the list.

This ACL type will deny access if one of the following conditions is true:
- The client did not provide an access token
- The Gateway is unable to validate the access token
- The access token is not valid
- The Gateway is not configured with an Identity server that supports the appropriate endpoint
- The Gateway is unable to retrieve the list of groups.

## Getting started
### Requirements
- Java JRE 8+ to run, JDK to build
- Reverse proxy for TLS/SSL support

### Reverse Proxy
By default, the gateway will listen on port `8000` of all IPs. To change, add the following line to your config file:
```yaml
server.port:
```

Configure your reverse proxy to send all `/_matrix` request to it.

#### Apache 2
In the `VirtualHost` section handling the domain with SSL, add the following and replace `0.0.0.0` by the internal
hostname/IP pointing to the gateway.

**This line MUST replace the one for the homeserver and MUST be after the one to your Identity server, if applicable.**
```
ProxyPass /_matrix http://0.0.0.0:8000/_matrix
```

Typical configuration would look like:
```

ServerName example.org
...

ProxyPreserveHost on
...

ProxyPass /_matrix http://localhost:8000/_matrix

```

#### nginx
In the `server` section handling the domain with SSL, add the following and replace `0.0.0.0` with the internal
hostname/IP pointing to gateway.

**This line MUST replace the one for the homeserver and MUST be after the one to your Identity server, if applicable.**

```
location /_matrix {
proxy_pass http://0.0.0.0:8000/_matrix;
}
```

Typical configuration would look like:
```
server {
listen 443 ssl;
server_name example.org;

...

location /_matrix {
proxy_pass http://localhost:8000/_matrix;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
```

### Configuration
Create a file `mxgwd.yaml` in your current working directory and add the appropriate options.
You can provide another path using the environment variable `MXGWD_CONFIG_FILE`.

Example of pseudo-config file:
```yaml
# Base configuration key
matrix.client.hosts:

# A host definition using the default protocol port
example.org:
to:
toIdentity:

# Endpoints definitions for this host
endpoints:
- action:
method:
path:
match:

# List of ACLs to be applied to this endpoint
acls:
- type:
target:
value:

# another ACL
- type: ...

# Another endpoint definition
- action: ...
to:
acls:
- ...
- ...

# Another host definition with a non-default port
example.org:8443:
...

# Another host definition with a hostname including a sub-domain
another.example.org:
...
```

---

Example of a working configuration:
```yaml
matrix.client.hosts:
synapse.localhost:
to: 'http://localhost:8008'
toIdentity: 'http://localhost:8090'

endpoints:
- path: '/_matrix/client/r0/profile/'
acls:
- type: 'whitelist'
target: 'method'
value: 'GET'

- action: 'm.room.create'
acls:
- type: 'whitelist'
target: 'group'
value: 'Admins'
```

This configuration will allow requests to `http://synapse.localhost` or `https://synapse.localhost`.
Requests will be forwarded to `http://localhost:8008`.
An extended Identity server at `http://localhost:8090` will be used for groups lookups.

Two endpoint definitions are given:
1. A generic endpoint matching all HTTP method and URL paths starting with `/_matrix/client/r0/profile/`.
One ACL is applied which will only allow requests using a HTTP `GET` method and deny all others.
This will restrict all clients (authenticated or not) to edit profiles (theirs or anyone else's).
2. A well-defined Matrix action of creating a room, which will be mapped to the appropriate HTTP method and URL path.
One ACL is applied which will only allow requests from authenticated users belonging to the `Admins` group.
This will restrict room creation to an opaque group provided by the extended Identity server.

All other requests to `synapse.localhost` will be allowed.

All other requests to any other host will be denied.

### Run
```bash
# Build mxgwd
./gradlew shadowJar

# You should create a configuration file if you haven't already

# Run mxgwd
java -jar build/libs/mxgwd.jar
```