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 的信任库：
    1. 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 的联合认证设置。