Class \Prado\Security\Permissions\TPermissionsManager

TPermissionsManager class.

TPermissionsManager handles Permissions authorization and Roll Based Access Control (RBAC). Each registered Permission is given a set of TAuthorizationRules. The RBAC is based on roles having children roles and permissions, with permissions being thought of as special roles themselves.

TPermissionsManager attaches TPermissionsBehavior to all classes that implement IPermissions. This is the main mechanism by which application permissions are registered.

The role hierarchy and permission rules are unique to each application. The permissions configuration is defined in the TPermissionsManager application configuration or in a separate PermissionsFile. TPermissionsConfigurationBehavior enables a page configuration to have Permission Configurations as well. A TDbParameterModule can be specified with getDbParameter for loading dynamic roles and permissions.

Module XML configurations (and similarly PermissionFile) follows the format, eg:

<module id="permissions" class="Prado\Security\Permissions\TPermissionsManager" DefaultRoles="Default" SuperRoles="Administrator">
<role name="Developer" children="all, param_shell_permission, cron" />
<role name="Manager" children="editor, change_user_role_permission, cron_shell" />
<role name="cron_shell" children="cron_add_task, cron_update_task, cron_remove_task" />
<role name="cron" children="cron_shell, cron_manage_log, cron_add_task, cron_update_task, cron_remove_task" />
 <role name="Default" children="register_user, blog_read_posts, blog_comment">
<permissionrule name="param_shell_permission" action="deny" users="*" roles="" verb="*" IPs="" />
<permissionrule name="cron_shell" action="allow" users="*" roles="Developer,cron_shell,cron_manage_log" verb="*" IPs="" />
<permissionrule name="register_user" action="allow" users="?" />
<permissionrule name="register_user" action="allow" roles="Manager" />
<permissionrule name="change_profile" action="deny" users="?" priority="0" />
<permissionrule name="blog_update_posts" class="Prado\Security\Permissions\TUserOwnerRule" Priority="5" />
<permissionrule name="cron" action="allow" users="admin, user1, user2" roles="*" verb="*" IPs="*"  />
<permissionrule name="blog_*" action="allow" users="admin, user1, user2" roles="*" verb="*" IPs="*"  />
<permissionrule name="*" action="deny" priority="1000" />
</module>

and in PHP the same file would follow the following format, eg:

'modules' => [
'permissions' => ['class' => 'Prado\Security\Permissions\TPermissionsManager',
		'properties' => ['DefaultRoles' => 'Default', 'SuperRoles' => "Administrator"],
	'roles' => [
		'Developer' => ['all', 'param_shell_permission', 'cron'],
		'Manager' => ['editor', 'change_user_role_permission', 'cron_shell'],
		'cron_shell' => ['cron_add_task', 'cron_update_task', 'cron_remove_task'],
		'cron' => ['cron_shell', 'cron_manage_log', 'cron_add_task', 'cron_update_task', 'cron_remove_task'],
		'Default' => ['register_user', 'blog_read_posts', 'blog_comment'],
	],
		'permissionRules' => [
		[name => 'param_shell_permission', 'action' => 'deny', 'users' => '*', roles => '*', 'verb' => '*', 'IPs' =>''],
		[name => 'cron_shell', 'action' => 'allow', 'users' => 'Developer,cron_shell,cron_manage_log', roles => 'cron_shell', 'verb' => '*', 'IPs' =>''],
		[name => 'register_user', 'action' => 'allow', 'users' => '?'],
		[name => 'register_user', 'action' => 'allow', 'roles' => 'Manager'],
		[name => 'change_profile', 'action' => 'deny', 'users' => '?', 'priority' => '0'],
		[name => 'blog_update_posts', 'class' => 'Prado\Security\Permissions\TUserOwnerRule', 'priority' => '5'],
		[name => 'cron', 'action' => 'allow', 'users' => 'admin, user1, user2'],
		[name => 'blog_*', 'action' => 'allow', 'users' => 'admin, user1, user2'],
		[name => '*', 'action' => 'deny', 'priority' => 1000]
	]
]

In this example, "cron" is not a permission, but when used as a permission, all children roles/permissions will receive the rule. Permissions with children, such as 'cron_shell' (above), will give all its children the rule as well.

A special role "All" is automatically created to contain all the permissions. Specifying "all" as a child, is the same as specifying a role as a super role via setSuperRoles.

All users get the roles specified by getDefaultRoles. This changes the default Prado behavior for guest users having no roles.

Intermediate roles, that are not defined in the user system, may be defined in the hierarchy, in the above example the "cron" role is not defined by the system, but is defined in the role hierarchy.

Permission Rules can have multiple rules. they are ordered by natural specified configuration order unless the rule property TAuthorizationRule::setPriority is set.

Permissions authorization rules may use the '' or 'perm_' to add the rules to all matching permission names. Anything before the * is matched as a permission. This does not traverse the hierarchy roles matching the name, just the permissions are matched for the TAuthorizationRule.

A permission name must list itself as a role in TAuthorizationRule for the user to be validated for that permission name for authorization. This is handled automatically by TPermissionManager with the getAutoAllowWithPermission property. By default getAutoAllowWithPermission is true, and allows any user with that permission in their hierarchy to allow access to the functionality. This rule priority can be set with getAutoRulePriority, where the default is 5, and -thus- before user defined rules.

The second automatic rules includes Modules have their own preset rules that can be automatically added via getAutoPresetRules. By default this is true. These rules typically allow owners of the data to be permitted without having a permission-role. Preset rules can define their own priorities but those without set priorities receive the priority from getAutoRulePriority.

The third, and last, auto-Rule is the final \Prado\Security\Permissions\getAutoDenyAll rule. This is the last rule that denies all by default. The AutoDenyAll gets its rule priority from getAutoDenyAllPriority. By default, deny all to all permissions is enabled and thus blocking all permissions.

Recursive hierarchy is gracefully handled, in case of any loop structures.

When TPermissionsManager is a module in your app, there are three permissions to control user access to its function:

TPermissionsManager::PERM_PERMISSIONS_SHELL 'permissions_shell' enables the shell commands.
TPermissionsManager::PERM_PERMISSIONS_MANAGE_ROLES 'permissions_manage_roles' enables adding and removing roles and children.
TPermissionsManager::PERM_PERMISSIONS_MANAGE_RULES 'permissions_manage_rules' enables adding and removing rules for permissions and roles.

The role and rule management functions only work when the TDbParameter Module is specified. The following gives user "admin" and all users with "Administrators" role the permission to access permissions shell and its full functionality:

 <role name="permissions_shell" children="permissions_manage_roles, permissions_manage_rules" />
  <permissionrule name="permissions_shell" action="allow" users="admin" />
  <permissionrule name="permissions_shell" action="allow" roles="Administrators" />
```php

Class hierarchy

\Prado\Security\Permissions\TPermissionsManager implements IPermissions

\Prado\TModule implements IModule

\Prado\TApplicationComponent

\Prado\TComponent

Author: Brad Anderson <belisoful@icloud.com>
Since: 4.2.0

Methods summary
`public`	`__destruct() : mixed` detaches the automatic class behaviors
`public`	`addPermissionRule(string $permission, TAuthorizationRule $rule) : bool` This method adds permission rules with in the runtime context.
`public`	`addRoleChildren(string $role, string\|array<string\|int, string> $children) : bool` This adds children to a role within the runtime context. The children can be a single comma separated string.
`public`	`getAutoAllowWithPermission() : bool`
`public`	`getAutoDenyAll() : bool`
`public`	`getAutoDenyAllPriority() : numeric-string\|int\|float`
`public`	`getAutoPresetRules() : bool`
`public`	`getAutoRulePriority() : numeric-string\|int\|float`
`public`	`getDbConfigPermissionRules() : array<string, array<string\|int, TAuthorizationRule>>` Get the permission rules that are runtime from the database
`public`	`getDbConfigRoles() : array<string, array<string\|int, string>>` Get the roles that are runtime from the database
`public`	`getDbParameter() : TDbParameterModule`
`public`	`getDefaultRoles() : null\|array<string\|int, string>` Gets the default roles of all users.
`public`	`getHierarchyRoleChildren(string $role) : null\|array<string\|int, string>` Gets the children for a specific role in the hierarchy.
`public`	`getHierarchyRoles() : array<string\|int, string>` Gets all the roles in the hierarchy, though may not be valid roles in the application.
`public`	`getLoadParameter() : string`
`public static`	`getManager() : TPermissionsManager\|null`
`public`	`getPermissionDescription(string $permissionName) : string` gets the short description of the permission
`public`	`getPermissionFile() : string`
`public`	`getPermissionRules(null\|string $permission) : null\|array<string, TAuthorizationRuleCollection>\|TAuthorizationRuleCollection`
`public`	`getPermissions(TPermissionsManager $manager) : array<string\|int, TPermissionEvent>`
`public`	`getSuperRoles() : null\|array<string\|int, string>` All super roles will get "all" roles and thus all permissions on module init.
`public`	`init(array<string\|int, mixed>\|TXmlElement $config) : mixed` Initializes the module.
`public`	`isInHierarchy(array<string\|int, string> $roles, string $permission[, array<string, bool> &$checked = [] ]) : mixed` checks if the $permission is in the $roles hierarchy.
`public`	`loadPermissionsData(array<string\|int, mixed>\|TXmlElement $config) : mixed` Loads the roles, children, and permission rules.
`public`	`registerPermission(string $permissionName, string $description[, null\|array<string\|int, TAuthorizationRule> $rules = null ]) : mixed` Registers a permission name with description and preset rules.
`public`	`registerShellAction(object $sender, null\|mixed $param) : mixed`
`public`	`removePermissionRule(string $permission, TAuthorizationRule $rule) : bool` This method removes permission rules with in the runtime context.
`public`	`removeRoleChildren(string $role, string\|array<string\|int, string> $children) : bool` This removes children from a role within the runtime context. The children can be a single comma separated string.
`public`	`setAutoAllowWithPermission(bool $enable) : mixed`
`public`	`setAutoDenyAll(bool $enable) : mixed`
`public`	`setAutoDenyAllPriority(numeric-string\|int\|float $priority) : mixed`
`public`	`setAutoPresetRules(bool $enable) : mixed`
`public`	`setAutoRulePriority(numeric-string\|int\|float $priority) : mixed`
`public`	`setDbParameter(IUserManager\|string $provider) : mixed`
`public`	`setDefaultRoles(string\|array<string\|int, string> $roles) : mixed`
`public`	`setLoadParameter(string $value) : mixed`
`public`	`setPermissionFile(string $value) : mixed`
`public`	`setSuperRoles(string\|array<string\|int, string> $roles) : mixed` sets the super roles to get all permissions.
`protected`	`addPermissionRuleInternal(string $name, TAuthorizationRule\|array<string\|int, TAuthorizationRule> $rule) : mixed` Adds a permission rule to a permission name. Names can contain the '' character and every permission with a matching name before the '' will get the rule
`protected`	`removePermissionRuleInternal(string $name, TAuthorizationRule $rule) : mixed` Removes a permission rule from a permission name.

Inherited methods
__call, __callStatic, __clone, __construct, __destruct, __get, __isset, __set, __sleep, __unset, __wakeup, addParsedObject, asa, attachBehavior, attachBehaviors, attachClassBehavior, attachEventHandler, callBehaviorsMethod, canGetProperty, canSetProperty, clearBehaviors, createdOnTemplate, detachBehavior, detachBehaviors, detachClassBehavior, detachEventHandler, disableBehavior, disableBehaviors, enableBehavior, enableBehaviors, evaluateExpression, evaluateStatements, fxAttachClassBehavior, fxDetachClassBehavior, getApplication, getAutoGlobalListen, getBehaviors, getBehaviorsEnabled, getClassHierarchy, getEventHandlers, getID, getListeningToGlobalEvents, getRequest, getResponse, getService, getSession, getSubProperty, getUser, hasEvent, hasEventHandler, hasMethod, hasProperty, init, isa, listen, publishAsset, publishFilePath, raiseEvent, setID, setSubProperty, unlisten, _getZappableSleepProps, getCallChain, getClassFxEvents, instanceBehavior, filter_prado_fx

Constants summary
`public mixed`	`PERM_PERMISSIONS_MANAGE_ROLES`	`'permissions_manage_roles'`
`public mixed`	`PERM_PERMISSIONS_MANAGE_RULES`	`'permissions_manage_rules'`
`public mixed`	`PERM_PERMISSIONS_SHELL`	`'permissions_shell'`
`public mixed`	`PERMISSIONS_BEHAVIOR`	`'permissions'`
`public mixed`	`PERMISSIONS_CONFIG_BEHAVIOR`	`'permissionsConfig'`
`public mixed`	`USER_PERMISSIONS_BEHAVIOR`	`'usercan'`

Inherited constants
`\Prado\TApplicationComponent::FX_CACHE_FILE, \Prado\TComponent::GLOBAL_RAISE_EVENT_LISTENER`

Classes

Interfaces

Traits

Search results

Class \Prado\Security\Permissions\TPermissionsManager

Class hierarchy