Matrix User Verification Service

Service to verify details of a user based on an Open ID Connect token.

Main features:

• Verifies a C2S Open ID token
  using the S2S UserInfo endpoint.
• Can verify user is a member in a given room (Synapse only currently, requires admin level token).
  In addition to returning membership status, returned will be user power level, the room power
  defaults and required power for events.

How to use

Dependencies

npm install

Configuration

Copy the default .env.default to .env and modify as needed.

## REQUIRED
# Homeserver client API admin token (synapse only)
# Required for the service to verify room membership
UVS_ACCESS_TOKEN=foobar
# Homeserver client API URL
UVS_HOMESERVER_URL=https://matrix.org
# Disable check for non private IP range of homeserver. E.g. set to `true` if your homeserver domain resolves to a private IP.
UVS_DISABLE_IP_BLACKLIST=true
## OPTIONAL
# Auth token to protect the API
# If this is set any calls to the provided API endpoints
# need have the header "Authorization: Bearer changeme".
UVS_AUTH_TOKEN=changeme
# Matrix server name to verify OpenID tokens against. See below section.
# Defaults to empty value which means verification is made against
# whatever Matrix server name passed in with the token.
UVS_OPENID_VERIFY_SERVER_NAME=matrix.org
# Listen address of the bot
UVS_LISTEN_ADDRESS=127.0.0.1
# Listen port of the bot
UVS_PORT=3000
# Log level, defaults to 'info'
# See choices here: https://github.com/winstonjs/winston#logging-levels
UVS_LOG_LEVEL=info

OpenID token verification

UVS can run in a single homeserver mode or be configured to trust any
homeserver OpenID token. Default is to trust the any Matrix server name
that is given with the OpenID token.

To disable this and ensure only OpenID tokens from a single Matrix homeserver
will be trusted, set the homeserver Matrix server name in the variable
UVS_OPENID_VERIFY_SERVER_NAME. Note, this is the server name of the homeserver,
not the client or federation API’s domain.

In either mode, the UserInfo endpoint
is determined by resolving server names in the usual way
so a /.well-known/matrix/server file may be needed even if the homeserver
isn’t otherwise federating. If the homeserver config doesn’t have the federation
listener setup, the openid listener can be added on the same port as the client
listener.

Room membership is still currently limited to be verified from a single
configured homeserver client API via UVS_HOMESERVER_URL.

API’s available

Authentication

If UVS_AUTH_TOKEN is set, you’ll need to provide an authorization header as follows:

Authorization: Bearer <value of UVS_AUTH_TOKEN>

Verify OpenID token

Verifies a user OpenID token.

POST /verify/user
Content-Type: application/json

Request body:

{
  "matrix_server_name": "domain.tld",
  "token": "secret OpenID token provided by the user"
}

Successful validation response:

{
  "results": {
    "user": true
  },
  "user_id": "@user:domain.tld"
}

Failed validation:

{
  "results": {
    "user": false
  },
  "user_id": null
}

Verify OpenID token and room membership

Verifies a user OpenID token and membership in a room.

POST /verify/user_in_room
Content-Type: application/json

Request body:

{
  "matrix_server_name": "domain.tld",
  "room_id": "!foobar:domain.tld",
  "token": "secret OpenID token provided by the user"
}

Successful validation response:

{
  "results": {
    "room_membership": true,
    "user": true
  },
  "user_id": "@user:domain.tld",
  "power_levels": {
    "room": {
      "ban": 50,
      "events": {
        "m.room.avatar": 50,
        "m.room.canonical_alias": 50,
        "m.room.history_visibility": 100,
        "m.room.name": 50,
        "m.room.power_levels": 100
      },
      "events_default": 0,
      "invite": 0,
      "kick": 50,
      "redact": 50,
      "state_default": 50,
      "users_default": 0
    },
    "user": 50
  }
}

Failed validation, in case token is not valid:

{
  "results": {
    "room_membership": false,
    "user": false
  },
  "user_id": null,
  "power_levels": null
}

In the token was validated but user is not in room, the failed response is:

{
  "results": {
    "room_membership": false,
    "user": true
  },
  "user_id": "@user:domain.tld",
  "power_levels": null
}

Running

npm start

Development

Run in watch mode.

npm run dev

License

Apache 2.0