diff --git a/proposed/authorisation-service-meta.md b/proposed/authorisation-service-meta.md new file mode 100644 index 0000000..17b3430 --- /dev/null +++ b/proposed/authorisation-service-meta.md @@ -0,0 +1,106 @@ +# Authorisation Service Meta Document + +## 1. Summary + +Authorization is the function of specifying access rights/privileges to resources related to information security and computer security in general and to access control in particular. More formally, "to authorize" is to define an access policy. [Wikipedia](https://en.wikipedia.org/wiki/Authorization) + +This specification aims to define a minimal interface for a service allowing to use Role Based Access Control in components, if they need to. + +## 2. Why Bother? + +While standard permissions can be implemented in way that components do not need to address it themselves, some components might need a more fine grained access to the permissions. A standardised interface enables 3PD to develop authorisation services which can be consumed by those components without having to deal with implementation details. + +## 3. Scope + +### 3.1 Goals + +This specification aims to provide robust interfaces for querying permissions and related information from Authorisation Services that are independent from the particular implementation. + +### 3.2 Non-Goals + +This specification does not seek to standardise or favor any particular implementation. +The setup and creation of roles and permissions is up to the implementation and not part of this specification. + +## 4. Approaches + +Privileges are three-dimensional: + + * **Actor** - a user or a role + * **Action** - a verb, sometimes with an intrinsic object + * **Target** - an entity or a class of entities + +### 4.1 Access Control in the User Object + +#### Examples + +##### Zizaco/[Entrust][]: + +```php +$allowed = $user->hasRole('admin'); +$allowed = $user->can('edit-user'); +``` + +##### Joomla 3.7: + +```php +$allowed = JFactory::getUser()->authorise('core.delete', 'com_content.article.' . (int) $record->id) +``` + +#### 4.1.1 Projects Using Access Control in the User Object + + * Joomla 3 + * Zizaco/[Entrust][] (Laravel 5 Package) + +### 4.2 Separated Access Control + +#### 4.2.1 Projects Using Separated Access Control + +### 4.3 Comparison of Approaches + +While having access control in the user object seems very convenient, it requires the user object to support access control explicitly, which violates the [Single Responsibility Principle][]. + +### 4.4 Chosen Approach + +This specification follows the Separated Access Control approach. + +## 5. Design Decisions + +* Some actions, like for example 'access-dashboard', do not need an entity to be applied to. + They operate on an 'intrinsic' target, in this case the dashboard. + The interfaces make the corresponding parameter optional to address such cases. + It is up to then implementation to check if the supplied information is sufficient. +* The service API is separated into two interfaces. + * The *Basic Authorisation Service* interface covers the most widely spread use case for an authentication service and should be easy to implement upon any authorisation solution. + * The *Extended Authorisation Service* allows the access to a whole dimension (actors, actions or targets), when the two other values are known. They are very useful in some special cases, but not needed in average components. + +## 6. People + +### 6.1 Editor(s) + +* Niels Braczek, + +### 6.2 Sponsors + +* N/A + +### 6.3 Contributors + +* Klas Berlič Fras, + +## 7. Votes + +* **Entrance Vote:** _(not yet taken)_ +* **Acceptance Vote:** _(not yet taken)_ + +## 8. Relevant Links + +* Wikipedia article on [Single Responsibility Principle][] +* [Bouncer](https://github.com/JosephSilber/bouncer) is an elegant, framework-agnostic approach to managing roles and abilities for any app using Eloquent models. +* [Entrust][] is a succinct and flexible way to add Role-based Permissions to Laravel 5. + +[Single Responsibility Principle]: https://en.wikipedia.org/wiki/Single_responsibility_principle +[Entrust]: https://github.com/Zizaco/entrust + +## 9. Errata + +... diff --git a/proposed/authorisation-service.md b/proposed/authorisation-service.md new file mode 100644 index 0000000..30f1cc6 --- /dev/null +++ b/proposed/authorisation-service.md @@ -0,0 +1,94 @@ +# Authorisation Service + +This document describes ... + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119][]. + +[RFC 2119]: http://tools.ietf.org/html/rfc2119 + +### References + +- [RFC 2119][]: Key words for use in RFCs to Indicate Requirement Levels + +## 1. Specification + +### 1.1 Basic Authorisation Service + +### 1.2 Extended Authorisation Service + +## 2. Interfaces + +### 2.1 AuthorisationServiceInterface + +The following interface MUST be implemented by compatible Basic Authorisation Services. + +```php +namespace Joomla\Service\Authorisation + +/** + * Basic Authorisation Service Interface + */ +interface AuthorisationServiceInterface +{ + /** + * Check if a particular user is allowed to take a particular action on a particular class or object. + * + * @param UserInterface $actor The user that will take action + * @param string $action The action to be taken + * @param string|object $target The class or object to act on. + * May be omitted, if `$action` does not require an object. + * + * @return bool + */ + public function isAllowed($actor, $action, $target = null): bool; +} +``` + +### 2.2 ExtendedAuthorisationServiceInterface + +The following interface MUST be implemented by compatible Extended Authorisation Services. + +```php +namespace Joomla\Service\Authorisation + +/** + * Extended Authorisation Service Interface + */ +interface ExtendedAuthorisationServiceInterface +{ + /** + * Get a list of actors (users) that are allowed to take an action on a particular target (class or object). + * + * @param string $action The action to be taken + * @param string|object $target The class or object to act on. + * May be omitted, if `$action` does not require an object. + * + * @return UserInterface[] + */ + public function getActors($action, $target = null): array; + + /** + * Get a list of actions that a particular actor (user) is allowed to take on a particular target (class or object). + * + * @param UserInterface $actor The user that will take action + * @param string|object $target The class or object to act on. + * May be omitted, if `$action` does not require an object. + * + * @return string[] + */ + public function getActions($actor, $target = null): array; + + /** + * Get a list of targets (objects) that a particular actor (user) is allowed to take a particular action on. + * + * @param UserInterface $actor The role or user that will take action + * @param string $action The action to be taken + * @param string $targetClass Optionally restrict to a particular entity class. + * + * @return object[] + */ + public function getObjects($actor, $action, $targetClass = null): array; +} +```