Matrix Authentication Support for Jitsi
This extends the collection with support for seamless authentication at the Jitsi server using Matrix OpenID. 1. New role for installing the [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) 2. Changes to Jitsi role: Installing Jitsi Prosody Mods and configuring Jitsi Auth 3. Changes to Jitsi and nginx-proxy roles: Serving .well-known/element/jitsi from jitsi.DOMAIN 4. We updated the Jitsi documentation on authentication and added documentation for the user verification service.
This commit is contained in:
jakicoll
@ -39,7 +39,17 @@ By default the Jitsi Meet instance does not require any kind of login and is ope
|
||||
|
||||
If you're fine with such an open Jitsi instance, please skip to [Apply changes](#apply-changes).
|
||||
|
||||
If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow this step to enable Jitsi's authentication and guests mode. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms.
|
||||
If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow the following steps to enable Jitsi's authentication and optionally guests mode.
|
||||
Currently, there are three supported authentication modes: 'internal' (default), 'matrix' and 'ldap'.
|
||||
|
||||
**Note:** Authentication is not tested via the playbook's self-checks.
|
||||
We therefore recommend that you manually verify if authentication is required by jitsi.
|
||||
For this, try to manually create a conference on jitsi.DOMAIN in your browser.
|
||||
|
||||
### Authenticate using Jitsi accounts (Auth-Type 'internal')
|
||||
The default authentication mechanism is 'internal' auth, which requires jitsi-accounts to be setup and is the recommended setup, as it also works in federated rooms.
|
||||
With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join.
|
||||
If a registered host is not yet present, guests are put on hold in individual waiting rooms.
|
||||
|
||||
Add these lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
|
||||
|
||||
@ -53,20 +63,35 @@ matrix_jitsi_prosody_auth_internal_accounts:
|
||||
password: "another-password"
|
||||
```
|
||||
|
||||
**Caution:** Accounts added here and subsquently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook.
|
||||
**Caution:** Accounts added here and subsequently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook.
|
||||
|
||||
**If you get an error** like this: "Error: Account creation/modification not supported.", it's likely that you had previously installed Jitsi without auth/guest support. In such a case, you should look into [Rebuilding your Jitsi installation](#rebuilding-your-jitsi-installation).
|
||||
|
||||
### Authenticate using Matrix OpenID (Auth-Type 'matrix')
|
||||
|
||||
### (Optional) LDAP authentication
|
||||
**Attention: Probably breaks jitsi in federated rooms and does not allow sharing conference links with guests.**
|
||||
|
||||
The default authentication mode of Jitsi is `internal`, however LDAP is also supported. An example LDAP configuration could be:
|
||||
Using this authentication type require a [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service).
|
||||
By default, this playbook creates and configures a user-verification-service to run locally, see [configuring-user-verification-service](configuring-playbook-user-verification-service.md).
|
||||
|
||||
To enable set this configuration at host level:
|
||||
|
||||
```yaml
|
||||
matrix_jitsi_enable_auth: true
|
||||
matrix_jitsi_auth_type: "matrix"
|
||||
```
|
||||
|
||||
For more information see also [https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification](https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification).
|
||||
|
||||
### Authenticate using LDAP (Auth-Type 'ldap')
|
||||
|
||||
An example LDAP configuration could be:
|
||||
|
||||
```yaml
|
||||
matrix_jitsi_enable_auth: true
|
||||
matrix_jitsi_auth_type: ldap
|
||||
matrix_jitsi_ldap_url: "ldap://ldap.DOMAIN"
|
||||
matrix_jitsi_ldap_base: "OU=People,DC=DOMAIN
|
||||
matrix_jitsi_ldap_base: "OU=People,DC=DOMAIN"
|
||||
#matrix_jitsi_ldap_binddn: ""
|
||||
#matrix_jitsi_ldap_bindpw: ""
|
||||
matrix_jitsi_ldap_filter: "uid=%u"
|
||||
@ -200,7 +225,19 @@ matrix_nginx_proxy_proxy_jitsi_additional_jvbs:
|
||||
Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo
|
||||
to route conferences too.
|
||||
|
||||
## (Optional) Enable Gravatar
|
||||
|
||||
In the default Jisti Meet configuration, gravatar.com is enabled as an avatar service. This results in third party request leaking data to gravatar.
|
||||
Since element already sends the url of configured Matrix avatars to Jitsi, we disabled gravatar.
|
||||
|
||||
To enable Gravatar set:
|
||||
|
||||
```yaml
|
||||
matrix_jitsi_disable_gravatar: false
|
||||
```
|
||||
|
||||
**Beware:** This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com).
|
||||
Besides metadata, this includes the matrix user_id and possibly the room identifier (via `referrer` header).
|
||||
|
||||
## Apply changes
|
||||
|
||||
|
||||
116
docs/configuring-playbook-user-verification-service.md
Normal file
116
docs/configuring-playbook-user-verification-service.md
Normal file
@ -0,0 +1,116 @@
|
||||
# Setting up Matrix User Verification Service (optional)
|
||||
|
||||
**[Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (hereafter: UVS) can only be installed after Matrix services are installed and running.**
|
||||
If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later.
|
||||
|
||||
Currently, the main purpose of this role is to allow Jitsi to authenticate matrix users and check if they are authorized to join a conference. Please refer to the documentation of the [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) to understand how it works.
|
||||
|
||||
**Note**: enabling Matrix User Verification Service, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled.
|
||||
|
||||
If the Jitsi server is also configured by this collection, all plugging of variables and secrets is handled in `group_vars/matrix_servers`.
|
||||
|
||||
__Some general concepts of UVS may be helpful to understand the rest, so here they are:__
|
||||
|
||||
UVS can be used to verify two claims:
|
||||
|
||||
* (A) Whether a given OpenID token is valid for a given server and
|
||||
* (B) whether a user is member of a given room and the corresponding PowerLevel
|
||||
|
||||
Verifying an OpenID token id done by finding the corresponding Homeserver via '.well-known/matrix/server' for the given domain.
|
||||
The configured `matrix_user_verification_service_uvs_homeserver_url` does **not** factor into this.
|
||||
By default, this collection only checks against `matrix_server_fqn_matrix`.
|
||||
Therefore, the request will be made against the public openid API for `matrix_server_fqn_matrix`.
|
||||
|
||||
Verifying RoomMembership and PowerLevel is done against `matrix_user_verification_service_uvs_homeserver_url` which is by default done via the docker network.
|
||||
UVS will verify the validity of the token beforehand though.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
In order to use UVS, an admin token for the configured homeserver must be supplied. For now this means configuring Synapse and creating the token before installing UVS.
|
||||
|
||||
## Enable
|
||||
|
||||
[Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) installation is disabled by default unless required by Jitsi (see group_vars/matrix_servers).
|
||||
You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
|
||||
|
||||
```yaml
|
||||
matrix_user_verification_service_enabled: true
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The only required configuration variable is `matrix_user_verification_service_uvs_access_token` (see below).
|
||||
|
||||
For a list of all configuration options see the role defaults [`roles/matrix-user-verification-service/defaults/main.yml`](../roles/custom/matrix-user-verification-service/defaults/main.yml).
|
||||
But be aware of all the plugging happening in `group_vars/matrix_servers`.
|
||||
|
||||
In the default configuration, the UVS Server is only reachable via the docker network, which is fine if e.g. Jitsi is also running in a container on the host.
|
||||
However, it is possible to expose UVS via setting `matrix_user_verification_service_container_http_host_bind_port`. Be aware that the normally used port (3000) may collide with Grafana.
|
||||
|
||||
### Access token
|
||||
|
||||
The Synapse Access Token is used to verify RoomMembership and PowerLevel against the configured homeserver_url (which is plugged in group_vars).
|
||||
|
||||
We recommend that you create a dedicated Matrix user for uvs (`uvs` is a good username).
|
||||
Follow our [Registering users](registering-users.md) guide to register a user with administration privileges.
|
||||
|
||||
You are required to specify an access token (belonging to this new user) for UVS to work.
|
||||
To get an access token for the UVS user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
|
||||
|
||||
```yaml
|
||||
matrix_user_verification_service_uvs_access_token: "YOUR ACCESS TOKEN HERE"
|
||||
```
|
||||
|
||||
### (Optional) Auth Token
|
||||
|
||||
It is possible to set an API Auth Token to restrict access to the UVS. If this is set, anyone making a request to UVS must provide it via the header "Authorization: Bearer TOKEN"
|
||||
|
||||
By default, the token will be derived from `matrix_homeserver_generic_secret_key` in `group_vars/matrix_servers`.
|
||||
To set your own Token, simply put the following in your host_vars.
|
||||
|
||||
```yaml
|
||||
matrix_user_verification_service_uvs_auth_token: "TOKEN"
|
||||
```
|
||||
|
||||
In case Jitsi is also managed by this collection and 'matrix' authentication in Jitsi is enabled, this collection will automatically configure Jitsi to use the configured auth token.
|
||||
|
||||
### (Optional) Federation
|
||||
|
||||
In theory (however currently untested), UVS can handle federation. Simply set:
|
||||
|
||||
```yaml
|
||||
matrix_user_verification_service_uvs_openid_verify_server_name: ~
|
||||
```
|
||||
|
||||
using host_vars to override the group_vars.
|
||||
|
||||
This will instruct UVS to verify the OpenID token against any domain given in a request.
|
||||
Homeserver discovery is done via '.well-known/matrix/server' of the given domain.
|
||||
|
||||
## Installation
|
||||
|
||||
After these variables have been set, please run the following command to re-run setup and to restart UVS:
|
||||
|
||||
```
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-user-verification-service,start
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
The configuration variable `UVS_LOG_LEVEL` can be set to:
|
||||
- warning
|
||||
- info
|
||||
- debug
|
||||
|
||||
## TLS Certificate Checking
|
||||
If the matrix Homeserver does not provide a valid TLS certificate, UVS will fail with the following error message:
|
||||
|
||||
> message: 'No response received: [object Object]',
|
||||
|
||||
This also applies to self-signed and let's encrypt staging certificates.
|
||||
|
||||
To disable certificate validation altogether (INSECURE! Not suitable for production use!) set: `NODE_TLS_REJECT_UNAUTHORIZED=0`
|
||||
|
||||
Alternatively, it is possible to inject your own CA certificates into the container by mounting a PEM file with additional trusted CAs into the container and pointing the `NODE_EXTRA_CA_CERTS` environment variable to it.
|
||||
Reference in New Issue
Block a user