matrixdotorg/matrix-user-verification-service

Matrix用户验证服务

镜像概述和主要用途

Matrix用户验证服务是一个基于Open ID Connect令牌验证用户详情的服务。它主要用于验证Matrix用户的身份信息及房间成员资格，支持通过Open ID令牌确认用户身份，并检查用户是否为指定房间的成员，同时返回相关权限级别信息。

核心功能和特性

• 验证C2S Open ID令牌，通过S2S UserInfo端点实现
• 验证用户是否为指定房间的成员（目前仅支持Synapse，需管理员级令牌），除返回成员状态外，还会返回用户权限级别、房间权限默认值及事件所需权限

使用场景和适用范围

• Matrix生态系统中的用户身份验证场景
• 需要验证用户房间成员资格的应用（如权限控制、访问管理）
• 基于用户身份和房间成员资格的服务授权

使用方法和配置说明

依赖安装

bash
npm install

配置说明

将默认配置文件 .env.default 复制为 .env 并根据需要修改：

## 必选配置
# Homeserver客户端API管理员令牌（仅Synapse）
# 用于验证房间成员资格
UVS_ACCESS_TOKEN=foobar
# Homeserver客户端API URL
UVS_HOMESERVER_URL=https://matrix.org
# 禁用homeserver非私有IP范围检查。例如，若homeserver域名解析为私有IP，设为`true`
UVS_DISABLE_IP_BLACKLIST=true

## 可选配置
# 保护API的认证令牌
# 若设置此值，调用API端点时需添加请求头"Authorization: Bearer changeme"
UVS_AUTH_TOKEN=changeme
# 用于验证OpenID令牌的Matrix服务器名称。详见下文说明
# 默认为空，意味着将针对令牌中传递的任何Matrix服务器名称进行验证
UVS_OPENID_VERIFY_SERVER_NAME=matrix.org
# 服务监听地址
UVS_LISTEN_ADDRESS=127.0.0.1
# 服务监听端口
UVS_PORT=3000
# 日志级别，默认为'info'
# 可选值参考：https://github.com/winstonjs/winston#logging-levels
UVS_LOG_LEVEL=info

OpenID令牌验证

UVS可运行在单homeserver模式或配置为信任任何homeserver的OpenID令牌。默认情况下，信任令牌中提供的任何Matrix服务器名称。

若要禁用此功能并仅信任来自单个Matrix homeserver的OpenID令牌，可在 UVS_OPENID_VERIFY_SERVER_NAME 变量中设置该homeserver的Matrix服务器名称。注意，这是homeserver的服务器名称，而非客户端或联邦API的域名。

在两种模式下，UserInfo端点均通过常规服务器名称解析方式确定，因此即使homeserver未进行联邦，也可能需要 /.well-known/matrix/server 文件。若homeserver配置未设置 federation 监听器，可在与 client 监听器相同的端口上添加 openid 监听器。

房间成员资格验证目前仍限制为通过 UVS_HOMESERVER_CLIENT_API_URL 配置的单个homeserver客户端API进行。

API说明

认证方式

若设置了 UVS_AUTH_TOKEN，调用API时需提供如下授权头：

Authorization: Bearer <UVS_AUTH_TOKEN的值>

验证OpenID令牌

验证用户OpenID令牌。

请求：

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

请求体：

json
{
  "matrix_server_name": "domain.tld",
  "token": "用户提供的OpenID令牌"
}

成功响应：

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

失败响应：

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

验证OpenID令牌和房间成员资格

验证用户OpenID令牌及在指定房间的成员资格。

请求：

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

请求体：

json
{
  "matrix_server_name": "domain.tld",
  "room_id": "!foobar:domain.tld",
  "token": "用户提供的OpenID令牌"
}

成功响应：

json
{
  "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
  }
}

令牌无效的失败响应：

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

令牌有效但用户不在房间的失败响应：

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

运行服务

bash
npm start

开发模式

以监视模式运行：

bash
npm dev

许可证

Apache 2.0