#身份联合

#什么是身份联合

身份联合 允许 Keycloak 将用户身份验证委托给外部身份源，而不是在内部管理凭据。Keycloak 充当代理：它针对外部系统对用户进行身份验证，然后向客户端应用程序颁发自己的令牌。

这使组织能够：

• 复用现有的企业身份存储（LDAP、Active Directory），而无需将用户迁移到 Keycloak。
• 允许用户使用社交账户（Google、GitHub、Microsoft）或企业 SSO 系统登录。
• 在单个 Keycloak Realm 下连接多个身份域。

#用户联合（LDAP / Active Directory）

用户联合 将 Keycloak 连接到现有的用户目录，例如 LDAP 或 Microsoft Active Directory。用户存储在外部目录中；Keycloak 从该目录读取用户数据，并且（可选）向其写入用户数据。

#工作原理

1. 用户登录时，Keycloak 会查询 LDAP/AD 服务器以对用户进行身份验证。
2. Keycloak 会在本地缓存用户属性以提升性能。
3. 用户数据（用户名、电子邮件、组成员关系）会按需或通过定期全量同步从目录同步到 Keycloak。

#关键配置选项

#LDAP Mapper

LDAP Mapper 定义了 LDAP 属性如何映射到 Keycloak 用户属性和角色。常见的 Mapper 包括：

• User Attribute Mapper：将 LDAP 属性（例如，mail）映射到 Keycloak 用户属性（例如，email）。
• Group Mapper：将 LDAP 组成员关系映射到 Keycloak 组或角色。
• Role Mapper：将 LDAP 组映射到 Keycloak Realm 角色或客户端角色。

#身份提供方（外部 IdP 代理）

身份提供方（Identity Provider，IdP）代理 将 Keycloak 连接到外部基于 OIDC 或 SAML 的身份提供方。Keycloak 作为外部 IdP 的 Service Provider（SP），同时作为自身客户端的 Identity Provider。

#支持的外部 IdP 类型

#代理流程

1. 用户在 Keycloak 登录页面上点击“使用 Google 登录”（或其他外部 IdP）。
2. Keycloak 将用户重定向到外部 IdP 进行身份验证。
3. 外部 IdP 对用户进行身份验证，并携带断言（OIDC ID token 或 SAML assertion）重定向回 Keycloak。
4. Keycloak 验证断言，创建或关联本地用户账户，并向客户端应用程序颁发自己的令牌。

#首次登录流程

当用户首次通过外部 IdP 进行身份验证时，Keycloak 会运行 首次登录流程，以确定如何处理该新用户：

• 创建新的本地用户：会自动创建一个新的 Keycloak 用户，并将其与外部身份关联。
• 关联到现有用户：如果本地已存在具有相同电子邮件的用户，Keycloak 可以提示用户进行确认并关联这些账户。
• 要求检查个人资料：会提示用户在继续之前检查或完善其个人资料。

首次登录流程可针对每个身份提供方进行完全自定义。

#在用户联合和 IdP 代理之间进行选择