README

sfDoctrineGuardPlugin是一个symfony插件，它提供了比symfony标准安全特性更高级别的认证和授权功能。

它提供模型（用户、组和权限对象）以及模块（后端和前端），通过可配置的插件，只需一分钟即可保护您的symfony应用程序。

从5.0.0版本开始（1.4稳定分支），sfDoctrineGuardPlugin还提供了通过网站申请账户的选项（默认情况下是禁用的），以及忘记密码时重置密码的能力。出于安全考虑，密码重置需要您知道与账户关联的电子邮件地址并且能够接收那里的邮件。然而，在5.0.0中申请账户并不需要收到电子邮件消息。

5.x系列在从早期版本迁移时可能需要大量的迁移工作。请参阅升级部分以获取更多信息。

安装

• 使用composer安装插件

  composer require lexpress/sf-doctrine-guard-plugin
  

• 在config/ProjectConfiguration.class.php中激活插件

  class ProjectConfiguration extends sfProjectConfiguration
  {
    public function setup()
    {
      $this->enablePlugins(array(
        'sfDoctrinePlugin',
        'sfDoctrineGuardPlugin',
        '...'
      ));
    }
  }

• 重新构建您的模型

  symfony doctrine:build-model
  symfony doctrine:build-sql
  

• 从零开始更新您的数据库表（这将删除所有现有表，然后重新创建它们）

  symfony doctrine:insert-sql
  

  或者通过一条命令完成所有操作

  symfony doctrine-build-all-reload frontend
  

  或者您可以使用在data/sql/plugins.sfGuardAuth.lib.model.schema.sql中生成的SQL语句创建新表

• 加载默认的固件（可选 - 它创建一个超级管理员用户）

  mkdir data/fixtures/
  cp plugins/sfDoctrineGuardPlugin/data/fixtures/fixtures.yml.sample data/fixtures/sfGuard.yml
  
  symfony doctrine:data-load frontend # replace frontend with the name of one of your application
  

• 在您的settings.yml中启用一个或多个模块（可选）

  • 对于您的后端应用程序：sfGuardUser, sfGuardGroup, sfGuardPermission

        all:
          .settings:
            enabled_modules:      [default, sfGuardGroup, sfGuardUser, sfGuardPermission]
    

  请注意：这些模块默认情况下不是安全的，因为我们无法猜测您想要的政策是什么。请阅读下方的“保护您的应用程序”部分。

  • 对于您的前端应用程序：sfGuardAuth

        all:
          .settings:
            enabled_modules:      [default, sfGuardAuth]
    

  不要保护sfGuardAuth，它是一个允许用户登录的模块。

• 清除您的缓存

  symfony cc
  

• 可选地，在安全过滤器上方添加“记住我”过滤器到filters.yml

  remember_me:
    class: sfGuardRememberMeFilter
  
  security: ~
  

升级

5.0.x系列添加了几个新表，向现有表添加了列，并更改了模式中所有关系的名称。

这需要两种类型的更改：数据库模式更改以及在某些情况下，对您的代码进行更改。我们将依次查看这些问题。

更新您的模式

模式中有三个基本更改

• 所有主键ID列都已更改为8字节整数
• sfGuardUser表中新增列，现在包含first_name、last_name和email_address信息
• 新增的sfGuardForgotPassword表用于验证密码重置请求和账户创建请求

升级到8字节整数

使用Doctrine的generate-migrations-diff任务来更新模式会很有帮助，但不幸的是，虽然它是一个强大的工具，但它无法确定如何更改ID列到8字节而不会出现外键错误。您可以自己编写迁移，或者简单地使用SQL ALTER TABLE语句。如果您选择这样做，您需要首先删除外键索引（当然不是列，只是索引），更改ID列的类型，然后再次创建外键索引。我们建议在此过程中锁定数据库。

您也可以在现有的数据库中保留ID的类型。这样做会更加简单。如果您选择这种方法，请确保按照以下说明创建新的sfGuardForgotPassword表，使用与旧表相同的4字节整数。

添加新列

sf_guard_user表中有三个新列。您可以使用以下SQL语句添加这些列

ALTER TABLE sf_guard_user ADD COLUMN first_name varchar(255) DEFAULT NULL;
ALTER TABLE sf_guard_user ADD COLUMN last_name varchar(255) DEFAULT NULL;
ALTER TABLE sf_guard_user ADD COLUMN email_address varchar(255) DEFAULT '';

接下来，您应该指定电子邮件地址必须是唯一的。如果您的现有系统中用户根本没有任何电子邮件地址字段（例如，您没有用户资料表，或者其中没有电子邮件地址），这将引发问题。您可以这样做作为临时解决方案

UPDATE sf_guard_user SET email_address = username;

这确保了唯一性设置，但实际上并没有提供有用的电子邮件地址。如果您有包含电子邮件地址的用户资料表，更好的做法是从那里导入电子邮件地址

UPDATE sf_guard_user,sf_guard_profile SET sf_guard_user.email_address = sf_guard_profile.email_address WHERE sf_guard_user.id = sf_guard_profile.id;

现在您可以为该列创建索引并使其唯一

ALTER TABLE sf_guard_user ADD UNIQUE KEY `email_address` (`email_address`);

添加sfGuardForgotPassword表

您可以使用以下SQL代码来完成此操作。

如果您希望继续使用4字节ID

CREATE TABLE sf_guard_forgot_password (id INT AUTO_INCREMENT, user_id INT NOT NULL, unique_key VARCHAR(255), expires_at DATETIME NOT NULL, created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL, INDEX user_id_idx (user_id), PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci ENGINE = INNODB;

如果您已经升级了ID

CREATE TABLE sf_guard_forgot_password (id BIGINT AUTO_INCREMENT, user_id BIGINT NOT NULL, unique_key VARCHAR(255), expires_at DATETIME NOT NULL, created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL, INDEX user_id_idx (user_id), PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci ENGINE = INNODB;

更新您的代码

如果您尚未迁移数据库模式，请先这样做（参见上面）。 否则，您将失去使用Doctrine迁移的选项。

在更新您的模式后，您还需要更新代码以适应这些更改。

首先重建您的模型、表单和过滤器基类。只要您遵循标准实践并保持Base类不变，这不会损坏您自己的模型类中的任何自定义代码

./symfony doctrine:build --all-classes

其次，检查您的Doctrine代码中定义了sfGuardUser、sfGuardGroup等的关系的位置。出于方便和遵循Symfony最佳实践，这些关系的名称已经更改。

更改的最常用的关系如下

$group->users现在为$group->Users（大写） $group->permissions现在为$group->Permissions（大写） $user->groups现在为$user->Groups（大写） $user->permissions现在为$user->Permissions（大写）

在sfGuardUserPermission和sfGuardGroupPermission上使用较少的关系也发生了变化。它们是大写的，并且没有sfGuard前缀。有时编写自定义查询以查找具有特定权限的用户的人需要注意到这一点。

保护您的应用程序

为了保护symfony应用程序

• 在settings.yml中启用模块sfGuardAuth

  all:
    .settings:
      enabled_modules: [..., sfGuardAuth]
  

• 在settings.yml中更改默认登录和安全模块

  login_module:           sfGuardAuth
  login_action:           signin
  
  secure_module:          sfGuardAuth
  secure_action:          secure
  

• 在myUser.class.php中更改父类

  class myUser extends sfGuardSecurityUser
  {
  }

• 可选地，将以下路由规则添加到routing.yml

  sf_guard_signin:
    url:   /login
    param: { module: sfGuardAuth, action: signin }
  
  sf_guard_signout:
    url:   /logout
    param: { module: sfGuardAuth, action: signout }
  
  sf_guard_register:
    url:   /register
    param: { module: sfGuardRegister, action: index }
  
  sf_guard_forgot_password:
    url:   /forgot_password
    param: { module: sfGuardForgotPassword, action: index }
  
  sf_guard_forgot_password_change:
    url:   /forgot_password/:unique_key
    class: sfDoctrineRoute
    options: { model: sfGuardForgotPassword, type: object }
    param: { module: sfGuardForgotPassword, action: change }
    requirements:
      sf_method: [get, post]
  

  您可以为每个路由自定义url参数。注意：您必须有一个@homepage路由规则（当用户注销时使用）

  如果启用模块sfGuardAuth，则这些路由将由插件自动注册，除非您在app.yml配置文件中将sf_guard_plugin_routes_register定义为false

  all:
    sf_guard_plugin:
      routes_register: false
  

• 在security.yml中保护某些模块或您的整个应用程序

  default:
    is_secure: true
  

• 您已完成。现在，如果尝试访问受保护的页面，您将被重定向到登录页面。如果您已加载默认固定文件，请使用admin作为用户名和admin作为密码进行登录。

• 如果您没有默认保护整个站点，请确保您确实保护了sfGuardUser、sfGuardGroup和sfGuardPermission模块！否则，匿名用户可以随时创建用户、组和权限。这是在sfDoctrineGuardPlugin网站上常见的疏忽。

管理您的用户、权限和组

为了能够管理您的用户、权限和组，sfDoctrineGuardPlugin提供了3个模块，可以集成到您的后端应用程序中。这些模块由symfony管理员生成器自动生成。

• 在settings.yml中启用模块

  all:
    .settings:
      enabled_modules: [..., sfGuardGroup, sfGuardPermission, sfGuardUser]
  

• 如果您没有对整个站点进行安全保护，请通过security.yml来保护这些模块。否则，匿名用户可以创建和删除用户

• 使用默认路由sf_guard_user访问模块

  http://www.example.com/backend.php/guard/users

账户申请

一些网站管理员希望允许公众成员申请账户。从5.0.0版本开始，这个功能在sfDoctrineGuardPlugin中可用。

要启用此功能，您必须启用sfGuardRegister模块，然后为用户提供一个链接到sfGuardRegister/index操作的链接。

[待完善] [待完善：记录忘记密码功能]

自定义sfGuardAuth模块模板

默认情况下，sfGuardAuth模块包含2个非常简单的模板

• signinSuccess.php
• secureSuccess.php

如果您想自定义这些模板之一

• 在您的应用程序中创建一个sfGuardAuth模块（不要使用init-module任务，只需创建一个sfGuardAuth目录）

• 在sfGuardAuth/templates目录中创建一个与您想要定制的模板同名的模板

• symfony现在将渲染您的模板而不是默认模板

自定义sfGuardAuth模块动作

如果您想自定义或向sfGuardAuth添加方法

• 在您的应用程序中创建一个sfGuardAuth模块

• 在您的actions目录中创建一个名为actions.class.php的文件，该文件继承自BasesfGuardAuthActions（不要忘记包含BasesfGuardAuthActions，因为它不能由symfony自动加载）

    require_once(sfConfig::get('sf_plugins_dir').'/sfDoctrineGuardPlugin/modules/sfGuardAuth/lib/BasesfGuardAuthActions.class.php');
  
    class sfGuardAuthActions extends BasesfGuardAuthActions
    {
      public function executeNewAction()
      {
        return $this->renderText('This is a new sfGuardAuth action.');
      }
    }

sfGuardSecurityUser类

该类继承自Symfony的sfBasicSecurityUser类，并用于symfony应用程序中的user对象。（记住，您之前更改了myUser基类。）

要访问它，您可以在动作中使用标准的$this->getUser()或在模板中使用$sf_user。

sfGuardSecurityUser添加了一些有用的方法

• signIn()和signOut()方法
• getGuardUser()，它返回sfGuardUser对象
• 一串代理方法，可以直接访问sfGuardUser对象

例如，获取当前用户名

  $this->getUser()->getGuardUser()->getUsername()

  // or via the proxy method
  $this->getUser()->getUsername()

超级管理员（"超级管理员"）标志

为了防止鸡生蛋的问题，sfDoctrineGuardPlugin有"超级管理员"的概念。超级管理员用户绕过所有凭证检查。

超级管理员标志不能通过sfGuardUser管理模块设置，您必须直接在数据库中设置标志或使用提供的Symfony任务

symfony guard:promote admin

验证器

sfDoctrineGuardPlugin提供了一个验证器，您可以在模块中使用：sfGuardUserValidator。

此验证器由sfGuardAuth模块在用户登录前用于验证用户名和密码。

使用外部方法检查用户密码

如果您不想因为已经有了LDAP服务器、.htaccess文件或者将密码存储在其他表中而在数据库中存储密码，您可以在app.yml中提供一个自己的checkPassword可调用（静态方法或函数）

all:
  sf_guard_plugin:
    check_password_callable: [MyLDAPClass, checkPassword]

当symfony调用$this->getUser()->checkPassword()方法时，它将调用您的方法或函数。您的函数必须接受两个参数，第一个是用户名，第二个是密码。它必须返回true或false。以下是一个此类函数的模板

  function checkLDAPPassword($username, $password)
  {
    $user = LDAP::getUser($username);
    if ($user->checkPassword($password))
    {
      return true;
    }
    else
    {
      return false;
    }
  }

更改存储密码时使用的算法

默认情况下，密码以sha1()哈希的形式存储。但是，您可以使用app.yml中的任何可调用函数更改此算法

all:
  sf_guard_plugin:
    algorithm_callable: [MyCryptoClass, MyCryptoMethod]

或者

all:
  sf_guard_plugin:
    algorithm_callable: md5

由于算法是为每个用户存储的，因此您可以稍后更改主意，而无需重新生成当前用户的密码。

更改"记住我"cookie的名称或过期期限

默认情况下，"记住我"功能会创建一个名为sfRemember的cookie，有效期15天。您可以在app.yml中更改此行为。

all:
  sf_guard_plugin:
     remember_key_expiration_age:  2592000   # 30 days in seconds
     remember_cookie_name:         myAppRememberMe

自定义sfGuardAuth重定向处理

在成功登录后可以将用户重定向到其个人资料，或在注销时重定向到特定页面。

您可以在app.yml中更改重定向设置。

all:
  sf_guard_plugin:
    success_signin_url:      @my_route?param=value # the plugin uses the referer as default
    success_signout_url:     module/action         # the plugin uses the referer as default