wso2~对接外部认证系统keycloak

在 WSO2 Identity Server 或 WSO2 API Manager 中，Identity Providers (身份提供者) 功能允许您将外部身份管理系统（如 Keycloak、Azure AD、Okta 等）集成到 WSO2 平台中，实现联合身份认证（Federation）。以下是使用 WSO2 Identity Providers 功能并与 Keycloak 对接的完整步骤：

---

1. Identity Providers 功能概述

• 作用：
  • 允许用户通过外部身份提供者（如 Keycloak）登录 WSO2 管理的应用或 API。
  • 支持协议：SAML 2.0、OAuth 2.0/OpenID Connect (OIDC)、WS-Federation 等。
• 典型场景：
  • 企业已有 Keycloak 用户体系，需与 WSO2 平台集成。
  • 需要将 WSO2 作为身份代理（Proxy），集中管理多个外部身份源。

---

2. 配置 Keycloak 作为外部 Identity Provider

步骤 1：在 Keycloak 中创建客户端（Client）

1. 登录 Keycloak 管理控制台
   
   访问 https://keycloak-host:port/auth/admin。

2. 创建 Realm（如果尚未创建）
   
   进入默认的 master Realm 或新建一个（如 my-realm）。

3. 创建客户端（Client）

   • 导航到 Clients → Create。
   • 设置：
     • Client ID：wso2-client（自定义名称）。
     • Client Protocol：openid-connect。
   • 保存后，进入客户端配置：
     • Valid Redirect URIs：添加 WSO2 的回调地址，如 https://wso2-host:9443/commonauth。
     • Web Origins：*（或限制为 WSO2 域名）。
     • 启用 Client authentication（生成客户端密钥）。

4. 记录关键信息

   • Client ID：wso2-client
   • Client Secret：在 Credentials 标签页中获取。
   • Keycloak Realm 的 OpenID Endpoint：
     
     https://keycloak-host:port/auth/realms/my-realm/.well-known/openid-configuration

---

步骤 2：在 WSO2 中配置 Keycloak 为外部 Identity Provider

1. 登录 WSO2 管理控制台
   
   访问 https://wso2-host:9443/carbon，使用管理员账号登录。

2. 创建新的 Identity Provider

   • 导航到 Main → Identity → Identity Providers → Add。
   • 输入名称（如 Keycloak-IDP）。

3. 配置 OpenID Connect 连接

   • 在 Federated Authenticators → OpenID Connect Configuration 中：
     • Enable：勾选。
     • Client ID：wso2-client（Keycloak 中创建的客户端 ID）。
     • Client Secret：Keycloak 客户端的密钥。
     • Authorization Endpoint：Keycloak 的 OIDC 授权端点（如 https://keycloak-host:port/auth/realms/my-realm/protocol/openid-connect/auth）。
     • Token Endpoint：Keycloak 的令牌端点（如 https://keycloak-host:port/auth/realms/my-realm/protocol/openid-connect/token）。
     • UserInfo Endpoint：用户信息端点（如 https://keycloak-host:port/auth/realms/my-realm/protocol/openid-connect/userinfo）。
     • JWKS Endpoint：JWKS 端点（如 https://keycloak-host:port/auth/realms/my-realm/protocol/openid-connect/certs）。
     • Callback URL：https://wso2-host:9443/commonauth（与 Keycloak 客户端配置一致）。

4. 配置声明映射（Claim Mapping）

   • 在 Claim Configuration 中，将 Keycloak 返回的用户属性（如 email、given_name）映射到 WSO2 的本地声明。
   • 示例：
     • Remote Claim：email → Local Claim：http://wso2.org/claims/emailaddress

5. 保存配置
   
   点击 Register 完成 Identity Provider 的创建。

---

3. 配置服务提供者（Service Provider）使用 Keycloak 认证

场景 1：WSO2 作为服务提供者（SP）

1. 创建服务提供者（Service Provider）

   • 导航到 Main → Identity → Service Providers → Add。
   • 输入名称（如 My-App）。

2. 配置联合认证

   • 在 Local & Outbound Authentication Configuration 中：
     • 选择 Federated Authentication。
     • 勾选刚创建的 Keycloak-IDP。
   • 可选：设置认证步骤（多因素认证）。

3. 配置声明映射
   
   确保服务提供者使用的声明与 Identity Provider 的映射一致。

---

场景 2：通过 WSO2 访问 API（API Manager 集成）

1. 在 API Manager 中启用 Keycloak 认证

   • 登录 API Publisher（https://wso2-host:9443/publisher）。
   • 创建或编辑 API → Runtime Configurations → Security。
   • 勾选 OAuth2 或 OpenID Connect，并关联 Keycloak-IDP。

2. 订阅 API 并测试

   • 用户通过 Keycloak 登录开发者门户，获取令牌后调用 API。

---

4. 验证集成

测试登录流程

1. 访问 WSO2 服务提供者的应用（如 https://wso2-host:9443/my-app）。
2. 点击 Login with Keycloak（或类似按钮）。
3. 重定向到 Keycloak 登录页面，输入 Keycloak 用户凭据。
4. 登录成功后，返回 WSO2 应用并验证用户信息。

---

5. 常见问题与调试

问题 1：证书验证失败

• 现象：SSLHandshakeException 或 unable to find valid certification path。
• 解决方案：
  • 将 Keycloak 的 SSL 证书导入 WSO2 的信任库：

    keytool -importcert -keystore <WSO2_HOME>/repository/resources/security/client-truststore.jks -alias keycloak -file keycloak.crt
    

问题 2：声明未正确映射

• 现象：用户属性（如邮箱、角色）未传递到 WSO2。
• 解决方案：
  • 检查 WSO2 Identity Provider 的 Claim Configuration，确保远程声明与 Keycloak 返回的 JSON 键匹配。
  • 在 Keycloak 客户端的 Mappers 中配置声明映射规则。

问题 3：重定向 URI 不匹配

• 现象：Invalid redirect_uri 错误。
• 解决方案：
  • 确保 WSO2 的 Callback URL 和 Keycloak 客户端的 Valid Redirect URIs 完全一致（包括协议、端口和路径）。

---

6. 高级配置（SAML 2.0 集成）

若需使用 SAML 代替 OIDC：

1. 在 Keycloak 中创建 SAML 客户端：
   • 客户端协议选择 SAML。
2. 在 WSO2 中配置 SAML 身份提供者：
   • 提供 Keycloak 的 SAML 元数据（Entity ID、SSO URL、证书等）。

---

总结

通过 WSO2 的 Identity Providers 功能，您可以无缝集成 Keycloak 作为外部身份源，实现以下能力：

• 联合登录：用户通过 Keycloak 登录 WSO2 管理的应用或 API。
• 集中管理：统一审计日志和策略控制。
• 协议支持：灵活选择 OIDC、SAML 等标准协议。

关键配置点：

1. Keycloak 客户端的正确配置（重定向 URI、协议）。
2. WSO2 Identity Provider 的端点与声明映射。
3. 服务提供者或 API 的联合认证设置。