This service is currently used for a single reason: generate JWT tokens with a given identity for a given room, so that users can use them to authenticate against LiveKit SFU.

It works by allowing a token obtained via the Matrix Client-Server API OpenID endpoint to be exchanged for a LiveKit JWT token which can be used to access a LiveKit SFU.

This functionality is defined by MSC4195: MatrixRTC using LiveKit backend.

Usage

This service is used when hosting the Element Call video conferencing application against a LiveKit backend.

Alongside this service, you will need the LiveKit SFU and for single page applications (SPA) the Element Call web application.

Installation

The available releases can be found here.

From docker image

docker run -e LIVEKIT_URL="ws://somewhere" -e LIVEKIT_KEY=devkey -e LIVEKIT_SECRET=secret -p 8080:8080 ghcr.io/element-hq/lk-jwt-service:0.1.2

From release file

Download the tar file from the URL on the release page:

wget https://github.com/element-hq/lk-jwt-service/archive/refs/tags/v0.1.1.tar.gz
tar -xvf v0.1.1.tar.gz
mv lk-jwt-service-0.1.1 lk-jwt-service

Build the service:

cd lk-jwt-service
go build -o lk-jwt-service .

To start the service locally:

LIVEKIT_URL="ws://somewhere" LIVEKIT_KEY=devkey LIVEKIT_SECRET=secret ./lk-jwt-service

Configuration

The service is configured via environment variables:

Variable	Description	Required
`LIVEKIT_URL`	The websocket URL of the LiveKit SFU	Yes
`LIVEKIT_KEY` or `LIVEKIT_KEY_FROM_FILE`	The API key or key file path for the LiveKit SFU	Yes
`LIVEKIT_SECRET` or `LIVEKIT_SECRET_FROM_FILE`	The secret or secret file path for the LiveKit SFU	Yes
`LIVEKIT_KEY_FILE`	file path to LiveKit SFU key-file format (`APIkey: secret`)	mutually exclusive with `LIVEKIT_KEY` and `LIVEKIT_SECRET`
`LIVEKIT_JWT_PORT`	The port the service listens on	No - defaults to 8080

Reverse Proxy and well-known requirements

A sample Caddy reverse proxy and well-known configuration (the MAS authenticaion is not required for lk-jwt-service but included for information.):

livekit-jwt.domain.tld {
        bind xx.xx.xx.xx
        reverse_proxy  localhost:8080
}

    handle /.well-known/matrix/* {
        header Content-Type application/json
        header Access-Control-Allow-Origin *  # Only needed if accessed via browser JS

        respond /client `{
            "m.homeserver": {"base_url": "https://matrix-domain.tld"},
            "org.matrix.msc4143.rtc_foci": [{
                "type": "livekit",
                "livekit_service_url": "https://livekit-jwt.domain.tld"
            }],
            "org.matrix.msc2965.authentication": {
                "issuer": "https://auth.domain.tld/",
                "account": "https://auth.domain.tld/account"
            }
        }`

The service is configured via environment variables:

Disable TLS verification

For testing and debugging (e.g. in the absence of trusted certificates while testing in a lab) you can disable TLS verification for the outgoing connection to the Matrix homeserver by setting the environment variable LIVEKIT_INSECURE_SKIP_VERIFY_TLS to YES_I_KNOW_WHAT_I_AM_DOING.