README

使用此库将 SAML 支持添加到您的 PHP 软件。忘记那些复杂的库，并使用 OneLogin Inc. 提供和支持的开源库。

3.X 分支与 PHP > 7.1 兼容，因此如果您正在使用该 PHP 版本，请使用它而不是 2.X 或 master 分支。

警告

版本 2.18.0 引入了 'rejectUnsolicitedResponsesWithInResponseTo' 设置参数，默认禁用，允许无效化未经请求的 SAMLResponse。此版本还将拒绝 SAMLResponse，如果 requestId 已提供给验证器但 SAMLResponse 不包含 InResponseTo 属性。此外，还引入了一个额外的设置参数 'destinationStrictlyMatches'，默认禁用，将强制 Destination URL 严格匹配处理 SAMLResponse 的地址。

版本 2.17.1 将 xmlseclibs 更新到 3.0.4 (CVE-2019-3465)，但 php-saml 由于实现了防止利用该漏洞的额外检查而没有直接受到影响。

版本 2.17.0 默认启用严格模式

将 php-saml 更新到 2.15.0，此版本包含与 XEE 攻击相关的安全补丁

php-saml 未受 201803-01 影响

将 php-saml 更新到 2.10.4，此版本包含与 LogoutRequests/LogoutResponses 上的签名验证相关的安全补丁

将 php-saml 更新到 2.10.0，此版本包含包含额外验证的安全补丁，这些验证将防止签名封装攻击。 CVE-2016-1000253

php-saml < v2.10.0 易受影响，允许签名封装！

安全指南

如果您认为您在此工具包中发现了安全漏洞，请在此处报告：https://www.onelogin.com/security，并提供描述。我们遵循负责任的披露指南，并与您合作迅速找到解决方案。

为什么要在我的软件中添加 SAML 支持？

SAML 是一个基于 XML 的用于网页浏览器单点登录的标准，由 OASIS 安全服务技术委员会定义。该标准自 2002 年以来一直存在，但最近由于其优势而越来越受欢迎。

易用性 - 从门户网站或内部网络一键访问、深度链接、消除密码和自动续订会话使用户的生活更轻松。
安全性 - 基于强数字签名进行身份验证和完整性，SAML 是一种安全的单点登录协议，世界上最大和最注重安全的企业的首选。
速度 - SAML 很快。只需一次浏览器重定向即可安全地将用户签入应用程序。
防止网络钓鱼 - 如果您没有应用程序的密码，您就不会被骗在假冒登录页面上输入它。
IT 友好 - SAML 简化了 IT 的工作，因为它将身份验证集中化，提供更大的可见性，并使目录集成更容易。
机会 - B2B 云提供商应支持 SAML，以促进其产品的集成。

一般描述

OneLogin的SAML PHP工具包允许您在PHP应用程序上构建一个服务提供者（SP），并将其连接到任何身份提供者（IdP）。

支持

单点登录（SSO）和单点注销（SLO，由SP和IdP启动）。
断言和nameId加密。
断言签名。
消息签名：AuthNRequest、LogoutRequest、LogoutResponses。
启用断言消费者服务端点。
启用单点注销服务端点。
发布SP元数据（可以进行签名）。

主要特性

saml2int - 实现了SAML 2.0 Web浏览器SSO配置文件。
无会话 - 忘掉SP和最终应用程序之间的常见冲突，工具包将委托会话到最终应用程序。
易于使用 - 开发者可以编写高级和低级代码，提供2个易于使用的API。
经过测试 - 严格测试。
流行 - OneLogin的客户使用它。许多PHP SAML插件使用它。

使用本指南在OneLogin中集成PHP工具包：[OneLogin SAML工具包PHP](https://developers.onelogin.com/page/saml-toolkit-for-php)

安装

依赖项

php >= 5.3.3和一些核心扩展，如php-xml、php-date、php-zlib。
openssl。安装openssl库。它处理x509证书。
mcrypt。如果您打算处理加密数据（如nameID、assertions），请安装该库及其php驱动程序。
gettext。安装该库及其php驱动程序。它处理翻译。
curl。如果您打算使用IdP元数据解析器，请安装该库及其php驱动程序。

由于PHP 5.3已官方不再支持，我们建议您使用较新的PHP版本。

代码

选项1. 从github克隆仓库

git clone git@github.com:onelogin/php-saml.git

选项2. 从github下载

工具包托管在github上。您可以从中下载

最新版本：https://github.com/onelogin/php-saml/releases/latest
主仓库：https://github.com/onelogin/php-saml/tree/master

将库的核心复制到php应用程序中。（每个应用程序都有自己的结构，因此请花时间找到最佳的PHP SAML工具包位置）。请参阅“将SAML支持添加到我的应用程序的指南”以获取更多信息。

请注意，压缩文件仅包含主要文件。如果您打算使用演示，请使用选项1。

选项3. Composer

工具包支持composer。您可以在https://packagist.org.cn/packages/onelogin/php-saml找到onelogin/php-saml包。

要将saml工具包导入到当前php项目中，请执行

composer require onelogin/php-saml

安装完成后，您将在vendor/文件夹中找到一个名为onelogin的新文件夹，其中包含php-saml。请确保您包含了由composer提供的自动加载器。它可以在vendor/autoload.php中找到。

重要在此选项中，x509证书必须存储在vendor/onelogin/php-saml/certs中，设置文件存储在vendor/onelogin/php-saml中。

当使用composer update或类似命令更新软件包时，您的设置可能会被删除。因此，强烈建议您不要使用设置文件，而是将设置作为数组直接传递给构造函数（本文件稍后解释）。如果不使用此方法，当使用composer update或类似命令更新软件包时，您的设置可能会被删除。

兼容性

此2.0版本包含新的库。工具包仍然兼容。

您之前用于添加SAML支持的旧代码将继续工作，只需加载lib/Saml文件夹中的文件。请注意，compatibility.php文件会这样做。

旧-demos文件夹包含使用旧版工具包（v.1）的旧应用的代码。请查看。

有时旧代码中类的名称可能略有不同，如果这是您的情况，您必须将它们更改为OneLogin_Saml_Settings、OneLogin_Saml_Response、OneLogin_Saml_AuthRequest或OneLogin_Saml_Metadata。

我们建议您将旧代码迁移到新版本，以便能够使用新库Saml2带来的新功能。

命名空间

如果您正在使用包含命名空间的框架（如Symfony）的库，请记住，必须通过在开头添加反斜杠（\）来调用类，例如，要使用静态方法getSelfURLNoQuery，请使用

\OneLogin_Saml2_Utils::getSelfURLNoQuery()

安全警告

在生产环境中，必须将strict参数设置为"true"，并且security下的signatureAlgorithm和digestAlgorithm必须设置为一个不同于SHA1的值（请参阅https://shattered.io/）。否则，您的环境不安全，容易受到攻击。

在生产环境中，我们还强烈建议在设置中注册IdP证书，而不是使用指纹方法。指纹是一个散列，因此最终容易受到碰撞攻击，可能导致签名验证绕过。其他SAML工具包已经弃用了该机制，我们为了兼容性以及测试环境的使用而维持它。

入门

了解工具包

新的OneLogin SAML工具包包含不同的文件夹（certs、endpoints、extlib、lib、demo等）和一些文件。

让我们先描述一下文件夹

`certs/`

SAML需要x509证书来签名和加密诸如NameID、Message、Assertion、Metadata等元素。

如果我们的环境需要签名或加密支持，此文件夹可能包含SP将使用的x509证书和私钥

sp.crt - SP的公共证书
sp.key - SP的私钥

或者我们也可以在设置文件中提供这些数据，在$settings['sp']['x509cert']和$settings['sp']['privateKey']。

有时我们可能需要在SP发布的元数据上添加签名，在这种情况下，我们可以使用之前提到的x509证书或使用新的x509证书：metadata.crt和metadata.key。

如果您正在进行密钥轮换过程并希望在服务提供商元数据上发布该x509证书，请使用sp_new.crt。

`extlib/`

此文件夹包含工具包使用的第三方库。目前仅使用xmlseclibs（作者Robert Richards，BSD许可），它处理xml元素的签名和加密。

`lib/`

此文件夹包含工具包的核心，即库

Saml文件夹包含工具包v.1的修改版本，允许旧代码继续工作。（此库提供以维持向后兼容性）。
Saml2文件夹包含稍后章节中描述的类和方法的新版本。

`doc/`

此文件夹包含工具包的API文档。

`endpoints/`

工具包有三个端点

metadata.php - SP元数据发布的位置。
acs.php - 断言消费者服务。处理SAML响应。
sls.php - 单一登出服务。处理登出请求和登出响应。

您可以使用工具包提供的文件或在添加SAML支持到您的应用程序时创建自己的端点文件。请注意，这些端点文件使用工具包基础文件夹的设置文件。

`locale/`

Locale文件夹包含一些翻译：en_US 和 es_ES 作为概念验证。目前没有翻译，但我们将最终本地化消息并支持多种语言。

其他重要文件

settings_example.php - 用于创建包含工具包基本配置信息的settings.php文件的模板。
advanced_settings_example.php - 用于创建包含与安全、联系人以及与SP关联的组织的额外配置信息的advanced_settings.php文件的模板。
_toolkit_loader.php - 此文件加载工具包库（SAML2库）。
compatibility - 导入此文件以使您的旧代码与新的工具包兼容（加载SAML库）。

杂项

tests/ - 包含工具包的单元测试。
demo1/ - 包含一个带有SAML支持的简单PHP应用程序的示例。阅读其中的Readme.txt以获取更多信息。
demo2/ - 包含另一个示例。
demo-old/ - 包含一个使用工具包旧版本代码的示例，以演示向后兼容性。

工作原理

设置

首先，我们需要配置工具包。SP的信息、IdP的信息，以及在某些情况下，配置有关签名和加密的高级安全问题。

有两种方式来提供设置信息

使用位于工具包基础文件夹中的settings.php文件。
使用设置数据的数组并将其直接提供给类的构造函数。

有一个模板文件settings_example.php，您可以复制此文件，重命名并编辑它。

<?php

$settings = array (
    // If 'strict' is True, then the PHP Toolkit will reject unsigned
    // or unencrypted messages if it expects them to be signed or encrypted.
    // Also it will reject the messages if the SAML standard is not strictly
    // followed: Destination, NameId, Conditions ... are validated too.
    'strict' => true,

    // Enable debug mode (to print errors).
    'debug' => false,

    // Set a BaseURL to be used instead of try to guess
    // the BaseURL of the view that process the SAML Message.
    // Ex http://sp.example.com/
    //    http://example.com/sp/
    'baseurl' => null,

    // Service Provider Data that we are deploying.
    'sp' => array (
        // Identifier of the SP entity  (must be a URI)
        'entityId' => '',
        // Specifies info about where and how the <AuthnResponse> message MUST be
        // returned to the requester, in this case our SP.
        'assertionConsumerService' => array (
            // URL Location where the <Response> from the IdP will be returned
            'url' => '',
            // SAML protocol binding to be used when returning the <Response>
            // message. OneLogin Toolkit supports this endpoint for the
            // HTTP-POST binding only.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
        ),
        // If you need to specify requested attributes, set a
        // attributeConsumingService. nameFormat, attributeValue and
        // friendlyName can be omitted
        "attributeConsumingService"=> array(
                "serviceName" => "SP test",
                "serviceDescription" => "Test Service",
                "requestedAttributes" => array(
                    array(
                        "name" => "",
                        "isRequired" => false,
                        "nameFormat" => "",
                        "friendlyName" => "",
                        "attributeValue" => array()
                    )
                )
        ),
        // Specifies info about where and how the <Logout Response> message MUST be
        // returned to the requester, in this case our SP.
        'singleLogoutService' => array (
            // URL Location where the <Response> from the IdP will be returned
            'url' => '',
            // SAML protocol binding to be used when returning the <Response>
            // message. OneLogin Toolkit supports the HTTP-Redirect binding
            // only for this endpoint.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // Specifies the constraints on the name identifier to be used to
        // represent the requested subject.
        // Take a look on lib/Saml2/Constants.php to see the NameIdFormat supported.
        'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
        // Usually x509cert and privateKey of the SP are provided by files placed at
        // the certs folder. But we can also provide them with the following parameters
        'x509cert' => '',
        'privateKey' => '',

        /*
         * Key rollover
         * If you plan to update the SP x509cert and privateKey
         * you can define here the new x509cert and it will be
         * published on the SP metadata so Identity Providers can
         * read them and get ready for rollover.
         */
        // 'x509certNew' => '',
    ),

    // Identity Provider Data that we want connected with our SP.
    'idp' => array (
        // Identifier of the IdP entity  (must be a URI)
        'entityId' => '',
        // SSO endpoint info of the IdP. (Authentication Request protocol)
        'singleSignOnService' => array (
            // URL Target of the IdP where the Authentication Request Message
            // will be sent.
            'url' => '',
            // SAML protocol binding to be used when returning the <Response>
            // message. OneLogin Toolkit supports the HTTP-Redirect binding
            // only for this endpoint.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // SLO endpoint info of the IdP.
        'singleLogoutService' => array (
            // URL Location of the IdP where SLO Request will be sent.
            'url' => '',
            // URL location of the IdP where the SP will send the SLO Response (ResponseLocation)
            // if not set, url for the SLO Request will be used
            'responseUrl' => '',            
            // SAML protocol binding to be used when returning the <Response>
            // message. OneLogin Toolkit supports the HTTP-Redirect binding
            // only for this endpoint.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // Public x509 certificate of the IdP
        'x509cert' => '',
        /*
         *  Instead of use the whole x509cert you can use a fingerprint in order to
         *  validate a SAMLResponse, but we don't recommend to use that
         *  method on production since is exploitable by a collision attack.
         *  (openssl x509 -noout -fingerprint -in "idp.crt" to generate it,
         *   or add for example the -sha256 , -sha384 or -sha512 parameter)
         *
         *  If a fingerprint is provided, then the certFingerprintAlgorithm is required in order to
         *  let the toolkit know which algorithm was used. Possible values: sha1, sha256, sha384 or sha512
         *  'sha1' is the default value.
         *
         *  Notice that if you want to validate any SAML Message sent by the HTTP-Redirect binding, you
         *  will need to provide the whole x509cert.
         */
        // 'certFingerprint' => '',
        // 'certFingerprintAlgorithm' => 'sha1',

        /* In some scenarios the IdP uses different certificates for
         * signing/encryption, or is under key rollover phase and
         * more than one certificate is published on IdP metadata.
         * In order to handle that the toolkit offers that parameter.
         * (when used, 'x509cert' and 'certFingerprint' values are
         * ignored).
         */
        // 'x509certMulti' => array(
        //      'signing' => array(
        //          0 => '<cert1-string>',
        //      ),
        //      'encryption' => array(
        //          0 => '<cert2-string>',
        //      )
        // ),
    ),
);

除了必需的设置数据（IdP、SP）之外，还可以定义其他信息。与基本信息的模板一样，在工具包的基础文件夹中还有一个模板，名为advanced_settings_example.php，您可以复制并重命名为advanced_settings.php。

<?php

$advancedSettings = array (

    // Compression settings
    'compress' => array (
        'requests' => true,
        'responses' => true
    ),
    // Security settings
    'security' => array (

        /** signatures and encryptions offered */

        // Indicates that the nameID of the <samlp:logoutRequest> sent by this SP
        // will be encrypted.
        'nameIdEncrypted' => false,

        // Indicates whether the <samlp:AuthnRequest> messages sent by this SP
        // will be signed.  [Metadata of the SP will offer this info]
        'authnRequestsSigned' => false,

        // Indicates whether the <samlp:logoutRequest> messages sent by this SP
        // will be signed.
        'logoutRequestSigned' => false,

        // Indicates whether the <samlp:logoutResponse> messages sent by this SP
        // will be signed.
        'logoutResponseSigned' => false,

        /* Sign the Metadata
         False || True (use sp certs) || array (
                                                    keyFileName => 'metadata.key',
                                                    certFileName => 'metadata.crt'
                                               )
                                      || array (
                                                    'x509cert' => '',
                                                    'privateKey' => ''
                                               )
        */
        'signMetadata' => false,

        /** signatures and encryptions required **/

        // Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest>
        // and <samlp:LogoutResponse> elements received by this SP to be signed.
        'wantMessagesSigned' => false,

        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be encrypted.
        'wantAssertionsEncrypted' => false,

        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be signed. [Metadata of the SP will offer this info]
        'wantAssertionsSigned' => false,

        // Indicates a requirement for the NameID element on the SAMLResponse
        // received by this SP to be present.
        'wantNameId' => true,

        // Indicates a requirement for the NameID received by
        // this SP to be encrypted.
        'wantNameIdEncrypted' => false,

        // Authentication context.
        // Set to false and no AuthContext will be sent in the AuthNRequest.
        // Set true or don't present this parameter and you will get an AuthContext 'exact' 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport'.
        // Set an array with the possible auth context values: array ('urn:oasis:names:tc:SAML:2.0:ac:classes:Password', 'urn:oasis:names:tc:SAML:2.0:ac:classes:X509').
        'requestedAuthnContext' => false,

        // Indicates if the SP will validate all received xmls.
        // (In order to validate the xml, 'strict' and 'wantXMLValidation' must be true).
        'wantXMLValidation' => true,

        // If true, SAMLResponses with an empty value at its Destination
        // attribute will not be rejected for this fact.
        'relaxDestinationValidation' => false,

        // If true, the toolkit will not raised an error when the Statement Element
        // contain atribute elements with name duplicated
        'allowRepeatAttributeName' => false,

        // If true, Destination URL should strictly match to the address to
        // which the response has been sent.
        // Notice that if 'relaxDestinationValidation' is true an empty Destintation
        // will be accepted.
        'destinationStrictlyMatches' => false,

        // If true, SAMLResponses with an InResponseTo value will be rejectd if not
        // AuthNRequest ID provided to the validation method.
        'rejectUnsolicitedResponsesWithInResponseTo' => false,

        // Algorithm that the toolkit will use on signing process. Options:
        //    'http://www.w3.org/2000/09/xmldsig#rsa-sha1'
        //    'http://www.w3.org/2000/09/xmldsig#dsa-sha1'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'
        // Notice that sha1 is a deprecated algorithm and should not be used
        'signatureAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',

        // Algorithm that the toolkit will use on digest process. Options:
        //    'http://www.w3.org/2000/09/xmldsig#sha1'
        //    'http://www.w3.org/2001/04/xmlenc#sha256'
        //    'http://www.w3.org/2001/04/xmldsig-more#sha384'
        //    'http://www.w3.org/2001/04/xmlenc#sha512'
        // Notice that sha1 is a deprecated algorithm and should not be used
        'digestAlgorithm' => 'http://www.w3.org/2001/04/xmlenc#sha256',

        // ADFS URL-Encodes SAML data as lowercase, and the toolkit by default uses
        // uppercase. Turn it True for ADFS compatibility on signature verification
        'lowercaseUrlencoding' => false,
    ),

    // Contact information template, it is recommended to supply a
    // technical and support contacts.
    'contactPerson' => array (
        'technical' => array (
            'givenName' => '',
            'emailAddress' => ''
        ),
        'support' => array (
            'givenName' => '',
            'emailAddress' => ''
        ),
    ),

    // Organization information template, the info in en_US lang is
    // recomended, add more if required.
    'organization' => array (
        'en-US' => array(
            'name' => '',
            'displayname' => '',
            'url' => ''
        ),
    ),
);

压缩设置允许您指示IdP是否可以接受使用gzip压缩的数据（'请求'和'响应'）。但如果我们将$deflate布尔参数提供给getRequest或getResponse方法，则它将优先于压缩设置。

在安全部分，您可以设置SP处理消息和断言的方式。联系IdP的管理员，询问IdP期望什么，并决定SP将处理哪些验证以及SP将有什么要求，并将这些要求传达给IdP的管理员。

一旦我们知道可以配置哪些类型的数据，让我们谈谈工具包中设置的处理方式。

所述设置文件（settings.php和advanced_settings.php）将由工具包加载，如果构造函数中没有提供其他设置信息的数组。让我们看看一些例子。

// Initializes toolkit with settings.php & advanced_settings files.
$auth = new OneLogin_Saml2_Auth();
//or
$settings = new OneLogin_Saml2_Settings();

// Initializes toolkit with the array provided.
$auth = new OneLogin_Saml2_Auth($settingsInfo);
//or
$settings = new OneLogin_Saml2_Settings($settingsInfo);

您可以在包含构造函数执行的文件中声明$settingsInfo，或者将其放在任何文件中，并加载该文件以获取我们以下示例中看到的数组。

<?php

require_once 'custom_settings.php';  // The custom_settings.php contains a
                                     // $settingsInfo array.

$auth = new OneLogin_Saml2_Auth($settingsInfo);

如何加载库

为了使用工具包库，您需要导入位于工具包基础文件夹中的_toolkit_loader.php文件。您可以以这种方式加载此文件

<?php

define("TOOLKIT_PATH", '/var/www/php-saml/');
require_once(TOOLKIT_PATH . '_toolkit_loader.php');

在这行之后，我们就能使用工具包中的类（以及它们的方法）（因为外部和 Saml2 库文件已经加载）。

如果你为 PHP-SAML 工具包的版本 1 编写了 SAML 应用的代码，你将需要加载 compatibility.php 文件，该文件加载 Saml 库文件，除了 _toolkit_loader.php。

该 Saml 库使用工具包最新版本的类和方法，同时保持旧过程的旧类、方法和工作流程以完成相同的事情。

我们强烈建议迁移旧代码并使用新工具包的新 API，因为有很多新功能你无法用旧代码处理。

启动单点登录

为了向 IdP 发送 AuthNRequest

<?php

define("TOOLKIT_PATH", '/var/www/php-saml/');
require_once(TOOLKIT_PATH . '_toolkit_loader.php');   // We load the SAML2 lib

$auth = new OneLogin_Saml2_Auth(); // Constructor of the SP, loads settings.php
                                   // and advanced_settings.php
$auth->login();   // Method that sent the AuthNRequest

根据 advanced_settings.php（'authnRequestsSigned'）中的安全信息，AuthNRequest 将以签名或未签名的方式发送。

然后 IdP 将将 SAML 响应返回给用户的客户端。客户端随后带着这些信息被转发到 SP 的属性消费者服务。如果我们没有在登录方法中设置 'url' 参数，并且我们使用工具包提供的默认 ACS（endpoints/acs.php），则 ACS 端点将重定向用户到启动 SSO 请求的文件。

我们可以设置一个 'returnTo' URL 来改变工作流程并将用户重定向到其他 PHP 文件。

$newTargetUrl = 'http://example.com/consume2.php';
$auth = new OneLogin_Saml2_Auth();
$auth->login($newTargetUrl);

登录方法可以接收其他六个可选参数

$parameters - 一个参数数组，它将被添加到 HTTP-Redirect 中的 GET 请求中。
$forceAuthn - 当为 true 时，AuthNRequest 将设置 ForceAuthn='true'
$isPassive - 当为 true 时，AuthNRequest 将设置 Ispassive='true'
$strict - 如果我们想保持（返回 URL 字符串）则为 true，如果我们要重定向则为 false
$setNameIdPolicy - 当为 true 时，AuthNRequest 将设置一个 nameIdPolicy 元素。
$nameIdValueReq - 向 IdP 指示应该进行认证的主题。

如果需要在未来的 SAMLResponse ID 和要发送的 AuthNRequest ID 之间进行匹配，则必须提取并保存该 AuthNRequest ID。

$ssoBuiltUrl = $auth->login(null, array(), false, false, true);
$_SESSION['AuthNRequestID'] = $auth->getLastRequestID();
header('Pragma: no-cache');
header('Cache-Control: no-cache, must-revalidate');
header('Location: ' . $ssoBuiltUrl);
exit();

SP 端点

与 SP 相关有三个重要的视图：元数据视图、ACS 视图和 SLS 视图。工具包在 endpoints 目录中提供了这些视图的示例。

SP 元数据 `endpoints/metadata.php`

此代码将根据我们在设置文件中提供的信息提供我们 SP 的 XML 元数据文件。

<?php

define("TOOLKIT_PATH", '/var/www/php-saml/');
require_once dirname(TOOLKIT_PATH.'/_toolkit_loader.php';

try {
    $auth = new OneLogin_Saml2_Auth();
    $settings = $auth->getSettings();
    $metadata = $settings->getSPMetadata();
    $errors = $settings->validateMetadata($metadata);
    if (empty($errors)) {
        header('Content-Type: text/xml');
        echo $metadata;
    } else {
        throw new OneLogin_Saml2_Error(
            'Invalid SP metadata: '.implode(', ', $errors),
            OneLogin_Saml2_Error::METADATA_SP_INVALID
        );
    }
} catch (Exception $e) {
    echo $e->getMessage();
}

getSPMetadata 将根据 advanced_settings.php（'signMetadata'）中的安全信息返回签名或不签名的元数据。

在暴露 XML 元数据之前，会进行一个检查以确保提供的信息是有效的。

除了使用 Auth 对象外，您还可以直接使用

$settings = new OneLogin_Saml2_Settings($settingsInfo, true);

来获取设置对象，并通过 true 参数避免 IdP 设置验证。

属性消费者服务（ACS） `endpoints/acs.php`

此代码处理 IdP 通过用户的客户端转发给 SP 的 SAML 响应。

<?php

session_start();  // IMPORTANT: This is required in order to be able
                  // to store the user data in the session.

define("TOOLKIT_PATH", '/var/www/php-saml/');
require_once dirname(TOOLKIT_PATH.'/_toolkit_loader.php';

$auth = new OneLogin_Saml2_Auth();

if (isset($_SESSION) && isset($_SESSION['AuthNRequestID'])) {
    $requestID = $_SESSION['AuthNRequestID'];
} else {
    $requestID = null;
}

$auth->processResponse($requestID);
unset($_SESSION['AuthNRequestID']);

$errors = $auth->getErrors();

if (!empty($errors)) {
    echo '<p>', implode(', ', $errors), '</p>';
    exit();
}

if (!$auth->isAuthenticated()) {
    echo "<p>Not authenticated</p>";
    exit();
}

$_SESSION['samlUserdata'] = $auth->getAttributes();
$_SESSION['samlNameId'] = $auth->getNameId();
$_SESSION['samlNameIdFormat'] = $auth->getNameIdFormat();
$_SESSION['samlNameidNameQualifier'] = $auth->getNameIdNameQualifier();
$_SESSION['samlNameidSPNameQualifier'] = $auth->getNameIdSPNameQualifier();
$_SESSION['samlSessionIndex'] = $auth->getSessionIndex();

if (isset($_POST['RelayState']) && OneLogin_Saml2_Utils::getSelfURL() != $_POST['RelayState']) {
    $auth->redirectTo($_POST['RelayState']);
}

$attributes = $_SESSION['samlUserdata'];
$nameId = $_SESSION['samlNameId'];

echo '<h1>Identified user: '. htmlentities($nameId) .'</h1>';

if (!empty($attributes)) {
    echo '<h2>'._('User attributes:').'</h2>';
    echo '<table><thead><th>'._('Name').'</th><th>'._('Values').'</th></thead><tbody>';
    foreach ($attributes as $attributeName => $attributeValues) {
        echo '<tr><td>' . htmlentities($attributeName) . '</td><td><ul>';
        foreach ($attributeValues as $attributeValue) {
            echo '<li>' . htmlentities($attributeValue) . '</li>';
        }
        echo '</ul></td></tr>';
    }
    echo '</tbody></table>';
} else {
    echo _('No attributes found.');
}

SAML 响应被处理并检查是否存在错误。它还验证用户是否已认证并将用户数据存储在会话中。

此时有两种可能的替代方案

如果没有提供 RelayState，我们可以在该视图中显示用户数据或以我们想要的方式显示。
如果提供了 RelayState，则进行重定向。

注意，我们在重定向之前在会话中保存了用户数据，以便在 RelayState 视图中可用。

`getAttributes` 方法

为了检索属性，我们可以使用

$attributes = $auth->getAttributes();

使用此方法，我们可以获得SAML响应断言中由IdP提供的所有用户数据。

如果我们执行 print_r($attributes)，我们可能会得到

Array
(
    [cn] => Array
        (
            [0] => John
        )
    [sn] => Array
        (
            [0] => Doe
        )
    [mail] => Array
        (
            [0] => john.doe@example.com
        )
    [groups] => Array
        (
            [0] => users
            [1] => members
        )
)

每个属性名称都可以用作 $attributes 中的索引来获取值。每个属性值都是一个数组——单值属性是一个只有一个元素的数组。

以下代码是等效的

$attributes = $auth->getAttributes();
print_r($attributes['cn']);

print_r($auth->getAttribute('cn'));

在尝试获取属性之前，请检查用户是否已认证。如果用户未认证或SAML断言中没有属性，则将返回一个空数组。例如，如果我们调用 getAttributes 在 $auth->processResponse 之前，则 getAttributes() 将返回一个空数组。

单点退出服务（SLS） `endpoints/sls.php`

此代码处理退出请求和退出响应。

<?php

session_start();  // IMPORTANT: This is required in order to be able
                  // to close the user session.

define("TOOLKIT_PATH", '/var/www/php-saml/');
require_once dirname(TOOLKIT_PATH.'/_toolkit_loader.php';

$auth = new OneLogin_Saml2_Auth();

if (isset($_SESSION) && isset($_SESSION['LogoutRequestID'])) {
    $requestID = $_SESSION['LogoutRequestID'];
} else {
    $requestID = null;
}

$auth->processSLO(false, $requestID);

$errors = $auth->getErrors();

if (empty($errors)) {
    echo 'Sucessfully logged out';
} else {
    echo implode(', ', $errors);
}

如果SLS端点收到退出响应，则验证响应并可以关闭会话

// part of the processSLO method

$logoutResponse = new OneLogin_Saml2_LogoutResponse($this->_settings, $_GET['SAMLResponse']);
if (!$logoutResponse->isValid($requestId)) {
    $this->_errors[] = 'invalid_logout_response';
} else if ($logoutResponse->getStatus() !== OneLogin_Saml2_Constants::STATUS_SUCCESS) {
    $this->_errors[] = 'logout_not_success';
} else {
    if (!$keepLocalSession) {
        OneLogin_Saml2_Utils::deleteLocalSession();
    }
}

如果SLS端点收到退出请求，则验证请求，关闭会话并向IdP的SLS端点发送退出响应。

// part of the processSLO method

$decoded = base64_decode($_GET['SAMLRequest']);
$request = gzinflate($decoded);
if (!OneLogin_Saml2_LogoutRequest::isValid($this->_settings, $request)) {
    $this->_errors[] = 'invalid_logout_request';
} else {
    if (!$keepLocalSession) {
        OneLogin_Saml2_Utils::deleteLocalSession();
    }

    $inResponseTo = $request->id;
    $responseBuilder = new OneLogin_Saml2_LogoutResponse($this->_settings);
    $responseBuilder->build($inResponseTo);
    $logoutResponse = $responseBuilder->getResponse();

    $parameters = array('SAMLResponse' => $logoutResponse);
    if (isset($_GET['RelayState'])) {
        $parameters['RelayState'] = $_GET['RelayState'];
    }

    $security = $this->_settings->getSecurityData();
    if (isset($security['logoutResponseSigned']) && $security['logoutResponseSigned']) {
        $signature = $this->buildResponseSignature($logoutResponse, $parameters['RelayState'], $security['signatureAlgorithm']);
        $parameters['SigAlg'] = $security['signatureAlgorithm'];
        $parameters['Signature'] = $signature;
    }

    $this->redirectTo($this->getSLOurl(), $parameters);
}

如果您不是使用默认的PHP会话，或者需要其他手动销毁会话的方法，您可以将回调方法传递给 processSLO 方法作为第四个参数

$keepLocalSession = False;
$callback = function () {
    // Destroy user session
};

$auth->processSLO($keepLocalSession, null, false, $callback);

如果我们不希望 processSLO 销毁会话，请将一个true参数传递给 processSLO 方法

$keepLocalSession = True;
$auth->processSLO($keepLocalSession);

启动SLO

为了向IdP发送退出请求

<?php

define("TOOLKIT_PATH", '/var/www/php-saml/');
require_once(TOOLKIT_PATH . '_toolkit_loader.php');

$auth = new OneLogin_Saml2_Auth();

$auth->logout();   // Method that sent the Logout Request.

此外，还可以设置八个可选参数

$returnTo - 用户登出后应返回的目标URL。
$parameters - 需要添加到GET中的额外参数。
$name_id - 将用于构建退出请求。如果未设置 name_id 参数并且认证对象处理了包含 NameId 的SAML响应，则将使用此 NameId。
$session_index - 识别用户会话的会话索引。
$stay - 如果我们想要保持（返回URL字符串）则设置为True，如果要重定向则设置为False。
$nameIdFormat - 将在退出请求中设置NameID格式。
$nameIdNameQualifier - 将在退出请求中设置NameID名称限定符。
$nameIdSPNameQualifier - 将在退出请求中设置NameID SP名称限定符。

退出请求将根据 advanced_settings.php（'logoutRequestSigned'）中的安全信息进行签名或未签名。

IdP将通过用户的客户端将退出响应返回到SP的单点退出服务。如果我们没有在退出方法中设置 'url' 参数并使用工具包提供的默认SLS（endpoints/sls.php），则SLS端点将重定向用户到启动SLO请求的文件。

我们可以设置一个 'returnTo' URL来更改工作流程并将用户重定向到其他PHP文件。

$newTargetUrl = 'http://example.com/loggedOut.php';
$auth = new OneLogin_Saml2_Auth();
$auth->logout($newTargetUrl);

具有所有参数的更复杂的登出

$auth = new OneLogin_Saml2_Auth();
$returnTo = null;
$paramters = array();
$nameId = null;
$sessionIndex = null;
$nameIdFormat = null;
$nameIdNameQualifier = null;
$nameIdSPNameQualifier = null;

if (isset($_SESSION['samlNameId'])) {
    $nameId = $_SESSION['samlNameId'];
}
if (isset($_SESSION['samlSessionIndex'])) {
    $sessionIndex = $_SESSION['samlSessionIndex'];
}
if (isset($_SESSION['samlNameIdFormat'])) {
    $nameIdFormat = $_SESSION['samlNameIdFormat'];
}
if (isset($_SESSION['samlNameIdNameQualifier'])) {
    $nameIdNameQualifier = $_SESSION['samlNameIdNameQualifier'];
}
if (isset($_SESSION['samlNameIdSPNameQualifier'])) {
    $nameIdSPNameQualifier = $_SESSION['samlNameIdSPNameQualifier'];
}
$auth->logout($returnTo, $paramters, $nameId, $sessionIndex, false, $nameIdFormat, $nameIdNameQualifier, $nameIdSPNameQualifier);

如果需要对即将发送的退出响应ID和要发送的退出请求ID进行匹配，则必须提取并存储该退出请求ID。

$sloBuiltUrl = $auth->logout(null, $paramters, $nameId, $sessionIndex, true);
$_SESSION['LogoutRequestID'] = $auth->getLastRequestID();
header('Pragma: no-cache');
header('Cache-Control: no-cache, must-revalidate');
header('Location: ' . $sloBuiltUrl);
exit();

初始化SSO请求和处理响应的视图示例（是acs目标）

我们可以编写一个独特的文件来初始化SSO流程，处理响应，获取属性，启动SLO并处理退出响应。

注意：请查看包含该用例的 demo1 文件夹；在稍后的部分中，我们将进一步详细解释demo1用例。

<?php

session_start();    // Initialize the session, we do that because
                    // Note that processResponse and processSLO
                    // methods could manipulate/close that session

require_once dirname(__DIR__).'/_toolkit_loader.php'; // Load Saml2 and external libs
require_once 'settings.php';    // Load the setting info as an Array

$auth = new OneLogin_Saml2_Auth($settingsInfo);  // Initialize the SP SAML instance

if (isset($_GET['sso'])) {    // SSO action.  Will send an AuthNRequest to the IdP
    $auth->login();
} else if (isset($_GET['sso2'])) {              // Another SSO action
    $returnTo = $spBaseUrl.'/demo1/attrs.php';  // but set a custom RelayState URL
    $auth->login($returnTo);
} else if (isset($_GET['slo'])) {  // SLO action. Will sent a Logout Request to IdP
    $auth->logout();
} else if (isset($_GET['acs'])) {  // Assertion Consumer Service
    $auth->processResponse();      // Process the Response of the IdP, get the
                                   // attributes and put then at
                                   // $_SESSION['samlUserdata']

    $errors = $auth->getErrors();  // This method receives an array with the errors
                                   // that could took place during the process

    if (!empty($errors)) {
        echo '<p>', implode(', ', $errors), '</p>';
    }
                                          // This check if the response was
    if (!$auth->isAuthenticated()) {      // sucessfully validated and the user
        echo "<p>Not authenticated</p>";  // data retrieved or not
        exit();
    }

    $_SESSION['samlUserdata'] = $auth->getAttributes(); // Retrieves user data
    if (isset($_POST['RelayState']) && OneLogin_Saml2_Utils::getSelfURL() != $_POST['RelayState']) {
        $auth->redirectTo($_POST['RelayState']);  // Redirect if there is a
    }                                             // relayState set
} else if (isset($_GET['sls'])) {   // Single Logout Service
    $auth->processSLO();            // Process the Logout Request & Logout Response
    $errors = $auth->getErrors(); // Retrieves possible validation errors
    if (empty($errors)) {
        echo '<p>Sucessfully logged out</p>';
    } else {
        echo '<p>', implode(', ', $errors), '</p>';
    }
}

if (isset($_SESSION['samlUserdata'])) {   // If there is user data we print it.
    if (!empty($_SESSION['samlUserdata'])) {
        $attributes = $_SESSION['samlUserdata'];
        echo 'You have the following attributes:<br>';
        echo '<table><thead><th>Name</th><th>Values</th></thead><tbody>';
        foreach ($attributes as $attributeName => $attributeValues) {
            echo '<tr><td>' . htmlentities($attributeName) . '</td><td><ul>';
            foreach ($attributeValues as $attributeValue) {
                echo '<li>' . htmlentities($attributeValue) . '</li>';
            }
            echo '</ul></td></tr>';
        }
        echo '</tbody></table>';
    } else {                             // If there is not user data, we notify
        echo "<p>You don't have any attribute</p>";
    }

    echo '<p><a href="?slo" >Logout</a></p>'; // Print some links with possible
} else {                                      // actions
    echo '<p><a href="?sso" >Login</a></p>';
    echo '<p><a href="?sso2" >Login and access to attrs.php page</a></p>';
}

使用Composer初始化SSO请求和处理响应的示例（是acs目标）

通过Composer安装包

composer require onelogin/php-saml

创建一个index.php

<?php
require('vendor/autoload.php');

session_start();
$needsAuth = empty($_SESSION['samlUserdata']);

if ($needsAuth) {
    // put SAML settings into an array to avoid placing files in the
    // composer vendor/ directories 
    $samlsettings = array(/*...config goes here...*/);
    
    $auth = new \OneLogin\Saml2\Auth($samlsettings);

    if (!empty($_REQUEST['SAMLResponse']) && !empty($_REQUEST['RelayState'])) {
        $auth->processResponse(null);
        $errors = $auth->getErrors();
        if (empty($errors)) {
            // user has authenticated successfully
            $needsAuth = false;
            $_SESSION['samlUserdata'] = $auth->getAttributes();
        }
    }

    if ($needsAuth) {
        $auth->login();
    }
}

// rest of your app goes here

URL猜测方法

php-saml工具包使用OneLogin_Saml2_Utils中的一系列方法来猜测处理SAML消息的URL。

getSelfHost 返回当前主机。
getSelfPort 返回请求使用的端口号。
isHTTPS 检查协议是否为 https 或 http。
getSelfURLhost 返回协议 + 当前主机 + 端口（如果与常用端口不同）。
getSelfURL 返回当前主机的 URL + 当前视图 + 查询。
getSelfURLNoQuery 返回当前主机 + 当前视图的 URL。
getSelfRoutedURLNoQuery 返回当前主机 + 当前视图的路由 URL。

getSelfURLNoQuery 和 getSelfRoutedURLNoQuery 用于计算当前URL，以验证 SAML 元素，如 Destination 或 Recipient。

当 PHP 应用程序位于代理或负载均衡器后面时，我们可以执行 setProxyVars(true) 和 setSelfPort，而 isHTTPS 将负责 $_SERVER["HTTP_X_FORWARDED_PORT"] 和 $_SERVER['HTTP_X_FORWARDED_PROTO'] 变量（否则将忽略它们）。

此外，开发者可以使用 setSelfProtocol、setSelfHost、setSelfPort 和 getBaseURLPath 来定义要由 isHTTPS、getSelfHost、getSelfPort 和 getBaseURLPath 返回的特定值。并定义一个 setBasePath，用于在 getSelfURL 和 getSelfRoutedURLNoQuery 中使用，以替换从 $_SERVER["REQUEST_URI"] 提取的数据。

在设置中，开发者将能够设置一个 'baseurl' 参数，该参数将自动使用 setBaseURL 来设置 setSelfProtocol、setSelfHost、setSelfPort 和 setBaseURLPath 的值。

在负载均衡器后面工作

当在带有 SSL 转发的负载均衡器后面工作时，断言请求 URL 和 SAML 响应的 Destination 属性可能会失败。

您可以通过配置服务器使其了解代理并在请求时返回原始 URL 来解决这个问题。

或使用上一节中描述的方法。

SP 密钥轮换

如果您计划更新 SP 的 x509cert 和 privateKey，可以将新的 x509cert 定义为 $settings['sp']['x509certNew']，它将发布在 SP 元数据中，以便身份提供者可以读取它们并准备轮换。

具有多个证书的 IdP

在某些场景中，IdP 使用不同的证书进行签名/加密，或在密钥轮换阶段，并在 IdP 元数据中发布多个证书。

为了处理这种情况，工具包提供了 $settings['idp']['x509certMulti'] 参数。

当使用该参数时，工具包将忽略 'x509cert' 和 'certFingerprint' 值。

'x509certMulti' 是一个具有 2 个键的数组

'signing'。一个用于验证 IdP 签名的证书数组
'encryption' 一个用于将数据加密并发送到 IdP 的唯一证书数组

重放攻击

为了避免重放攻击，您可以将已处理的 SAML 消息的 ID 存储起来，以避免重复处理。由于消息会过期并因该原因失效，因此您不需要存储这些 ID 超过您目前接受的时间范围。

使用 Auth 对象的 getLastMessageId/getLastAssertionId 方法获取最后处理的消息/断言的 ID。

主要类和方法

下面描述了可以调用的主要类和方法。

旧的 Saml 库

让我们先描述 Saml 库的类和方法，它是旧 v.1 工具包的一个演变，提供以保持向后兼容性。它们中的大多数都使用新的 SAML2 库中的类和方法。

OneLogin_Saml_AuthRequest - `AuthRequest.php`

具有受保护的属性 $auth，一个 OneLogin_Saml2_Auth 对象。

OneLogin_Saml_AuthRequest - 构建 OneLogin_Saml2_Auth，初始化 SP SAML 实例。
getRedirectUrl($returnTo) - 获取包含压缩后的AuthRequest消息的SSO URL。

OneLogin_Saml_Response - `Response.php`

OneLogin_Saml_Response - 构造函数，处理SAML响应，内部初始化SP SAML实例和OneLogin_Saml2_Response。
get_saml_attributes - 获取包含登录用户数据的数组。

OneLogin_Saml_Settings - `Settings.php`

用于构建工具包v1.0中使用的设置对象的简单类。

OneLogin_Saml_Metadata - `Metadata.php`

OneLogin_Saml_Metadata - 构造函数，根据SP的设置构建元数据XML信息。
getXml - 包含SP元数据信息的XML。

OneLogin_Saml_XmlSec - `XmlSec.php`

辅助类，包含验证SAML响应的方法：validateNumAssertions、validateTimestamps、isValid（使用前两种方法，并验证SAML响应的签名）。

Saml2库

现在让我们描述SAML2库的类和方法。

OneLogin_Saml2_Auth - Auth.php

OneLogin PHP工具包的主要类

OneLogin_Saml2_Auth - 初始化SP SAML实例
login - 启动SSO流程。
logout - 启动SLO流程。
processResponse - 处理IdP发送的SAML响应。
processSLO - 处理IdP发送的SAML注销响应/注销请求。
redirectTo - 将用户重定向到参数中提供的URL或我们定义的SSO请求中的URL。
isAuthenticated - 检查用户是否已认证。
getAttributes - 返回SAML属性集。
getAttribute - 返回请求的SAML属性。
getNameId - 返回nameID。
getNameIdFormat - 获取IdP提供的NameID格式。
getNameIdNameQualifier - 获取SAML响应字符串中提供的NameID NameQualifier。
getNameIdSPNameQualifier - 获取SAML响应字符串中提供的NameID SP NameQualifier。
getSessionIndex - 从AuthnStatement获取SessionIndex。
getErrors - 返回是否有错误。
getSSOurl - 获取SSO URL。
getSLOurl - 获取SLO URL。
getLastRequestID - 最后生成的SAML请求消息的ID。
buildRequestSignature - 生成SAML请求的签名。
buildResponseSignature - 生成SAML响应的签名。
getSettings - 返回设置信息。
setStrict - 设置严格模式启用/禁用。
getLastRequestID - 获取服务提供商生成的最后一个AuthNRequest或LogoutRequest的ID。
getLastRequestXML - 返回最近构造/处理的XML SAML请求（AuthNRequest、LogoutRequest）。
getLastResponseXML - 返回最近构造/处理的XML SAML响应（SAMLResponse、LogoutResponse）。如果SAMLResponse有加密的断言，则解密它。

OneLogin_Saml2_AuthnRequest - `AuthnRequest.php`

SAML 2身份验证请求类

OneLogin_Saml2_AuthnRequest - 构造AuthnRequest对象。
getRequest - 返回压缩、base64编码、未签名的AuthnRequest。
getId - 返回AuthNRequest ID。
getXML - 返回作为请求一部分发送的XML。

OneLogin_Saml2_Response - `Response.php`

SAML 2身份验证响应类

OneLogin_Saml2_Response - 构造SAML响应对象。
isValid - 使用证书确定SAML响应是否有效。
checkStatus - 检查状态是否为成功。
getAudiences - 获取受众。
getIssuers - 获取颁发者（从响应和断言中获取）。
getNameIdData - 获取IdP提供的NameID数据。
getNameId - 获取来自身份提供者（IdP）的SAML响应中提供的NameID。
getNameIdFormat - 获取IdP提供的NameID格式。
getNameIdNameQualifier - 获取SAML响应字符串中提供的NameID NameQualifier。
getNameIdSPNameQualifier - 获取SAML响应字符串中提供的NameID SP NameQualifier。
getSessionNotOnOrAfter - 获取AuthnStatement中的SessionNotOnOrAfter。
getSessionIndex - 从AuthnStatement获取SessionIndex。
getAttributes - 获取来自AttributeStatement元素的属性。
validateNumAssertions - 验证文档只包含单个断言（加密或不加密）。
validateTimestamps - 验证根据条件元素，文档是否仍然有效。
getError - 执行验证过程后，如果失败，此方法返回原因。
getXMLDocument - 返回SAML响应文档（如果包含加密断言，则解密它）。

OneLogin_Saml2_LogoutRequest - `LogoutRequest.php`

SAML 2注销请求类

OneLogin_Saml2_LogoutRequest - 构建注销请求对象。
getRequest - 返回注销请求的解包、base64编码、未签名版本。
getID - 返回注销请求的ID。（如果您有对象，您可以访问id属性）
getNameIdData - 获取注销请求的NameID数据。
getNameId - 获取注销请求的NameID。
getIssuer - 获取注销请求的发行者。
getSessionIndexes - 获取注销请求中的SessionIndexes。
isValid - 检查收到的注销请求是否有效。
getError - 执行验证过程后，如果失败，此方法返回原因。
getXML - 返回作为请求的一部分发送的XML或SP接收到的XML。

OneLogin_Saml2_LogoutResponse - `LogoutResponse.php`

SAML 2注销响应类

OneLogin_Saml2_LogoutResponse - 构建一个注销响应对象（从设置中初始化参数，如果提供则加载注销响应）。
getIssuer - 获取注销响应的发行者。
getStatus - 获取注销响应的状态。
isValid - 确定SAML注销响应是否有效。
build - 生成注销响应对象。
getResponse - 返回注销响应对象。
getError - 执行验证过程后，如果失败，此方法返回原因。
getXML - 返回作为响应的一部分发送的XML或SP接收到的XML。

OneLogin_Saml2_Settings - `Settings.php`

OneLogin PHP工具包的配置

OneLogin_Saml2_Settings - 初始化设置：设置不同文件夹的路径，从设置文件或提供的数组/对象中加载设置信息。
checkSettings - 检查设置信息。
getBasePath - 返回基本路径。
getCertPath - 返回证书路径。
getLibPath - 返回库路径。
getExtLibPath - 返回外部库路径。
getSchemasPath - 返回模式路径。
checkSPCerts - 检查SP的x509证书是否存在且有效。
getSPkey - 返回SP的x509私钥。
getSPcert - 返回SP的x509公钥。
getSPcertNew - 返回SP的未来x509公钥。
getIdPData - 获取IdP数据。
getSPData 获取SP数据。
getSecurityData - 获取安全数据。
getContacts - 获取联系数据。
getOrganization - 获取组织数据。
getSPMetadata - 获取SP元数据。XML表示形式。
validateMetadata - 验证XML SP元数据。
formatIdPCert - 格式化IdP证书。
formatSPCert - 格式化SP证书。
formatSPCertNew - 格式化新的SP证书。
formatSPKey - 格式化SP私钥。
getErrors - 返回一个包含错误的数组，当设置正常时数组为空。
getLastErrorReason - 返回最后错误的理由。
getBaseURL - 如果设置了，返回设置的baseurl。
setBaseURL - 设置基础URL值
setStrict - 启用或禁用严格模式。
isStrict - 返回是否启用了'严格'模式。
isDebugActive - 返回是否启用了调试模式。

OneLogin_Saml2_Metadata - `Metadata.php`

一个包含与SP元数据相关的功能的类

builder - 根据设置生成SP的元数据。
signmetadata - 使用提供的密钥/证书对元数据进行签名。
addX509KeyDescriptors - 将x509描述符（签名/加密）添加到元数据中。

OneLogin_Saml2_Utils - `Utils.php`

一个包含多个方法的辅助类

validateXML - 此函数尝试验证一个XML字符串与指定的模式。
formatCert - 返回一个x509证书（如果需要，添加头部和尾部）。
formatPrivateKey - 返回一个RSA私钥（如果需要，添加头部和尾部）。
redirect - 执行到提供的url的重定向（或返回目标url）。
isHTTPS - 检查是否为https或http。
getSelfHost - 返回当前主机。
getSelfURLhost - 返回协议 + 当前主机 + 端口（如果不同于常见端口）。
getSelfURLNoQuery - 返回当前主机 + 当前视图的URL。
getSelfURL - 返回当前主机 + 当前视图 + 查询的URL。
generateUniqueID - 生成一个唯一的字符串（例如用作断言的ID）。
parseTime2SAML - 将UNIX时间戳转换为SAML2时间戳，格式为yyyy-mm-ddThh:mm:ss(.s+)?Z。
parseSAML2Time - 将SAML2时间戳（格式为yyyy-mm-ddThh:mm:ss(.s+)?Z）转换为UNIX时间戳。忽略小数部分。
parseDuration - 解析相对于给定时间戳的ISO8601持续时间值。
getExpireTime - 比较两个日期并返回最早的一个。
query - 从DOMDocument中提取节点。
isSessionStarted - 检查会话是否已启动。
deleteLocalSession - 删除本地会话。
calculateX509Fingerprint - 计算x509证书的指纹。
formatFingerPrint - 格式化指纹。
generateNameId - 生成一个nameID。
getStatus - 从响应中获取状态。
decryptElement - 解密一个加密元素。
castKey - 将XMLSecurityKey转换为正确的算法。
addSign - 向元素（消息或断言）添加签名密钥和发送者证书。
validateSign - 验证签名（消息或断言）。

OneLogin_Saml2_IdPMetadataParser - `IdPMetadataParser.php`

一个包含多个方法以检索和处理IdP元数据的辅助类

parseRemoteXML - 从URL获取IdP元数据信息。
parseFileXML - 从文件获取IdP元数据信息。
parseXML - 从XML获取IdP元数据信息。
injectIntoSettings - 将元数据信息注入到php-saml设置数组中。

更多信息，请查看源代码；每个方法都有文档，并提供了它所做的工作以及如何使用的详细信息。确保还要检查doc文件夹，其中提供了有关SAML和SAML2的类和方法的HTML文档。

工具包中包含的演示

工具包包括三个演示应用程序，用于说明如何使用工具包，请查看它。

演示需要在使用之前对SP和IdP进行适当的配置。

演示1

SP设置

Onelogin的PHP工具包允许您以两种方式提供设置信息

使用位于工具包基础文件夹中的settings.php文件。
使用设置数据的数组。

在这个演示中，我们采用第二种方式提供数据，使用一个名为 $settingsInfo 的设置数组。此数组使用作为模板包含的 settings_example.php 来创建 settings.php 设置，并将其存储在 demo1/ 文件夹中。配置 SP 部分，然后审查 IdP 的元数据并完成 IdP 信息。

如果您检查 index.php 文件的代码，您将看到加载了 settings.php 文件，以便使用 $settingsInfo 变量来初始化 Setting 类。

请注意，在这个演示中，可以定义在工具包基本文件夹中的 setting.php 文件被忽略，并且使用位于工具包基本文件夹中的 _toolkit_loader.php 来加载库。

IdP 设置

一旦配置了 SP，SP 的元数据就会发布在 metadata.php 文件中。根据该信息配置 IdP。

工作原理

第一次访问 index.php 视图时，您可以选择登录并返回同一视图或登录并重定向到 attrs.php 视图。
当您点击

第一个链接中的 2.1 时，我们访问到 (index.php?sso)，向 IdP 发送一个 AuthNRequest，在 IdP 进行认证，然后通过用户的客户端将响应发送到 SP，具体是断言消费者服务视图：index.php?acs。请注意，将 RelayState 参数设置为启动过程的 URL，即 index.php 视图。

2.2 在第二个链接中，我们访问到 (attrs.php)，与 2.1 中描述的过程相同，不同之处在于将 RelayState 设置为 attrs.php。
在 ACS (index.php?acs) 中处理 SAML 响应，如果响应无效，则在此停止处理并显示消息。否则，我们将重定向到 RelayState 视图。a) index.php 或 b) attrs.php。
我们登录到应用程序，并显示用户属性。在这一点上，我们可以测试单点登出功能。
单点登出功能可以通过两种方式测试。

5.1 SP 启动的 SLO。单击 SP 上的“登出”链接，之后向 IdP 发送一个登出请求，关闭 IdP 上的会话，并通过客户端向 SP 发送登出响应（发送到单点登出服务端点）。SP 的 SLS 端点 (index.php?sls) 处理登出响应，如果有效，则关闭本地应用程序的用户会话。请注意，SLO 工作流从 SP 开始并结束。

5.2 IdP 启动的 SLO。在这种情况下，操作发生在 IdP 一侧，登出过程在 idP 上启动，向 SP 发送登出请求（SLS 端点，index.php?sls）。SP 的 SLS 端点处理登出请求，如果有效，则关闭本地应用程序的用户会话，并向 IdP 发送登出响应（发送到 IdP 的 SLS 端点）。IdP 接收登出响应，处理它并关闭 IdP 的会话。请注意，SLO 工作流从 IdP 开始并结束。

请注意，所有 SAML 请求和响应都由一个唯一的文件处理，即 index.php 文件，以及如何使用 GET 参数来知道必须执行的操作。

演示2

SP设置

Onelogin的PHP工具包允许您以两种方式提供设置信息

使用位于工具包基础文件夹中的settings.php文件。
使用设置数据的数组。

第一个是演示2应用程序的情况。应在工具包基本文件夹中定义 setting.php 文件和 setting_extended.php 文件。通过审查 setting_example.php 和 advanced_settings_example.php 来学习如何构建它们。

在这种情况下，我们将使用端点文件夹中的文件作为属性消费服务和单点登出服务（acs.php 和 sls.php）。

IdP 设置

一旦配置了SP，SP的元数据将发布在 metadata.php 文件中。基于这些信息，配置IdP。

工作原理

在demo1中，我们看到了所有SAML请求和响应是如何在一个唯一的文件index.php中处理的。这个demo1使用高级编程。

在demo2中，我们有几个视图：index.php、sso.php、slo.php、consume.php 和 metadata.php。正如我们所说，我们将使用工具箱中定义的端点（端点文件夹中的acs.php、sls.php）。这个demo2使用低级编程。

请注意，SSO操作可以在 index.php 或 sso.php 中启动。

发生的SAML工作流与demo1中定义的工作流相似，只是更改了目标。

当您第一次访问 index.php 或 sso.php 时，会自动向IdP发送一个 AuthNRequest（因为发送了原始url作为 RelayState）。我们在IdP处进行身份验证，然后向SP发送一个 Response，到端点，在这个例子中是端点文件夹中的 acs.php。
SAML响应在ACS中处理，如果 Response 无效，则在此处停止处理并显示消息。否则，我们将重定向到 RelayState 视图（sso.php 或 index.php）。sso.php 检测用户是否已登录，并将其重定向到 index.php，因此我们最终会在 index.php 中。
我们已经登录到应用程序，并显示了用户属性（如果有）。在此阶段，我们可以测试单点登出功能。
单点登出功能可以通过两种方式测试。

4.1 SP启动的SLO。在SP上点击“登出”链接，然后我们将重定向到 slo.php 视图，并在那里向IdP发送一个登出请求，关闭IdP上的会话，并回复SP一个登出响应（发送到单点登出服务端点）。在这种情况下，SP的SLS端点处理登出响应，如果有效，关闭本地应用程序的用户会话。请注意，SLO工作流从SP开始，并在SP结束。

4.2 IdP启动的SLO。在这种情况下，操作在IdP端进行，登出过程在IdP处启动，向SP发送一个登出请求（端点文件夹中的SLS端点 sls.php）。SP的SLS端点处理登出请求，如果有效，关闭本地应用程序的用户会话，并向IdP发送一个登出响应（发送到IdP的SLS端点）。IdP接收登出响应，处理它并关闭IdP上的会话。请注意，SLO工作流从IdP开始，并在IdP结束。

旧版演示

SP设置

这个演示使用了工具箱版本1的旧风格。必须向AuthRequest构造函数提供一个OneLogin_Saml_Settings类的对象。

您可以在demo-old文件夹中找到一个 example_settings.php 文件，该文件可以用作您的 settings.php 文件的模板。

在该模板中，SAML设置分为两部分，应用程序特定的（const_assertion_consumer_service_url、const_issuer、const_name_identifier_format）和用户/账户特定的（idp_sso_target_url、x509certificate）。您需要在这里添加自己的代码来识别用户或用户来源（例如，通过 subdomain、ip_address 等）。

IdP 设置

一旦配置了SP，SP的元数据将发布在 metadata.php 文件中。之后，根据这些信息配置IdP。

工作原理

在 metadata.php 视图中发布了SP的元数据。

如果应用程序应该启动 SAML 会话，则 index.php 文件充当启动器。这被称为服务提供商启动的 SAML。服务提供商创建 SAML 认证请求并将其发送到身份提供者（IdP）。

consume.php 是 ACS 端点。接收 SAML 断言。在响应验证后，可以使用 getNameId() 或 getAttributes() 获取 userdata 和 nameID。

由于 php 工具包的版本 1 不支持 SLO，因此在本演示旧版本中我们不展示如何处理 SLO。

bloomatwork / php-saml

维护者

详细信息

README

警告

安全指南

为什么要在我的软件中添加 SAML 支持？

一般描述

安装

依赖项

代码

选项1. 从github克隆仓库

选项2. 从github下载

选项3. Composer

兼容性

命名空间

安全警告

入门

了解工具包

certs/

extlib/

lib/

doc/

endpoints/

locale/

其他重要文件

杂项

工作原理

设置

如何加载库

启动单点登录

SP 端点

SP 元数据 endpoints/metadata.php

属性消费者服务（ACS） endpoints/acs.php

getAttributes 方法

单点退出服务（SLS） endpoints/sls.php

启动SLO

初始化SSO请求和处理响应的视图示例（是acs目标）

使用Composer初始化SSO请求和处理响应的示例（是acs目标）

URL猜测方法

在负载均衡器后面工作

SP 密钥轮换

具有多个证书的 IdP

重放攻击

主要类和方法

旧的 Saml 库

OneLogin_Saml_AuthRequest - AuthRequest.php

OneLogin_Saml_Response - Response.php

OneLogin_Saml_Settings - Settings.php

OneLogin_Saml_Metadata - Metadata.php

OneLogin_Saml_XmlSec - XmlSec.php

Saml2库

OneLogin_Saml2_Auth - Auth.php

OneLogin_Saml2_AuthnRequest - AuthnRequest.php

OneLogin_Saml2_Response - Response.php

OneLogin_Saml2_LogoutRequest - LogoutRequest.php

OneLogin_Saml2_LogoutResponse - LogoutResponse.php

OneLogin_Saml2_Settings - Settings.php

OneLogin_Saml2_Metadata - Metadata.php

OneLogin_Saml2_Utils - Utils.php

OneLogin_Saml2_IdPMetadataParser - IdPMetadataParser.php

工具包中包含的演示

演示1

SP设置

IdP 设置

工作原理

演示2

SP设置

IdP 设置

工作原理

旧版演示

SP设置

IdP 设置

工作原理

`certs/`

`extlib/`

`lib/`

`doc/`

`endpoints/`

`locale/`

SP 元数据 `endpoints/metadata.php`

属性消费者服务（ACS） `endpoints/acs.php`

`getAttributes` 方法

单点退出服务（SLS） `endpoints/sls.php`

OneLogin_Saml_AuthRequest - `AuthRequest.php`

OneLogin_Saml_Response - `Response.php`

OneLogin_Saml_Settings - `Settings.php`

OneLogin_Saml_Metadata - `Metadata.php`

OneLogin_Saml_XmlSec - `XmlSec.php`

OneLogin_Saml2_AuthnRequest - `AuthnRequest.php`

OneLogin_Saml2_Response - `Response.php`

OneLogin_Saml2_LogoutRequest - `LogoutRequest.php`

OneLogin_Saml2_LogoutResponse - `LogoutResponse.php`

OneLogin_Saml2_Settings - `Settings.php`

OneLogin_Saml2_Metadata - `Metadata.php`

OneLogin_Saml2_Utils - `Utils.php`

OneLogin_Saml2_IdPMetadataParser - `IdPMetadataParser.php`