README

贡献者: getpantheon, danielbachhuber, outlandish-josh, jazzs3quence
标签: 身份验证, SAML
至少需要 4.4
测试到 6.3
需要 PHP 7.3
稳定标签 2.1.4
许可: GPLv2 或更高版本
许可 URI: https://gnu.ac.cn/licenses/gpl-2.0.html

WordPress 的 SAML 身份验证

描述

WordPress 的 SAML 身份验证，使用捆绑的 OneLogin SAML 库或可选安装的 SimpleSAMLphp。OneLogin 提供一个 SAML 认证网关；SimpleSAMLphp 提供了 SAML 以及各种其他身份验证机制。此插件作为 WordPress 和身份验证库之间的网关。

如果您的组织使用 Google Apps，将 Google Apps 与 WP SAML Auth 集成只需几个步骤。

标准用户流程如下

用户可以通过添加到标准 WordPress 登录视图的按钮使用 SAML 登录。
点击按钮后，用户将转交给身份验证库。使用 OneLogin 时，用户将被重定向到 SAML 身份提供商。使用 SimpleSAMLphp 时，用户将被重定向到 SimpleSAMLphp 安装。
一旦用户通过身份提供商进行身份验证，他们将被重定向回 WordPress 并登录到他们的账户。如果不存在新 WordPress 用户，将创建一个新用户（尽管此行为可以禁用）。
当用户从 WordPress 登出时，他们也将从身份提供商登出。

一组配置选项允许您更改插件默认行为。例如，permit_wp_login=>false 将强制所有身份验证都通过 SAML 身份提供商进行，绕过 wp-login.php。同样，auto_provision=>false 将禁用自动创建新 WordPress 用户。

请参阅安装说明以获取完整的配置细节。

安装

一旦您激活了插件，并且有权访问功能齐全的 SAML 身份提供商（IdP），WP SAML Auth 可以通过以下几种方式配置

WordPress 后端中的设置页面。设置页面提供最常见的配置选项，但并非全部。它位于 "设置" -> "WP SAML Auth"。
使用过滤器应用代码片段。下面的文档中记录的代码片段方法允许访问所有配置设置。当存在代码片段时，设置页面完全禁用。

如果您直接连接到现有的 IdP，应使用捆绑的 OneLogin SAML 库。必要的最常见设置在 WordPress 后端中可用。

如果您有更复杂的身份验证需求，则还可以在同一环境中使用运行SimpleSAMLphp的安装。这些设置不能通过WordPress后端进行配置；它们需要通过过滤器来定义。并且，如果您已经有了过滤器，WordPress后端设置将被删除。

下面代码段中对每个设置都有额外的说明。

为了测试目的在本地安装SimpleSAMLphp，可以从身份提供者快速入门开始。在Pantheon上，SimpleSAMLphp的Web目录需要链接到~/code/simplesaml以由Nginx正确处理。阅读文档了解在Pantheon上配置SimpleSAMLphp的更多详细信息。

由于SAML身份验证被作为登录流程的一部分处理，您的SAML身份提供者需要将响应发送回wp-login.php。例如，如果您的域是pantheon.io，则您会使用http://pantheon.io/wp-login.php作为您的AssertionConsumerService配置值。

要使用过滤器配置插件或了解每个设置的详细信息，请使用以下代码段

function wpsax_filter_option( $value, $option_name ) {
    $defaults = array(
        /**
         * Type of SAML connection bridge to use.
         *
         * 'internal' uses OneLogin bundled library; 'simplesamlphp' uses SimpleSAMLphp.
         *
         * Defaults to SimpleSAMLphp for backwards compatibility.
         *
         * @param string
         */
        'connection_type' => 'internal',
        /**
         * Configuration options for OneLogin library use.
         *
         * See comments with "Required:" for values you absolutely need to configure.
         *
         * @param array
         */
        'internal_config'        => array(
            // Validation of SAML responses is required.
            'strict'       => true,
            'debug'        => defined( 'WP_DEBUG' ) && WP_DEBUG ? true : false,
            'baseurl'      => home_url(),
            'sp'           => array(
                'entityId' => 'urn:' . parse_url( home_url(), PHP_URL_HOST ),
                'assertionConsumerService' => array(
                    'url'  => wp_login_url(),
                    'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
                ),
            ),
            'idp'          => array(
                // Required: Set based on provider's supplied value.
                'entityId' => '',
                'singleSignOnService' => array(
                    // Required: Set based on provider's supplied value.
                    'url'  => '',
                    'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
                ),
                'singleLogoutService' => array(
                    // Required: Set based on provider's supplied value.
                    'url'  => '',
                    'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
                ),
                // Required: Contents of the IDP's public x509 certificate.
                // Use file_get_contents() to load certificate contents into scope.
                'x509cert' => '',
                // Optional: Instead of using the x509 cert, you can specify the fingerprint and algorithm.
                'certFingerprint' => '',
                'certFingerprintAlgorithm' => '',
            ),
        ),
        /**
         * Path to SimpleSAMLphp autoloader.
         *
         * Follow the standard implementation by installing SimpleSAMLphp
         * alongside the plugin, and provide the path to its autoloader.
         * Alternatively, this plugin will work if it can find the
         * `SimpleSAML_Auth_Simple` class.
         *
         * @param string
         */
        'simplesamlphp_autoload' => dirname( __FILE__ ) . '/simplesamlphp/lib/_autoload.php',
        /**
         * Authentication source to pass to SimpleSAMLphp
         *
         * This must be one of your configured identity providers in
         * SimpleSAMLphp. If the identity provider isn't configured
         * properly, the plugin will not work properly.
         *
         * @param string
         */
        'auth_source'            => 'default-sp',
        /**
         * Whether or not to automatically provision new WordPress users.
         *
         * When WordPress is presented with a SAML user without a
         * corresponding WordPress account, it can either create a new user
         * or display an error that the user needs to contact the site
         * administrator.
         *
         * @param bool
         */
        'auto_provision'         => true,
        /**
         * Whether or not to permit logging in with username and password.
         *
         * If this feature is disabled, all authentication requests will be
         * channeled through SimpleSAMLphp.
         *
         * @param bool
         */
        'permit_wp_login'        => true,
        /**
         * Attribute by which to get a WordPress user for a SAML user.
         *
         * @param string Supported options are 'email' and 'login'.
         */
        'get_user_by'            => 'email',
        /**
         * SAML attribute which includes the user_login value for a user.
         *
         * @param string
         */
        'user_login_attribute'   => 'uid',
        /**
         * SAML attribute which includes the user_email value for a user.
         *
         * @param string
         */
        'user_email_attribute'   => 'mail',
        /**
         * SAML attribute which includes the display_name value for a user.
         *
         * @param string
         */
        'display_name_attribute' => 'display_name',
        /**
         * SAML attribute which includes the first_name value for a user.
         *
         * @param string
         */
        'first_name_attribute' => 'first_name',
        /**
         * SAML attribute which includes the last_name value for a user.
         *
         * @param string
         */
        'last_name_attribute' => 'last_name',
        /**
         * Default WordPress role to grant when provisioning new users.
         *
         * @param string
         */
        'default_role'           => get_option( 'default_role' ),
    );
    $value = isset( $defaults[ $option_name ] ) ? $defaults[ $option_name ] : $value;
    return $value;
}
add_filter( 'wp_saml_auth_option', 'wpsax_filter_option', 10, 2 );

如果您需要根据SAML响应调整身份验证行为，可以使用wp_saml_auth_pre_authentication过滤器

/**
 * Reject authentication if $attributes doesn't include the authorized group.
 */
add_filter( 'wp_saml_auth_pre_authentication', function( $ret, $attributes ) {
    if ( empty( $attributes['group'] ) || ! in_array( 'administrators', $attributes['group'] ) ) {
        return new WP_Error( 'unauthorized-group', "Sorry, you're not a member of an authorized group." );
    }
    return $ret;
}, 10, 2 );

WP-CLI命令

此插件实现了一系列WP-CLI命令。所有命令都分组在wp saml-auth命名空间中。

$ wp help saml-auth

NAME

  wp saml-auth

DESCRIPTION

  Configure and manage the WP SAML Auth plugin.

SYNOPSIS

  wp saml-auth <command>

SUBCOMMANDS

  scaffold-config      Scaffold a configuration filter to customize WP SAML Auth usage.

使用wp help saml-auth <command>了解更多关于每个命令的信息。

贡献

有关贡献的信息，请参阅CONTRIBUTING.md。

安全策略

报告安全漏洞

请通过Patchstack漏洞披露计划报告在WP SAML Auth插件源代码中发现的任何安全漏洞。Patchstack团队将协助您进行验证、CVE分配，并通知此插件的开发者。

常见问题解答

我可以在用户重新登录时更新现有WordPress用户的数据吗？

如果您想确保用户的显示名称、姓氏和名字在用户重新登录时在WordPress中更新，您可以使用以下代码段

/**
 * Update user attributes after a user has logged in via SAML.
 */
add_action( 'wp_saml_auth_existing_user_authenticated', function( $existing_user, $attributes ) {
    $user_args = array(
        'ID' => $existing_user->ID,
    );
    foreach ( array( 'display_name', 'first_name', 'last_name' ) as $type ) {
        $attribute          = \WP_SAML_Auth::get_option( "{$type}_attribute" );
        $user_args[ $type ] = ! empty( $attributes[ $attribute ][0] ) ? $attributes[ $attribute ][0] : '';
    }
    wp_update_user( $user_args );
}, 10, 2 );

wp_saml_auth_existing_user_authenticated操作在用户使用SAML IdP成功认证后触发。代码段随后使用类似于WP SAML Auth的模式从SAML响应中获取显示名称、姓氏和名字。最后，代码段更新现有的WordPress用户对象。

我如何在多Web节点环境中使用SimpleSAMLphp和WP SAML Auth？

由于SimpleSAMLphp使用PHP会话来管理用户身份验证，它会在具有多个Web节点的服务器配置上不可靠或不工作。这是因为PHP的默认会话处理程序使用文件系统，每个Web节点都有不同的文件系统。幸运的是，有一个解决办法。

首先，安装并激活WP Native PHP Sessions插件，它为WordPress注册了一个基于数据库的PHP会话处理程序。

接下来，修改SimpleSAMLphp的www/_include.php文件，使其包含wp-load.php。如果您在wp-saml-auth目录内安装了SimpleSAMLphp，您将编辑wp-saml-auth/simplesamlphp/www/_include.php以包含

<?php
require_once dirname( dirname( dirname( dirname( dirname( dirname( __FILE__ ) ) ) ) ) ) . '/wp-load.php';

注意：声明需要在_include.php的顶部，以确保在SimpleSAMLphp之前加载WordPress（以及因此会话处理）。

没有第三步。因为SimpleSAMLphp会加载WordPress，而WordPress启用了WP Native PHP Sessions，所以SimpleSAMLphp和WP SAML Auth能够在多节点Web环境中相互通信。

升级通知

2.0.0

最低支持的PHP版本是7.3。

变更日志

2.1.4（2023年11月27日）

修复证书路径标签中的拼写错误[#352]
更新Pantheon WP编码标准到2.0[#357]
修复注销认证问题[#359]（感谢Snicco）

2.1.3（2023年4月8日）

修复前一个版本中缺失的vendor/目录[#336]

2.1.2（2023年4月7日）

将yoast/phpunit-polyfills从1.0.4升级到1.0.5[#334]
更新到测试的版本
删除未使用的NPM依赖项

2.1.1（2023年3月15日）

添加PHP 8.2兼容性[#332].
使dependabot针对develop分支[#313].
升级依赖项[#308][#310][#314][#319][#322][#323][#324][#325][#326][#330].

2.1.0（2022年11月29日）

添加用于构建标签和部署到wp.org的Github Actions。添加CONTRIBUTING.md。[#311]

2.0.1（2022年1月24日）

重建平台依赖项以适应PHP 7.3[#278].

2.0.0（2022年1月6日）

重大变更：将onelogin/php-saml更新到v4.0.0，需要PHP 7.3或更高版本[#275].

1.2.7（2021年12月9日）

添加在注销前触发的wp_saml_auth_pre_logout动作[#274].

1.2.6（2021年10月12日）

添加wp_saml_auth_login_parameters过滤器，允许过滤登录参数[#262].

1.2.5（2021年8月18日）

修复1.2.4中引入的未定义索引通知[#257].

1.2.4（2021年8月18日）

添加wp_saml_auth_internal_logout_args过滤器，允许过滤内部注销参数[#255].

1.2.3（2021年5月25日）

添加wp_saml_auth_force_authn过滤器，允许启用forceAuthn="true"[#248].

1.2.2（2021年4月26日）

确保SAML按钮和说明只添加到登录屏幕 [#242].

1.2.1 (2021年3月2日)

更新 onelogin/php-saml 到 v3.6.1 [#236].

1.2.0 (2021年2月22日)

更新 onelogin/php-saml 到 v3.6.0 [#233].

1.1.1 (2021年2月3日)

更新法语本地化并确保加载本地化 [#230].

1.1.0 (2020年12月1日)

更新 onelogin/php-saml 到 v3.5.0 [#218].

1.0.2 (2020年5月27日)

当使用SimpleSAMLphp时避免不希望的 session_start() [#196].

1.0.1 (2020年5月26日)

允许在避免循环重定向的情况下重定向回 wp-login.php [#192].

1.0.0 (2020年3月2日)

插件稳定。

0.8.3 (2020年2月3日)

删除导致PHP警告的未使用 placeholder 值 [#178].

0.8.2 (2020年1月22日)

修复用于静态方法的方法声明问题 [#176].

0.8.1 (2019年11月25日)

更新 onelogin/php-saml 到 v3.4.1 [#174].

0.8.0 (2019年11月20日)

更新 onelogin/php-saml 到 v3.4.0 [#173].

0.7.3 (2019年11月7日)

更新 onelogin/php-saml 到 v3.3.1 [#172].

0.7.2 (2019年10月30日)

修复空必填设置字段引发加载异常的问题 [#170].

0.7.1 (2019年9月26日)

修复设置页面上的拼写错误 [#163].

0.7.0 (2019年9月16日)

更新 onelogin/php-saml 到 v3.3.0 [#160].

0.6.0 (2019年5月14日)

添加用于配置WP SAML Auth的设置页面 [#151].
修复处理SimpleSAMLphp响应时的问题 [#145].

0.5.2 (2019年4月8日)

更新 onelogin/php-saml 到 v3.1.1 以支持PHP 7.3 [#139].

0.5.1 (2018年11月15日)

引入 wp_saml_auth_attributes 过滤器，允许在SAML响应属性被WordPress处理之前修改它们 [#136].

0.5.0 (2018年11月7日)

更新 onelogin/php-saml 到 v3.0.0 以支持PHP 7.2 [#133].

0.4.0 (2018年9月5日)

将 onelogin/php-saml 从 v2.13.0 更新到 v2.14.0 [#127].

0.3.11 (2018年7月18日)

当SAML响应属性缺失时，明确提供错误信息。[#125]

0.3.10（2018年6月28日）

通过使用rawurlencode()编码，确保redirect_to URL不会丢失查询参数。[#124]
添加法语本地化。

0.3.9（2018年3月29日）

使用可用的命名空间SimpleSAMLphp类修复PHP notice，如果存在的话。[#118]
将onelogin/php-saml从v2.12.0更新到v2.13.0

0.3.8（2018年2月26日）

当redirect_to持久化时，重定向到action=wp-saml-auth，以确保处理身份验证。[#115]

0.3.7（2018年2月13日）

更准确地持久化redirect_to值，作为v0.3.6中更改的后续。[#113]

0.3.6（2018年2月7日）

防止WordPress在用户从/wp-admin/ URL重定向到登录时丢弃身份验证cookie。[#112]

0.3.5（2018年1月19日）

用parse_url( wp_login_url(), PHP_URL_PATH )替换wp-login.php字符串，以适应更改标准登录URL的插件和函数。[#109]

0.3.4（2017年12月22日）

允许使用没有注销URL的internal连接类型，以集成Google Apps。[#106]

0.3.3（2017年11月28日）

将'redirect_to'参数转发到SAML身份验证，以启用深度链接。[#103]

0.3.2（2017年11月9日）

将onelogin/php-saml依赖项从v2.10.7更新到v2.12.0。[#90，#99]

0.3.1（2017年7月12日）

将$attributes传递给wp_saml_auth_insert_user过滤器，以便可以根据SAML响应修改用户创建行为。

0.3.0（2017年6月29日）

包含OneLogin的PHP SAML库，用于无需SimpleSAMLphp的SAML身份验证。有关配置说明，请参阅“安装”部分。
修复了当permit_wp_login=true时SAMLResponse的处理。

0.2.2（2017年5月24日）

引入一个wp_saml_auth_login_strings过滤器，允许过滤登录文本字符串。
引入一个wp_saml_auth_pre_authentication过滤器，允许根据SAML响应调整身份验证行为。
当所需的SAML响应属性缺失时，改进了错误信息。
在composer.json中更正了项目名称。

0.2.1（2017年3月22日）

引入了wp_saml_auth_new_user_authenticated和wp_saml_auth_existing_user_authenticated操作，允许主题/插件在身份验证后运行回调。
针对最新的稳定SimpleSAMLphp运行Behat测试套件，而不是固定版本。

0.2.0（2017年3月7日）

引入了wp saml-auth scaffold-config，一个WP-CLI命令，用于生成配置过滤器以自定义WP SAML Auth的使用。
在SimpleSAMLPHP身份验证后重定向回WordPress。
测试套件的各种改进。

0.1.0（2016年4月18日）

首次发布。

pantheon-systems / wp-saml-auth

维护者

详细信息