Skip to content

Commit 5a5bd2d

Browse files
dereuromarkdereuromark
committed
Fix up docs.
1 parent 342af0e commit 5a5bd2d

File tree

7 files changed

+160
-112
lines changed

7 files changed

+160
-112
lines changed

‎README.md‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ A CakePHP plugin to handle authentication and user authorization the easy way.
1212

1313
This branch is for **CakePHP 5.1+**. For details see [version map](https://github.com/dereuromark/cakephp-tinyauth/wiki#cakephp-version-map).
1414

15-
## Why use TinyAuth as a wrapper for Authentication/Authorization plugins?
15+
## Why use TinyAuth?
1616

17-
TinyAuth now acts as a powerful wrapper around CakePHP's official Authentication and Authorization plugins, providing significant advantages:
17+
**TinyAuth is a wrapper plugin** that extends CakePHP's official Authentication and Authorization plugins, providing significant advantages:
1818

1919
### 🚀 Zero-Code Configuration
2020
- **INI-based setup**: Define all your authentication and authorization rules in simple INI files
@@ -113,19 +113,32 @@ echo $this->AuthUser->postLink('Delete', ['action' => 'delete', $id], ['confirm'
113113
```
114114

115115
## Installation
116-
Including the plugin is pretty much as with every other CakePHP plugin:
116+
117+
### Required Dependencies
118+
119+
TinyAuth acts as a wrapper around CakePHP's official Authentication and Authorization plugins. You need to install them first:
120+
121+
```bash
122+
# Required for authentication features
123+
composer require cakephp/authentication
124+
125+
# Required for authorization features
126+
composer require cakephp/authorization
127+
```
128+
129+
Then install TinyAuth:
117130

118131
```bash
119132
composer require dereuromark/cakephp-tinyauth
120133
```
121134

122-
Then, to load the plugin:
135+
Finally, load the plugin:
123136

124137
```sh
125138
bin/cake plugin load TinyAuth
126139
```
127140

128-
That's it. It should be up and running.
141+
**Note:** The AuthUser component and helper can work standalone with any authentication solution. For the main TinyAuth.Authentication and TinyAuth.Authorization components, the official plugins are required dependencies.
129142

130143
## Docs
131144
For setup and usage see [Docs](/docs).

‎docs/Authentication.md‎

Lines changed: 13 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
# TinyAuth Authentication
22
The fast and easy way for user authentication in CakePHP applications.
33

4-
Use TinyAuth Component if you want to add instant (and easy) action whitelisting to your application.
4+
**IMPORTANT:** This component wraps the official CakePHP Authentication plugin.
5+
You must install it first - see [AuthenticationPlugin.md](AuthenticationPlugin.md).
6+
7+
Use TinyAuth Authentication Component if you want to add instant (and easy) INI-based action whitelisting to your application.
58
You can allow/deny per controller action or with wildcards also per controller and more.
69

710
## Basic Features
@@ -147,42 +150,18 @@ By default, it will not use caching in debug mode, though.
147150

148151
To modify the caching behavior set the ``autoClearCache`` configuration option:
149152
```php
150-
$this->loadComponent('TinyAuth.Auth', [
151-
'autoClearCache' => true|false
152-
)]
153-
```
154-
155-
## Multi Column authentication
156-
Often times you want to allow logging in with either username or email.
157-
In this case you can use the built-in adapter for it:
158-
159-
```php
160-
'authenticate' => [
161-
'TinyAuth.MultiColumn' => [
162-
'fields' => [
163-
'username' => 'login',
164-
'password' => 'password',
165-
],
166-
'columns' => ['username', 'email'],
167-
'userModel' => 'Users',
168-
],
169-
],
170-
```
171-
which you can pass in to Auth component as options.
172-
173-
Your form would then contain e.g.
174-
```php
175-
echo $this->Form->control('login', ['label' => 'Your username or email']);
176-
echo $this->Form->control('password', ['autocomplete' => 'off']);
153+
$this->loadComponent('TinyAuth.Authentication', [
154+
'autoClearCache' => true|false,
155+
]);
177156
```
178157

179158
## Configuration
180159

181160
TinyAuth Authentication component supports the following configuration options.
182161

183-
Option | Type | Description
184-
:----- | :--- | :----------
185-
autoClearCache|bool|True will generate a new ACL cache file every time.
186-
allowFilePath|string|Full path to the INI file. Can also be an array of paths. Defaults to `ROOT . DS . 'config' . DS`.
187-
allowFile|string|Name of the INI file. Defaults to `auth_allow.ini`.
188-
allowAdapter|string|Class name, defaults to `IniAllowAdapter::class`.
162+
Option | Type | Description
163+
:---------------|:-------|:---------------------------------------------------------------------------------------------------
164+
autoClearCache | bool | True will generate a new ACL cache file every time.
165+
allowFilePath | string | Full path to the INI file. Can also be an array of paths. Defaults to `ROOT . DS . 'config' . DS`.
166+
allowFile | string | Name of the INI file. Defaults to `auth_allow.ini`.
167+
allowAdapter | string | Class name, defaults to `IniAllowAdapter::class`.

‎docs/AuthenticationPlugin.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,18 @@
22

33
Support for [Authentication plugin](https://github.com/cakephp/authentication) usage.
44

5+
## Installation
6+
7+
First, you need to install the official CakePHP Authentication plugin:
8+
9+
```bash
10+
composer require cakephp/authentication
11+
```
12+
13+
See the [official Authentication plugin documentation](https://book.cakephp.org/authentication/2/en/index.html) for more details.
14+
15+
## Setup
16+
517
Instead of the core Auth component you load the Authentication component:
618

719
```php

‎docs/Authorization.md‎

Lines changed: 34 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# TinyAuth Authorization
22
The fast and easy way for user authorization in CakePHP applications.
33

4-
Enable TinyAuth Authorize if you want to add instant (and easy) role
4+
**IMPORTANT:** This component wraps the official CakePHP Authorization plugin. You must install it first - see [AuthorizationPlugin.md](AuthorizationPlugin.md).
5+
6+
Enable TinyAuth Authorization if you want to add instant (and easy) INI-based role
57
based access control (RBAC) to your application.
68

79
## Basic Features
@@ -18,41 +20,23 @@ frontend yourself)
1820

1921
## Enabling
2022

21-
Assuming you already have authentication set up correctly you can enable
22-
authorization in your controller's `beforeFilter()` method like this example:
23+
**IMPORTANT:** You must first install and configure the official Authorization plugin. See [AuthorizationPlugin.md](AuthorizationPlugin.md) for complete setup instructions.
2324

24-
**DEPRECATED** Use middleware approach and `TinyAuth.Authorization` instead. Rest of the page is accurate.
25+
Load the Authorization component in your controller:
2526

2627
```php
2728
// src/Controller/AppController
2829

2930
public function initialize() {
3031
parent::initialize();
3132

32-
$this->loadComponent('TinyAuth.Auth', [
33-
'authorize' => [
34-
'TinyAuth.Tiny' => [
35-
...
36-
],
37-
...
38-
]
33+
$this->loadComponent('TinyAuth.Authorization', [
34+
...
3935
]);
4036
}
4137
```
42-
TinyAuth Authorize can be used in combination with any [CakePHP Authentication Type](http://book.cakephp.org/3.0/en/controllers/components/authentication.html#choosing-an-authentication-type), as well.
4338

44-
45-
Please note that `TinyAuth.Auth` replaces the default CakePHP `Auth` component. Do not try to load both at once.
46-
You can also use the default one, if you only want to use ACL (authorization):
47-
```php
48-
$this->loadComponent('Auth', [
49-
'authorize' => [
50-
'TinyAuth.Tiny' => [
51-
...
52-
]
53-
]
54-
]);
55-
```
39+
The TinyAuth.Authorization component extends the official `cakephp/authorization` plugin and adds INI-based access control on top of it.
5640

5741

5842
## Roles
@@ -279,38 +263,38 @@ By default it will not use caching in debug mode, though.
279263

280264
To modify the caching behavior set the ``autoClearCache`` configuration option:
281265
```php
282-
'TinyAuth.Tiny' => [
283-
'autoClearCache' => true|false
284-
]
266+
$this->loadComponent('TinyAuth.Authorization', [
267+
'autoClearCache' => true|false,
268+
]);
285269
```
286270

287271
## Configuration
288272

289273
TinyAuthorize adapter supports the following configuration options.
290274

291-
Option | Type | Description
292-
:----- | :--- | :----------
293-
roleColumn|string|Name of column in user table holding role id (used for foreign key in users table in a single role per user setup, or in the pivot table on multi-roles setup)
294-
userColumn|string|Name of column in pivot table holding role id (only used in pivot table on multi-roles setup)
295-
aliasColumn|string|Name of the column for the alias in the role table
296-
idColumn|string|Name of the ID Column in users table
297-
rolesTable|string|Name of Configure key holding all available roles OR class name of roles database table
298-
usersTable|string|Class name of the users table.
299-
pivotTable|string|Name of the pivot table, for a multi-group setup.
300-
rolesTablePlugin|string|Name of the plugin for the roles table, if any.
301-
pivotTablePlugin|string|Name of the plugin for the pivot table, if any.
302-
multiRole|bool|True will enable multi-role/HABTM authorization (requires a valid join table).
303-
superAdminRole|int|Id of the super admin role. Users with this role will have access to ALL resources.
304-
superAdmin|int or string|Id/name of the super admin. Users with this id/name will have access to ALL resources. null/0/'0' disable it.
305-
superAdminColumn|string|Column of super admin in user table. Default is idColumn option.
306-
authorizeByPrefix|bool/array|If prefixed routes should be auto-handled by their matching role name or a prefix=>role map.
307-
allowLoggedIn|bool|True will give authenticated users access to all resources except those using the `protectedPrefix`.
308-
protectedPrefix|string/array|Name of the prefix(es) used for admin pages. Defaults to `Admin`.
309-
autoClearCache|bool|True will generate a new ACL cache file every time.
310-
aclFilePath|string|Full path to the auth_acl.ini. Can also be an array of multiple paths. Defaults to `ROOT . DS . 'config' . DS`.
311-
aclFile|string|Name of the INI file. Defaults to `auth_acl.ini`.
312-
aclAdapter|string|Class name, defaults to `IniAclAdapter::class`.
313-
includeAuthentication|bool|Set to true to include public auth access into hasAccess() checks. Note, that this requires Configure configuration.
275+
Option | Type | Description
276+
:----------------------|:--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------
277+
roleColumn | string | Name of column in user table holding role id (used for foreign key in users table in a single role per user setup, or in the pivot table on multi-roles setup)
278+
userColumn | string | Name of column in pivot table holding role id (only used in pivot table on multi-roles setup)
279+
aliasColumn | string | Name of the column for the alias in the role table
280+
idColumn | string | Name of the ID Column in users table
281+
rolesTable | string | Name of Configure key holding all available roles OR class name of roles database table
282+
usersTable | string | Class name of the users table.
283+
pivotTable | string | Name of the pivot table, for a multi-group setup.
284+
rolesTablePlugin | string | Name of the plugin for the roles table, if any.
285+
pivotTablePlugin | string | Name of the plugin for the pivot table, if any.
286+
multiRole | bool | True will enable multi-role/HABTM authorization (requires a valid join table).
287+
superAdminRole | int | Id of the super admin role. Users with this role will have access to ALL resources.
288+
superAdmin | int or string | Id/name of the super admin. Users with this id/name will have access to ALL resources. null/0/'0' disable it.
289+
superAdminColumn | string | Column of super admin in user table. Default is idColumn option.
290+
authorizeByPrefix | bool/array | If prefixed routes should be auto-handled by their matching role name or a prefix=>role map.
291+
allowLoggedIn | bool | True will give authenticated users access to all resources except those using the `protectedPrefix`.
292+
protectedPrefix | string/array | Name of the prefix(es) used for admin pages. Defaults to `Admin`.
293+
autoClearCache | bool | True will generate a new ACL cache file every time.
294+
aclFilePath | string | Full path to the auth_acl.ini. Can also be an array of multiple paths. Defaults to `ROOT . DS . 'config' . DS`.
295+
aclFile | string | Name of the INI file. Defaults to `auth_acl.ini`.
296+
aclAdapter | string | Class name, defaults to `IniAclAdapter::class`.
297+
includeAuthentication | bool | Set to true to include public auth access into hasAccess() checks. Note, that this requires Configure configuration.
314298

315299
## AuthUser Component
316300
Add the AuthUserComponent and you can easily check permissions inside your controller scope:

‎docs/AuthorizationPlugin.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,18 @@
22

33
Support for [Authorization plugin](https://github.com/cakephp/authorization) usage.
44

5+
## Installation
6+
7+
First, you need to install the official CakePHP Authorization plugin:
8+
9+
```bash
10+
composer require cakephp/authorization
11+
```
12+
13+
See the [official Authorization plugin documentation](https://book.cakephp.org/authorization/2/en/index.html) for more details.
14+
15+
## Setup
16+
517
Instead of the core Auth component you load the Authorization component:
618

719
```php

‎docs/Multi-role.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
## Configuration Multi-role
22

3+
**IMPORTANT:** First install the official plugins as described in [docs/README.md](README.md#required-dependencies)
4+
35
```php
46
// in your app.php
57
'TinyAuth' => [
@@ -9,13 +11,18 @@
911

1012
```php
1113
// in your AppController.php
12-
$this->loadComponent('TinyAuth.Auth', [
13-
'autoClearCache' => true,
14-
'authorize' => ['TinyAuth.Tiny'],
15-
...
16-
]);
14+
public function initialize() {
15+
parent::initialize();
16+
17+
$this->loadComponent('TinyAuth.Authentication');
18+
$this->loadComponent('TinyAuth.Authorization', [
19+
'autoClearCache' => true,
20+
]);
21+
}
1722
```
1823

24+
See [AuthenticationPlugin.md](AuthenticationPlugin.md) and [AuthorizationPlugin.md](AuthorizationPlugin.md) for complete middleware setup instructions.
25+
1926
### auth_allow.ini
2027
```ini
2128
// in config folder

0 commit comments

Comments
 (0)