README

一个 PHP Symfony 扩展包，使用 simplesamlphp/saml2 为您的应用程序添加 SAML 功能

作为 OpenConext-Stepup Gateway 和相关 OpenConext-Stepup 应用程序的一部分开发，这些应用程序使用 SAML 2.0

安装

• 将包添加到您的 Composer 文件中

  composer require surfnet/stepup-saml-bundle

如何使用 SF6 安装

1. 在 composer.json 中要求扩展包（版本 4.1.9 或更高）
2. 在 config/bundles.php 中启用扩展包，将以下内容添加到返回语句中： Surfnet\SamlBundle\SurfnetSamlBundle::class => ['all' => true],
3. 在 config/packages/surfnet_saml.yaml 中指定扩展包配置，有关可用选项，请参阅下面的配置部分。
4. 通过将 '%kernel.project_dir%/vendor/surfnet/stepup-saml-bundle/templates': 'SurfnetSaml' 添加到您的 twig.yaml 配置文件（们）中来配置模板以供 Twig 扩展包使用

配置

surfnet_saml:
    enable_authentication: false
    hosted:
        attribute_dictionary:
            ignore_unknown_attributes: false
        service_provider:
            enabled: true
            assertion_consumer_route: name_of_the_route_of_the_assertion_consumer_url
            public_key: %surfnet_saml_sp_publickey%
            private_key: %surfnet_saml_sp_privatekey%
        identity_provider:
            enabled: true
            service_provider_repository: service.name.of.entity_repository
            sso_route: name_of_the_route_of_the_single_sign_on_url
            public_key: %surfnet_saml_idp_publickey%
            private_key: %surfnet_saml_idp_privatekey%
        metadata:
            entity_id_route: name_of_the_route_of_metadata_url
            public_key: %surfnet_saml_metadata_publickey%
            private_key: %surfnet_saml_metadata_privatekey%
    remote:
        identity_provider:
            enabled: true
            entity_id: %surfnet_saml_remote_idp_entity_id%
            sso_url: %surfnet_saml_remote_idp_sso_url%
            certificate: %surfnet_saml_remote_idp_certificate%
        service_providers:
            - entity_id: "%surfnet_saml_remote_sp_entity_id%"
              certificate_file: "%surfnet_saml_remote_sp_certificate%"
              assertion_consumer_service_url: "%surfnet_saml_remote_sp_acs%"            

hosted: 配置列出您的应用程序提供的服务的配置（SP、IdP 或两者）。可以通过相应的 enabled 标志分别开启和关闭 SP 和 IdP 功能。

remote: 配置列出（如果启用），连接到的一个或多个远程服务提供者和身份提供者的配置。如果您的应用程序通过单个身份提供者进行身份验证，您可以使用上述所示的 identity_provider: 选项。可以使用 @surfnet_saml.remote.idp 服务在运行时访问身份提供者。

如果您的应用程序通过多个身份提供者进行身份验证，您可以从配置中省略 identity_provider: 键，并在 identity_providers: 下列出所有身份提供者。可以使用 @surfnet_saml.remote.identity_providers 服务访问身份提供者。

    remote:
        identity_providers:
            -  enabled: true
               entity_id: %surfnet_saml_remote_idp_entity_id%
               sso_url: %surfnet_saml_remote_idp_sso_url%
               certificate: %surfnet_saml_remote_idp_certificate%

最后一行的内联证书可以用包含证书文件的文件系统路径替换 certificate_file。建议使用上面列出的参数。各种 publickey 和 privatekey 变量是键的内容，一行中不带证书等分隔符。强烈建议使用上面列出的参数，以便将实际键内容保留在配置文件之外（例如，使用本地 parameters.yml 文件）。

service_provider_repository 是您提供 IdP 服务的服务提供者的存储库。配置的 必须 实现 Surfnet\SamlBundle\Entity\ServiceProviderRepository 接口。

可以通过使用远程 service_providers 配置选项提供静态服务提供者。要使用这些配置的服务提供者，请记住您需要将 surfnet_saml.remote.service_providers 作为 service_provider_repository 分配。

示例用法

Symfony 身份验证

从本扩展包的第 5 版开始，我们开始支持通过 Stepup SAML 扩展包进行 SAML 身份验证。这与 Symfony 安全组件结合使用。

有关如何将此安装到您的 SP 的详细信息，请参阅 EXAMPLES.md。

重写 ACS 处理器

您的应用程序将开始尝试处理发送到您的应用程序 ACS 位置的所有 SAML 响应。在大多数情况下，这正是您想要的。但是，如果您想自己处理响应，您也可以这样做！

1. 确保您将 RelayState 语句添加到 AuthnRequest
2. 在您的应用中配置rejected_relay_states参数中的RelayState值。此值默认为[]。因此，请确保传递一个字符串值数组。
3. 就是这样。

元数据发布

<?php

namespace Acme\SamlBundle

use Surfnet\SamlBundle\Http\XMLResponse;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;

class MetadataController extends Controller
{
    public function metadataAction(Request $request)
    {
        /** @var \Surfnet\SamlBundle\Metadata\MetadataFactory $metadataFactory */
        $metadataFactory = $this->get('surfnet_saml.metadata_factory');

        return new XMLResponse($metadataFactory->generate());
    }
}

更多示例请参考EXAMPLES.md。

发布策略

CHANGELOG.md

请阅读：[https://github.com/OpenConext/Stepup-Deploy/wiki/Release-Management](https://github.com/OpenConext/Stepup-Deploy/wiki/Release-Management)以获取关于Stepup项目中使用的发布策略的更多信息。

UPGRADING.md

当在包中引入向后兼容的破坏性更改时，请更新UPGRADING.md文件，指导用户如何处理这些更改。这将使升级尽可能顺利。