FuelPHP，PHP 5.3 框架 简体中文手册

OrmAuth - 简介

Ormauth 是一組提供與 Simpleauth 类似功能的認證和授权驅动， 但儲存其資料在資料庫而非配置档案中。該資料透過 ORM 模型來存取。

除此之外，它還配備了額外的功能。不像 Simpleauth，Ormauth 支援直接指派角色給使用者， 并指派權限給使用者和群組，允許更加細緻的權限系统。 它不是把使用者的詮釋資料儲存在一个序列化的陣列，而是一張单獨的詮釋資料的資料表，使用 ORM 的 EAV 功能， 能让你像任何其他的使用者特性一樣存取詮釋資料。它也会追踪先前的登入時間， 它可以做为在登入時顯示給使用者的一个額外的安全措施。

Auth 設置

配置開始於告知 Auth 套件你即将使用 Ormauth 驅动。 这是透過 auth.php 配置档案做到。預設档案在 Auth 套件中被提供。 在做任何變更前，你應該複製此档案到你的 app/config 文件夾。 預設档案已经为 Simpleauth 套件配置，所以你需要變更它。你将在此配置档案的这裡找到說明。

在你完成後，你可以選擇透過 app/config/config.php 的 always_load 段落來自动載入套件。

因为 OrmAuth 使用 ORM 來存取資料庫，確保你也已经添加 'orm' 套件到 always_load 段落！

ACL

OrmAuth 有比 SimpleAuth 更細緻的 ACL 系统。它使用标准 ORM 關聯來为任何所給的使用者建構權限組， 并有以下的結構：

• 每个使用者是一个群組（對，就是一个）的一員
• 每个使用者可以有零个或多个指派給它的角色
• 每个群組可以有零个或多个指派給它的角色
• 每个使用者可以有零个或多个指派給它的權限
• 每个群組可以有零个或多个指派給它的權限
• 每个角色可以有零个或多个指派給它的權限
• 每个權限屬於一个權限區域
• 每个權限可以有零个或多个關聯的动作

所有權限是每个使用者的集合。角色可以有特別的權限過濾器， 这可能改變指派集合的權限。他們是：

• "All access"，存为 "A"。有这个角色的使用者可以存取全部。这通常是用在 'super-admin' 角色。它推翻所有權限設定。
• "No access"，存为 "D"。有这个角色的使用者無法存取。这通常是用在 'banned' 角色。它推翻所有權限設定。
• "Revoke permissions"，存为 "R"。設定在此角色的權限会從集合權限設定中被移除。

請注意，"revoked" 權限在所有其他權限之前被檢查。这能让你建立像这樣的權限結構： 「这个 super-admin 可以存取全部，除了应用程序極機密的區域」……

指派權限是使用标准的 ORM 關聯，而且非常直接了當：

// 取得識別为 $role_id 的角色
$role = \Model\Auth_Role::find($role_id);

// 取得識別为 $perm_id 的權限
$perm = \Model\Auth_Permission::find($perm_id);

// 關聯兩者
$role->permissions = $perm;

// 并保存關聯
$role->save();

动作

如上所述，你可以透過添加一个權限的动作列表（區域和權限的組合）來添加額外的細緻度。

动作儲存在權限紀錄中做为一个字串陣列索引，透過 ORM 自动序列化和反序列化。 你可以盡量定義你想要的动作，并選擇任何你喜歡的字串。如果需要， 这能让你以一个形式對每一个动作設定每个權限，更細緻的，在你任何可能需要的時候！

定義在權限上的动作列表在指派權限給一个使用者、一个群組、或一个角色時，指定可以被指派的可能动作。 指派的动作儲存为一个鍵的陣列，它定義哪些动作被指派。

// 如果这些是可能的动作：
array('add', 'view', 'edit', 'delete')

// 然後你應該在指派 'view' 和 'edit' 時儲存它：
array(1, 2)

要儲存它，ORM 模型已经提供直接存取關聯， 或透過不管是連結到 user、role 或 group 資料表的權限。

// 取得識別为 $role_id 的角色
$role = \Model\Auth_Role::find($role_id);

// 取得識別为 $perm_id 的權限
$perm = \Model\Auth_Permission::find($perm_id);

// 關聯兩者，添加部份選定的动作
$role->rolepermission[] = \Model\Auth_Rolepermission::forge(array(
	'role_id' => $role->id,
	'perms_id' => $perm->id,
	'actions' => array(1,2),
));

// 并保存關聯
$role->save();

當檢查存取時，你指定所需的存取为 area.permission 當你想要檢查单一權限， area.[permission,permission,...] 當你想要一次檢查多个權限， 或如果你想要檢查關聯动作，你可以使用 area.permission[action,action,...]。这是一个 AND 檢查， 所以當你指定多个權限時，該使用者必須要有全部指派權限才能授权存取。 这能让你建構像 blog.comments[read,create,write,write-own,delete,delete-own] 的檢查。

快取

为了減少資料庫 I/O，OrmAuth 驅动大量使用快取，來避免登入的使用者在每个頁面請求必須檢索整个權限設定。 在你開始使用 OrmAuth 之前，確保你的快取配置已经設置。

所有快取條目帶有定義在 OrmAuth 配置档案中的前綴。他們建立時沒有過期時間戳記， 所以當你設計你的管理後端，確保在一个更新後有刪除所需的快取條目，如此快取可以被刷新。

以下的快取鍵被 OrmAuth 使用：

• <prefix>.groups - 所有定義群組的完整列表
• <prefix>.roles - 所有定義角色的完整列表
• <prefix>.permissions.user_<id> - 給使用者 <id> 的有效權限

在一个權限系统的更新後，確保清除快取的權限，并且，如果你有變更角色或群組定義， 也清除他們。

// 清除单一使用者（ID 12211）的權限
\Cache::delete(\Config::get('ormauth.cache_prefix', 'auth').'.permissions.user_12211');

// 清除所有快取的權限
\Cache::delete_all(\Config::get('ormauth.cache_prefix', 'auth').'.permissions');

// 清除所有快取的群組
\Cache::delete(\Config::get('ormauth.cache_prefix', 'auth').'.groups');

// 清除所有快取的角色
\Cache::delete(\Config::get('ormauth.cache_prefix', 'auth').'.roles');

配置

Ormauth 認證系统是透過一个配置档案來配置，不意外地稱为 'ormauth.php'。 預設档案在 Auth 套件中有提供。 在你做任何變更前，你應該複製該档案到你的 app/config 文件夾。

以下配置值可以被定義：

null

'users'

array('*')

'auth'

true

array(
	'enabled' => false,
	'cookie_name' => 'rmcookie',
	'expiration' => 86400*31
)

false

'put_some_salt_in_here'

'username'

'password'

如果你想要使用 'remember-me' 功能，確保你有一个有效的 Crypt 配置， 因为它使用一个加密的 cookie 來儲存要被記憶的使用者資訊。

資料庫表

OrmAuth 依賴一張資料表，Auth 套件包含要建立此資料表所需的迁移档案。
只要运行 oil refine migrate --packages=auth 來为你建立这些資料表。

範例

这是一个简单的登入动作：

public function action_login()
{
	$data = array();

	// 如果你按下提交按鈕，让我們跑整个步驟。
	if (Input::post())
	{
		// 檢查認證，这裡假設你已经建立上表，且
		// 你已经使用如上所述的資料表定義和配置。
		if (Auth::login())
		{
			// 認證成功，進入。
			Response::redirect('success_page');
		}
		else
		{
			// 哎呀，沒你的湯，再试著登入一次。設定一些值來
			// 重填使用者名稱欄位，并給一些错误的文字到檢視。
			$data['username']    = Input::post('username');
			$data['login_error'] = 'Wrong username/password combo. Try again';
		}
	}

	// 顯示登入表单。
	echo View::forge('auth/login',$data);
}