如何在 PHP 应用中集成 Keycloak 单点登录（SSO）-php教程-PHP中文网

如何在 PHP 应用中集成 Keycloak 单点登录（SSO）

本文详解如何通过 openid connect 标准协议，在 php 应用中安全、可靠地集成 keycloak sso，涵盖环境准备、客户端配置、php sdk 选型、代码实现及关键注意事项。

本文详解如何通过 openid connect 标准协议，在 php 应用中安全、可靠地集成 keycloak sso，涵盖环境准备、客户端配置、php sdk 选型、代码实现及关键注意事项。

Keycloak 是一款功能完备、生产就绪的开源身份与访问管理（IAM）平台，原生支持 OpenID Connect（OIDC）和 OAuth 2.0 协议。虽然 Keycloak 官方未提供 PHP 语言官方适配器（Adapter），但因其严格遵循 OIDC 规范，任何符合标准的 PHP OIDC 客户端库均可与其无缝集成——无需定制协议或逆向工程。

✅ 推荐集成方案：使用成熟 OIDC 客户端库

目前社区主流且维护活跃的 PHP OIDC 客户端包括：

jumbojett/openid-connect-php（轻量、无依赖、文档清晰）
web-token/jwt-framework（企业级 JWT 处理，适合高安全要求场景）
firmanJS/sso-keycloak-php（专为 Keycloak 优化的封装示例，含完整登录/登出/Token 刷新流程）

⚠️ 注意：已归档项目 ataccama/keycloak-adapter-php 不再维护，不建议用于新项目。其设计耦合 Keycloak 旧版 Admin API，缺乏对 PKCE、JWKS 自动轮换、Token introspection 等现代安全特性的支持。

? 快速集成示例（基于 `jumbojett/openid-connect-php`）

安装 SDK

composer require jumbojett/openid-connect-php

Keycloak 后台配置（关键步骤）

btpanel phpsite 宝塔面板PHP网站
宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载
- 创建 Realm（如 myrealm）
- 新建 Client（如 php-app），Client Protocol 选择 openid-connect
- 设置 Access Type = confidential（推荐）或 public（仅限测试）
- 配置 Valid Redirect URIs（如 https://your-app.com/callback.php）
- 记录以下参数：Client ID、Client Secret（confidential 模式必需）、Realm Public Key、Auth Server URL（如 https://auth.example.com/auth）

PHP 登录逻辑（login.php）

<?php require_once 'vendor/autoload.php';

use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient(
    'https://auth.example.com/auth/realms/myrealm',
    'php-app',
    'your-client-secret-here'
);

// 启用 PKCE（增强授权码流程安全性）
$oidc->setResponseTypes(['code']);
$oidc->addScope(['openid', 'profile', 'email']);

if (!isset($_GET['code'])) {
    // 重定向至 Keycloak 登录页
    header('Location: ' . $oidc->getAuthorizationUrl());
    exit;
} else {
    // 交换授权码获取 Token
    $oidc->authenticate($_GET['code']);
    $token = $oidc->getAccessToken();
    $userInfo = $oidc->requestUserInfo();

    // 存储用户会话（示例）
    session_start();
    $_SESSION['access_token'] = $token;
    $_SESSION['user'] = $userInfo;
    header('Location: dashboard.php');
}
?>

受保护页面校验（dashboard.php）

<?php session_start();
if (!isset($_SESSION['access_token'])) {
    header('Location: login.php');
    exit;
}

// 可选：调用 /introspect 验证 Token 有效性（需 Keycloak Client 配置 Service Account）
// 或本地验证 JWT 签名（需 Realm Public Key）
?><h2>Welcome, = htmlspecialchars($_SESSION['user']['name'] ?? 'User') ?>!</h2>
<a href="logout.php">Logout</a>

⚠️ 关键注意事项

安全第一：生产环境务必启用 HTTPS；禁用 http://localhost 等非安全重定向 URI；始终校验 ID Token 的 iss、aud、exp 字段。
Token 管理：避免长期存储 Access Token；敏感操作建议调用 /introspect 接口实时验证（需开启 Client 的 Service Accounts）。
错误处理：捕获 OpenIDConnectClientException 并记录日志，避免向用户暴露敏感错误信息（如密钥泄露提示）。
会话同步：Keycloak 登出（/logout）不会自动销毁 PHP Session，需在回调中手动 session_destroy() 并重定向。

✅ 总结

集成 Keycloak 与 PHP 的本质是正确实现 OIDC 授权码流程（Authorization Code Flow with PKCE）。选择经过验证的第三方 OIDC 库，严格遵循 Keycloak 管理控制台的客户端配置指引，并注重 Token 校验与会话生命周期管理，即可构建健壮、合规的单点登录体系。建议优先参考 Keycloak 官方文档 — Securing Applications 和所选 SDK 的最新实践指南。