Laravel使用aacotroneo/laravel-saml2对接Azure SSO登录事件不触发

DevOps 小满

2026-8-27

问题描述

在Laravel应用中使用aacotroneo/laravel-saml2包对接Azure AD实现SAML身份认证，已完成IDP配置，微软登录页面可正常展示，但无法从Azure返回的认证结果中获取用户信息。参考操作指引修改app/Providers/SAML2ServiceProvider.php文件，在boot方法中添加如下代码后，事件监听逻辑完全不执行，用户在微软侧完成登录后无业务逻辑响应，无法在Laravel应用中完成登录：

public function boot()
    {
        Event::listen('Aacotroneo\Saml2\Events\Saml2LogoutEvent', function ($event) {
            if (session_status() !== PHP_SESSION_ACTIVE) {
                session_start();
            }
            unset($_SESSION["id"]);
            session_destroy();
        });

        Event::listen('Aacotroneo\Saml2\Events\Saml2LoginEvent', function (Saml2LoginEvent $event) {
            $messageId = $event->getSaml2Auth()->getLastMessageId();
            // 需自行添加messageId防重放逻辑，拦截重放攻击
            if (session_status() == PHP_SESSION_ACTIVE) {
                session_start();
            }
            $user = $event->getSaml2User();
            Log::info("COOKIE_SAML ACTIVATED");
            $_COOKIE["COOKIE_SAML"] = 1;

            $userData = [
                'id' => $user->getUserId(),
                'attributes' => $user->getAttributes(),
                'assertion' => $user->getRawSamlAssertion()
            ];

            Log::info(json_encode($userData));

            $inputs = [
                'sso_user_id'  => self::getValue($user->getUserId()),
                // 'username'     => $user->getAttribute('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'),
                'email'        => self::getValue($user->getAttribute('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')),
                'first_name'   => self::getValue($user->getAttribute('http://schemas.microsoft.com/identity/claims/displayname')),
                'last_name'    => self::getValue($user->getAttribute('http://schemas.microsoft.com/identity/claims/displayname')),
            ];

            $user = UserAdecco::where('sso_user_id', $inputs['sso_user_id'])->where('email', $inputs['email'])->first();
            if (!$user) {
                $res = UserAdecco::store($inputs);
                if ($res['status'] == 'success') {
                    $user  = $res['data'];
                    $_SESSION["id"] = $user->id;
                    // Auth::guard('web')->login($user);
                } else {
                    Log::info('SAML USER Error ' . $res['messages']);
                }
            } else {
                $_SESSION["id"] = $user->id;
                // Auth::guard('web')->login($user);
            }
        });
    }

排查修复方案

按照以下优先级逐一排查，全部修复后事件即可正常触发：

检查自定义服务提供者注册状态。打开config/app.php，确认providers数组中已经注册自定义的SAML2ServiceProvider；Laravel 5.5+版本还要确认该提供者没有被加入dont-discover列表，导致框架启动时完全不加载该文件，事件绑定逻辑从一开始就没有执行。
给SAML回调路由添加CSRF豁免。打开app/Http/Middleware/VerifyCsrfToken.php，将saml2/*路径加入$except白名单。Azure AD回跳是POST请求，默认会被Laravel的CSRF中间件拦截返回419错误，请求根本到不了SAML包的认证逻辑，也不会触发登录事件，这是该场景下最高发的问题。
校验ACS路由配置一致性。打开config/saml2/[对应IDP标识].php（一般命名为config/saml2/azure.php），确认配置的ACS路由和Azure AD后台填写的Assertion Consumer Service回调地址完全匹配。该SAML包默认ACS路由格式为/saml2/[idp标识]/acs，地址不匹配时请求会直接404，不会走认证流程。
修正代码中session启动的逻辑错误。现有登录事件里的session判断写反了：if (session_status() == PHP_SESSION_ACTIVE) { session_start(); } 只有在session已经激活时才会调用启动方法，永远不会生效，要改成和登出事件一致的判断逻辑if (session_status() !== PHP_SESSION_ACTIVE) { session_start(); }。另外不要直接操作$_COOKIE和原生$_SESSION，优先使用Laravel自带的Session facade，避免和SAML包依赖的session中间件产生读写冲突，导致流程中断。
校验SAML签名配置匹配度。确认IDP配置文件中wantsMessagesSigned、wantsAssertionsSigned的开关值和Azure AD侧的签名要求完全一致，签名验证失败时SAML包会直接终止流程抛出错误，不会触发登录事件。可以临时将saml2配置的debug参数设为true，查看storage/logs/laravel.log中的具体报错快速定位。
确认命名空间引用正确。检查SAML2ServiceProvider文件头部，是否正确引入Event、Log、Saml2LoginEvent、Saml2LogoutEvent对应的类，类引用缺失会导致事件绑定本身报错，监听逻辑自然无法生效。

事件触发后还要注意属性映射问题：Azure AD返回的用户邮箱属性标识通常是http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress，不要误用name类型的claim去取邮箱，避免后续用户匹配逻辑失败。

内容的提问来源于stack exchange，提问作者user3101803