Synapse与Authentik集成中的用户匹配问题解决方案

背景介绍

在自托管Matrix服务器(Synapse)与Authentik身份提供程序(IdP)的集成过程中，许多管理员会遇到一个常见问题：即使用户名相同，通过Authentik登录时系统仍会创建新用户，而不是匹配现有用户。这种情况通常发生在从传统认证方式迁移到OIDC单点登录的过程中。

问题分析

当Synapse配置了OIDC提供商(如Authentik)后，系统默认行为是为每个通过OIDC登录的用户创建新账户。即使Authentik中的用户名与Synapse现有用户名完全一致，系统也不会自动关联这两个账户。这是因为Synapse需要明确的配置来允许现有用户通过OIDC登录。

关键配置参数

要解决这个问题，需要在Synapse的homeserver.yaml配置文件中正确设置以下参数：

enable_registration: false
oidc_providers:
    - idp_id: authentik
      allow_existing_users: true
      user_mapping_provider:
          config:
              localpart_template: "{{ user.preferred_username }}"

其中最重要的两个参数是：

1. allow_existing_users: true - 允许现有用户通过OIDC登录
2. enable_registration: false - 禁止自动创建新用户

解决方案步骤

1. 清理现有绑定：首先需要移除可能存在的旧绑定关系，这通常需要通过API调用将用户的external_ids设置为空数组。

2. 配置用户映射：确保user_mapping_provider中的localpart_template与Authentik返回的用户名属性(preferred_username)匹配。

3. 测试验证：配置完成后，使用现有用户凭据通过Authentik登录，验证是否能够正确关联到已有账户。

注意事项

• 确保Authentik中配置的preferred_username与Synapse中的用户名完全一致(包括大小写)
• 在修改配置后需要重启Synapse服务使更改生效
• 如果用户已经通过OIDC创建了重复账户，可能需要先删除这些账户才能正确关联

高级配置建议

对于更复杂的部署环境，可以考虑以下额外配置：

user_mapping_provider:
    config:
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"

这些配置可以确保用户的显示名称和电子邮件地址也能从Authentik同步到Synapse，实现更完整的用户信息集成。

通过以上配置，管理员可以顺利实现Synapse与Authentik的无缝集成，确保现有用户能够通过OIDC登录而不创建重复账户。