README

将 Yii 2 应用程序连接到 Saml 身份提供者以实现单点登录

安装

安装此扩展的首选方式是通过 composer。

运行以下命令之一

php composer.phar require --prefer-dist asasmoyo/yii2-saml "*"

或将以下内容添加到您的 composer.json 文件的 require 部分。

"asasmoyo/yii2-saml": "*"

配置

在 config/web.php 中将 asasmoyo\yii2saml\Saml 注册到组件中。

'components' => [
    'saml' => [
        'class' => 'asasmoyo\yii2saml\Saml',
        'configFileName' => '@app/config/saml.php', // OneLogin_Saml config file (Optional)
    ]
]

此组件需要一个存储在 php 文件中的 OneLogin_Saml 配置。默认的 configFileName 值为 @app/config/saml.php，因此请确保在之前创建此文件。此文件必须返回 OneLogin_Saml 配置。有关示例配置，请参阅此 链接。

<?php

$urlManager = Yii::$app->urlManager;
$spBaseUrl = $urlManager->getHostInfo() . $urlManager->getBaseUrl();

return [
    'sp' => [
        'entityId' => $spBaseUrl.'/saml/metadata',
        'assertionConsumerService' => [
            'url' => $spBaseUrl.'/saml/acs',
        ],
        'singleLogoutService' => [
            'url' => $spBaseUrl.'/saml/sls',
        ],
        'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified',
    ],
    'idp' => [
        'entityId' => 'identity-provider',
        'singleSignOnService' => [
            'url' => 'https://idp.com/sso',
        ],
        'singleLogoutService' => [
            'url' => 'https://idp.com/sls',
        ],
        'x509cert' => '<x509cert string>',
    ],
];

注意：自版本 1.6.0 以来，您可以直接将配置放入组件中。例如

<?php

$urlManager = Yii::$app->urlManager;
$spBaseUrl = $urlManager->getHostInfo() . $urlManager->getBaseUrl();

$config = [
    // some other configuration here

    'components' => [
        'saml' => [
            'class' => 'asasmoyo\yii2saml\Saml',
            'config' => [
                'sp' => [
                    'entityId' => $spBaseUrl.'/saml/metadata',
                    'assertionConsumerService' => [
                        'url' => $spBaseUrl.'/saml/acs',
                    ],
                    'singleLogoutService' => [
                        'url' => $spBaseUrl.'/saml/sls',
                    ],
                    'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified',
                ],
                'idp' => [
                    'entityId' => 'identity-provider',
                    'singleSignOnService' => [
                        'url' => 'https://idp.com/sso',
                    ],
                    'singleLogoutService' => [
                        'url' => 'https://idp.com/sls',
                    ],
                    'x509cert' => '<x509cert string>',
                ],
            ],
        ]
    ],

    // some other configuration here
];

return $config;

使用方法

此扩展提供了 4 个操作

1. LoginAction

   此操作将启动在配置文件中指定的身份提供者的登录过程。要使用此操作，只需将其注册到您的控制器中的操作即可。

   <?php
   
   namespace app\controllers;
   
   use Yii;
   use yii\web\Controller;
   use yii\helpers\Url;
   
   
   class SamlController extends Controller {
   
       // Remove CSRF protection
       public $enableCsrfValidation = false;
   
       public function actions() {
           return [
               'login' => [
                   'class' => 'asasmoyo\yii2saml\actions\LoginAction',
                   'returnTo' => Yii::app()->user->returnUrl
               ]
           ];
       }
   
   }

   登录方法可以接收七个可选参数

   • $returnTo - 用户登录后应返回的目标 URL。
   • $parameters - 要添加到 HTTP-Redirect 中 GET 的参数数组。
   • $forceAuthn - 当为 true 时，AuthNRequest 将设置 ForceAuthn='true'。
   • $isPassive - 当为 true 时，AuthNRequest 将设置 Ispassive='true'。
   • $strict - 如果为真，则保持（返回 URL 字符串），如果为假，则重定向。
   • $setNameIdPolicy - 当为真时，AuthNRequest 将设置 nameIdPolicy 元素。
   • $nameIdValueReq - 通知 IdP 应该认证的实体。

   现在您可以通过访问 saml/login 登录到您的身份提供者。

2. AcsAction

   此操作将处理身份提供者在成功登录后发送的 saml 响应。您可以在控制器中注册回调以执行某些操作，例如读取身份提供者发送的属性并从这些属性中创建新用户。要使用此操作，只需将其注册到您控制器中的操作即可。

   <?php
   
   namespace app\controllers;
   
   use Yii;
   use yii\web\Controller;
   use yii\helpers\Url;
   
   
   class SamlController extends Controller {
   
       // Remove CSRF protection
       public $enableCsrfValidation = false;
   
       public function actions() {
           return [
               ...
               'acs' => [
                   'class' => 'asasmoyo\yii2saml\actions\AcsAction',
                   'successCallback' => [$this, 'callback'],
                   'successUrl' => Url::to('site/welcome'),
               ]
           ];
       }
   
       /**
        * @param array $param has 'attributes', 'nameId' , 'sessionIndex', 'nameIdNameQualifier' and 'nameIdSPNameQualifier' from response
        */
       public function callback($param) {
           // do something
           //
           // if (isset($_POST['RelayState'])) {
           // $_POST['RelayState'] - should be returnUrl from login action
           // }
       }
   }

   注意：请确保在身份提供者中将 acs 操作的 URL 注册到 AssertionConsumerService，并将 sls 操作的 URL 注册到 SingleLogoutService（如果支持）。

3. MetadataAction

   此操作将显示您应用程序的元数据（xml）。要使用此操作，只需将其注册到您控制器中的操作即可。

   <?php
   
       public function actions() {
           return [
               ...
               'metadata' => [
                   'class' => 'asasmoyo\yii2saml\actions\MetadataAction'
               ]
           ];
       }

4. LogoutAction

   此操作将启动到身份提供者的单点退出过程。要使用此操作，只需将其注册到您控制器中的操作即可。

   <?php
       $session = Yii::$app->session;
       public function actions() {
           return [
               ...
               'logout' => [
                   'class' => 'asasmoyo\yii2saml\actions\LogoutAction',
                   'returnTo' => Url::to('site/bye'),
                   'parameters' => [],
                   'nameId' => $session->get('nameId'),
                   'sessionIndex' => $session->get('sessionIndex'),
                   'stay' => false,
                   'nameIdFormat' => null,
                   'nameIdNameQualifier' => $session->get('nameIdNameQualifier'),
                   'nameIdSPNameQualifier' => $session->get('nameIdSPNameQualifier'),
                   'logoutIdP' => false, // if you don't want to logout on idp
               ]
           ];
       }

5. SlsAction

   此操作将处理身份提供者发送的 saml 登出请求/响应。要使用此操作，只需将其注册到您控制器中的操作即可。

   <?php
   
       public function actions() {
           ...
   
           return [
               ...
               'sls' => [
                   'class' => 'asasmoyo\yii2saml\actions\SlsAction',
                   'successUrl' => Url::to('site/bye'),
                   'logoutIdP' => false, // if you don't want to logout on idp
               ]
           ]
       }

使用方法

如果 SAMLResponse 被拒绝，请将以下参数添加到 SAML 设置中

'debug' => true,

并将提示原因。

许可证

MIT 许可证