别再各写各的登录了！三步吃透 PHP (Yii2) 接入企业级 SSO 单点登录

原创

学习与分享
学习与分享

php的自我修养

2026年6月29日 08:30
广东

在小说阅读器读本章

去阅读

商务合作加微信：2230304070

学习与交流：PHP技术自我修养微信群

免费领取phpstorm正版激活码

获取地址：https://web.52shizhan.cn

以下文章正文

research and development

引言：为什么企业级应用需要 SSO？

在企业级应用群落中，孤立的账号体系是研发和用户的噩梦。当公司内部孵化出 OA、CRM、ERP 等多套系统时，如果用户在每个系统都需要重复输入账号密码，不仅体验极差，数据孤立、权限混乱、安全防线难以收拢等痛点也会接踵而至。

SSO（Single Sign-On，单点登录） 正是解决这一痛点的终极方案。它允许用户在多个互信的独立业务系统中，“一次登录，到处通行”。本文将带你从底层机制出发，用 PHP (Yii2 架构) 闭环实现一套工业级的 SSO 接入方案。

一、核心复盘：SSO 认证究竟是如何运转的？

要接入 SSO，首先必须搞懂它的核心账密置换凭证 —— Ticket（授权码/票据）机制。

我们以经典的中心化认证流为例，当用户访问受保护的业务系统时，其核心步骤如下：

路由拦截

：用户访问业务系统 B。业务系统发现用户未登录，通过 302 重定向将用户引导至 SSO 认证中心。
2. 凭证分发

：用户在 SSO 中心完成账号密码认证。SSO 中心验证通过后，生成一个短期内有效的随机凭证 Ticket，并带着这个 Ticket 重定向回业务系统 B 预留的回调地址。
3. 后台置换

：业务系统 B 拿到 Ticket 后，在后端（Server to Server）发起请求，向 SSO 中心验证 Ticket 的合法性，并换取当前用户的核心信息（如工号、邮箱、角色）。
4. 本地授信

：业务系统 B 验证无误，将用户信息写入本地 Session/Token，自动完成本地登录，页面正常响应。

二、实战演练：三步打通 PHP 的 SSO 接入

为了让代码更具规范性和扩展性，我们采用 接口定义服务实现控制器调用 的三层架构。

步骤 1：定义统一的 SSO 契约接口

首先，我们定义一个规范的接口。不论未来的 SSO 协议是基于标准的 OIDC、OAuth2 还是自研的 CAS，业务层只需要关心这两个核心动作。

<?php
namespace app\\components\\sso;

interface SSOLoginInterface
{
    /**
     * 获取单点登录中心授权跳转地址
     * @return string 跳转到SSO中心的完整URL
     */
    public function getAuthUrl(): string;

    /**
     * 通过回调获得的 Ticket 换取 SSO 中心的用户信息
     * @param string $ticket 认证票据
     * @return array 用户基础信息数组
     * @throws \\Exception 校验失败时抛出异常
     */
    public function getInfoFromTicket(string $ticket): array;
}

步骤 2：落地具体对接的 SSO 服务类

这里我们模拟一个具体的 CompanySSOService。在实际生产环境下，你可以将这里的 curl 请求替换为你们公司的 SSO 中心真实 API。

<?php
namespaceapp\\components\\sso;

useYii;
useyii\\base\\Component;

class CompanySSOService extends Component implements SSOLoginInterface
{
    public $ssoHost = 'https://sso.company.com';
    public $clientId = 'crm_system_01';
    public $clientSecret = 'sso_secret_key_xxxxxx';

    publicfunction getAuthUrl(): string
    {
        // 告诉SSO中心，认证成功后跳回本地的什么地方
        $callbackUrl = urlencode(Yii::$app->request->getHostInfo() . '/sso/callback');
        return\"{$this->ssoHost}/login?client_id={$this->clientId}&redirect_uri={$callbackUrl}\";
    }

    publicfunction getInfoFromTicket(string $ticket): array
    {
        $apiExhangeUrl = \"{$this->ssoHost}/api/verify-ticket\";

        // 发起后端安全的 Server to Server 请求，杜绝前端伪造
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $apiExhangeUrl);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
            'ticket' => $ticket,
            'client_id' => $this->clientId,
            'client_secret' => $this->clientSecret,
        ]));

        $response = curl_exec($ch);
        curl_close($ch);

        $result = json_decode($response, true);
        if (empty($result) || !isset($result['success']) || !$result['success']) {
            thrownew \\Exception(\"SSO凭证校验失败: \" . ($result['message'] ?? '未知错误'));
        }

        return $result['data']; // 返回格式统一包含: username, email, truename
    }
}

步骤 3：编写控制器，闭环回调登录逻辑

在 Yii2 框架中创建 SsoController。它是整个登录闭环的控制中枢，负责处理Ticket 的接收、新用户的自动常驻同步、以及本地会话的建立。

<?php
namespaceapp\\controllers;

useYii;
useyii\\web\\Controller;
useyii\\web\\BadRequestHttpException;
useapp\\models\\User;
useapp\\components\\sso\\CompanySSOService;

class SsoController extends Controller
{
    /**
     * @return CompanySSOService
     */
    privatefunction getSsoService()
    {
        // 建议在 Yii 的 components 中配置注入，此处快速实例化演示
        returnnew CompanySSOService();
    }

    /**
     * 登录入口触发表
     */
    publicfunction actionLogin()
    {
        // 如果本地已经有登录态，直接去后台首页
        if (!Yii::$app->user->isGuest) {
            return$this->redirect(['/dashboard']);
        }

        // 渲染登录引导页，将前端登录按钮的链接指向 SSO 授权页
        return$this->render('login', [
            'ssoUrl' => $this->getSsoService()->getAuthUrl()
        ]);
    }

    /**
     * SSO 中心认证通过后的核心回调接口
     */
    publicfunction actionCallback()
    {
        $ticket = Yii::$app->request->get('ticket');

        if (empty($ticket)) {
            thrownew BadRequestHttpException('授权失败：缺失关键 ticket 参数');
        }

        try {
            // 1. 去 SSO 中心洗白，拿回用户的真实资料
            $ssoUser = $this->getSsoService()->getInfoFromTicket($ticket);

            if (empty($ssoUser['username'])) {
                return$this->renderError('SSO 授信中心返回的用户数据不完整');
            }

            // 2. 统一格式规整（防止大小写引发的账号双胞胎问题）
            $username = strtolower(trim($ssoUser['username']));

            // 3. 检索本地账号仓库，不存在则自动激活“影子上游账号”
            $user = User::find()->where(['username' => $username])->one();

            if (!$user) {
                $user = new User();
                $user->username = $username;
                $user->email = $ssoUser['email'] ?? \"{$username}@company.com\";
                $user->realname = $ssoUser['truename'] ?? '新员工';
                $user->role = User::ROLE_MEMBER; // 默认赋予普通成员权限
                $user->status = User::STATUS_ACTIVE;

                if (!$user->save()) {
                    thrownew \\Exception(\"本地同步创建用户失败：\" . json_encode($user->getErrors()));
                }
            }

            // 4. 正式签发本地登录会话（Session/Cookie 保持 30 天）
            Yii::$app->user->login($user, 3600 * 24 * 30);

            // 5. 顺滑流转至系统内部首页
            return$this->redirect(['/dashboard']);

        } catch (\\Exception $e) {
            Yii::error(\"SSO登录异常挂起: \" . $e->getMessage(), __METHOD__);
            return$this->renderError($e->getMessage());
        }
    }

    privatefunction renderError($msg)
    {
        return$this->render('error', [
            'message' => $msg,
            'retryUrl' => $this->getSsoService()->getAuthUrl()
        ]);
    }
}