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）

登录 Keycloak 管理控制台
访问 https://keycloak-host:port/auth/admin。
创建 Realm（如果尚未创建）
进入默认的 master Realm 或新建一个（如 my-realm）。
创建客户端（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（生成客户端密钥）。
记录关键信息
- 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

登录 WSO2 管理控制台
访问 https://wso2-host:9443/carbon，使用管理员账号登录。
创建新的 Identity Provider
- 导航到 Main → Identity → Identity Providers → Add。
- 输入名称（如 Keycloak-IDP）。
配置 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 客户端配置一致）。
配置声明映射（Claim Mapping）
- 在 Claim Configuration 中，将 Keycloak 返回的用户属性（如 email、given_name）映射到 WSO2 的本地声明。
- 示例：
  - Remote Claim：email → Local Claim：http://wso2.org/claims/emailaddress
保存配置
点击 Register 完成 Identity Provider 的创建。

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

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

创建服务提供者（Service Provider）
- 导航到 Main → Identity → Service Providers → Add。
- 输入名称（如 My-App）。
配置联合认证
- 在 Local & Outbound Authentication Configuration 中：
  - 选择 Federated Authentication。
  - 勾选刚创建的 Keycloak-IDP。
- 可选：设置认证步骤（多因素认证）。
配置声明映射
确保服务提供者使用的声明与 Identity Provider 的映射一致。

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

在 API Manager 中启用 Keycloak 认证
- 登录 API Publisher（https://wso2-host:9443/publisher）。
- 创建或编辑 API → Runtime Configurations → Security。
- 勾选 OAuth2 或 OpenID Connect，并关联 Keycloak-IDP。
订阅 API 并测试
- 用户通过 Keycloak 登录开发者门户，获取令牌后调用 API。

4. 验证集成

测试登录流程

访问 WSO2 服务提供者的应用（如 https://wso2-host:9443/my-app）。
点击 Login with Keycloak（或类似按钮）。
重定向到 Keycloak 登录页面，输入 Keycloak 用户凭据。
登录成功后，返回 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：

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

总结

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

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

关键配置点：

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