Keycloak身份与本地.NET应用集成：用户同步及存储方案咨询

1. 是否需要同步本地用户到.NET身份数据库？ #

需要，但不需要每次登录都全量检查。因为你需要关联用户和业务数据，必须在本地数据库保留用户的关联标识。推荐在用户首次登录或用户信息发生变更时同步，而非每次登录重复校验。

具体实现可通过两种方式：

• 利用OpenID Connect的OnTokenValidated事件：Token验证通过后，提取Keycloak返回的用户UUID，查询本地数据库，不存在则创建；存在则对比关键信息是否更新，有变化则同步。
• 实现IClaimsTransformation：在Claims转换过程中完成用户同步逻辑，更贴合.NET身份认证的扩展机制。

2. 本地数据库应存储哪些用户内容？ #

核心原则是只存必要的、与业务强关联的、或Keycloak不常返回的信息，重点保留唯一不变的标识：

• Keycloak用户UUID：必须存储，作为本地用户的唯一标识（主键或外键），这是Keycloak中唯一不会变更的用户属性。
• 可选存储字段（根据业务需求）：
  • 用户名/邮箱：用于业务展示或快速查询，若Keycloak中变更，需同步更新本地记录。
  • 角色/权限快照：如果业务需要离线判断权限，可存储角色列表，但建议优先实时从Keycloak的Token或UserInfo端点获取，避免数据不一致。
  • 最后同步时间：用于判断下次登录时是否需要从Keycloak拉取最新信息。

3. 处理Keycloak用户数据变更的方案 #

由于Keycloak中除UUID外的信息可能变更，可通过以下方式保证本地数据一致性：

• 登录时校验：每次登录时，从Keycloak的UserInfo端点获取最新用户信息，对比本地存储的字段（如邮箱、用户名），有差异则更新本地记录。
• 监听Keycloak Webhook：配置Keycloak的用户事件Webhook，当用户信息变更时主动通知.NET应用，触发本地数据同步（实时性最高）。
• 定期同步：针对不敏感的信息，可每天/每周执行一次批量同步，拉取Keycloak用户列表更新本地数据。

代码示例：OnTokenValidated事件中同步用户 #

services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
    // 配置Keycloak的OpenID基础参数
    options.ClientId = "your-client-id";
    options.Authority = "https://your-keycloak-domain/auth/realms/your-realm";
    options.ResponseType = OpenIdConnectResponseType.Code;

    options.Events = new OpenIdConnectEvents
    {
        OnTokenValidated = async context =>
        {
            // 从Claims中提取Keycloak用户UUID（对应Keycloak默认的sub claim）
            var userId = context.Principal.FindFirstValue(ClaimTypes.NameIdentifier);
            
            // 查询本地用户仓库
            var localUser = await _userRepository.GetByKeycloakIdAsync(userId);
            if (localUser == null)
            {
                // 创建本地用户
                var email = context.Principal.FindFirstValue(ClaimTypes.Email);
                var username = context.Principal.FindFirstValue(ClaimTypes.Name);
                await _userRepository.CreateAsync(new LocalUser
                {
                    KeycloakId = userId,
                    Email = email,
                    UserName = username,
                    LastSyncTime = DateTime.UtcNow
                });
            }
            else
            {
                // 检查并更新变更字段
                var currentEmail = context.Principal.FindFirstValue(ClaimTypes.Email);
                if (localUser.Email != currentEmail)
                {
                    localUser.Email = currentEmail;
                    localUser.LastSyncTime = DateTime.UtcNow;
                    await _userRepository.UpdateAsync(localUser);
                }
            }
        }
    };
});

内容的提问来源于stack exchange，提问作者Sam