From e977f0e4567877e6e69326fc48964c9e18ee439a Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 06:42:46 +0900 Subject: [PATCH 01/45] docs: extract "Controller Filters" --- docs/authenticators_and_filters.md | 101 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 102 insertions(+) create mode 100644 docs/authenticators_and_filters.md diff --git a/docs/authenticators_and_filters.md b/docs/authenticators_and_filters.md new file mode 100644 index 000000000..8c029f350 --- /dev/null +++ b/docs/authenticators_and_filters.md @@ -0,0 +1,101 @@ +# Authenticators and Controller Filters + +## Authenticators + +## Controller Filters + +The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes the shield provides are: + +```php +public $aliases = [ + // ... + 'session' => \CodeIgniter\Shield\Filters\SessionAuth::class, + 'tokens' => \CodeIgniter\Shield\Filters\TokenAuth::class, + 'chain' => \CodeIgniter\Shield\Filters\ChainAuth::class, + 'auth-rates' => \CodeIgniter\Shield\Filters\AuthRates::class, + 'group' => \CodeIgniter\Shield\Filters\GroupFilter::class, + 'permission' => \CodeIgniter\Shield\Filters\PermissionFilter::class, + 'force-reset' => \CodeIgniter\Shield\Filters\ForcePasswordResetFilter::class, + 'jwt' => \CodeIgniter\Shield\Filters\JWTAuth::class, +]; +``` + +Filters | Description +--- | --- +session and tokens | The `Session` and `AccessTokens` authenticators, respectively. +chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. +jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). +auth-rates | Provides a good basis for rate limiting of auth-related routes. +group | Checks if the user is in one of the groups passed in. +permission | Checks if the user has the passed permissions. +force-reset | Checks if the user requires a password reset. + +These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). + +> **Note** These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. + +### Protect All Pages + +If you want to limit all routes (e.g. `localhost:8080/admin`, `localhost:8080/panel` and ...), you need to add the following code in the **app/Config/Filters.php** file. + +```php +public $globals = [ + 'before' => [ + // ... + 'session' => ['except' => ['login*', 'register', 'auth/a/*']], + ], + // ... +]; +``` + +### Rate Limiting + +To help protect your authentication forms from being spammed by bots, it is recommended that you use +the `auth-rates` filter on all of your authentication routes. This can be done with the following +filter setup: + +```php +public $filters = [ + 'auth-rates' => [ + 'before' => [ + 'login*', 'register', 'auth/*' + ] + ] +]; +``` + +### Forcing Password Reset + +If your application requires a force password reset functionality, ensure that you exclude the auth pages and the actual password reset page from the `before` global. This will ensure that your users do not run into a *too many redirects* error. See: + +```php +public $globals = [ + 'before' => [ + //... + //... + 'force-reset' => ['except' => ['login*', 'register', 'auth/a/*', 'change-password', 'logout']] + ] +]; +``` +In the example above, it is assumed that the page you have created for users to change their password after successful login is **change-password**. + +> **Note** If you have grouped or changed the default format of the routes, ensure that your code matches the new format(s) in the **app/Config/Filter.php** file. + +For example, if you configured your routes like so: + +```php +$routes->group('accounts', static function($routes) { + service('auth')->routes($routes); +}); +``` +Then the global `before` filter for `session` should look like so: + +```php +public $globals = [ + 'before' => [ + // ... + 'session' => ['except' => ['accounts/login*', 'accounts/register', 'accounts/auth/a/*']] + ] +] +``` +The same should apply for the Rate Limiting and Forcing Password Reset. diff --git a/mkdocs.yml b/mkdocs.yml index f18ca9d7c..2d1bb83e9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,6 +41,7 @@ nav: - Getting Started: - Concepts: concepts.md - Installation: install.md + - Authenticators and Filters: authenticators_and_filters.md - Quick Start Guide: - quick_start_guide/authentication_flow.md - quick_start_guide/authorization_flow.md From 159295b8904195fbdc5cf6d851cedc6462333581 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 06:45:20 +0900 Subject: [PATCH 02/45] docs: remove "the" --- docs/authenticators_and_filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authenticators_and_filters.md b/docs/authenticators_and_filters.md index 8c029f350..53a640643 100644 --- a/docs/authenticators_and_filters.md +++ b/docs/authenticators_and_filters.md @@ -4,7 +4,7 @@ ## Controller Filters -The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes the shield provides are: +The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes Shield provides are: ```php public $aliases = [ From b42159ca694a0f8a8ea8caae6d476a0433d1d6b5 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 06:51:48 +0900 Subject: [PATCH 03/45] docs: add list of Authenticators --- docs/authenticators_and_filters.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/authenticators_and_filters.md b/docs/authenticators_and_filters.md index 53a640643..d1839bc7b 100644 --- a/docs/authenticators_and_filters.md +++ b/docs/authenticators_and_filters.md @@ -2,6 +2,13 @@ ## Authenticators +Shield provides the following Authenticators: + +- **Session** authenticator provides traditional Email/Password authentication. +- **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. +- **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, + you need additional setup. See [JWT Authentication](./addons/jwt.md). + ## Controller Filters The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes Shield provides are: From a937a807833593e65814a95e0d57a896d0a4a7aa Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 06:58:56 +0900 Subject: [PATCH 04/45] docs: add section title --- docs/authenticators_and_filters.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/authenticators_and_filters.md b/docs/authenticators_and_filters.md index d1839bc7b..340b7fcc3 100644 --- a/docs/authenticators_and_filters.md +++ b/docs/authenticators_and_filters.md @@ -41,6 +41,8 @@ These can be used in any of the [normal filter config settings](https://codeigni > **Note** These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. +## Configure Controller Filters + ### Protect All Pages If you want to limit all routes (e.g. `localhost:8080/admin`, `localhost:8080/panel` and ...), you need to add the following code in the **app/Config/Filters.php** file. From 5c636e58809c45d98bbed6b60d46518ebcb3d505 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 07:05:21 +0900 Subject: [PATCH 05/45] docs: change first letters of keywords to capital letters --- docs/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 81a746ebc..615a5ed1c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,13 +16,13 @@ The primary goals for Shield are: ### Important Features -* Session-based authentication (traditional email/password with remember me) +* Session-based authentication (traditional Email/Password with Remember me) * Stateless authentication using Personal Access Tokens * Optional Email verification on account registration * Optional Email-based Two-Factor Authentication after login * Magic Login Links when a user forgets their password -* Flexible groups-based access control (think roles, but more flexible) -* Users can be granted additional permissions +* Flexible Groups-based access control (think Roles, but more flexible) +* Users can be granted additional Permissions ### License From 91e094d12ad6a36300f0419cc402727bd7123a7b Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 08:52:56 +0900 Subject: [PATCH 06/45] docs: change page titles and move a section. --- ...orization_flow.md => using_access_tokens_auth.md} | 12 ++++++++++-- ...{authentication_flow.md => using_session_auth.md} | 12 ++---------- mkdocs.yml | 4 ++-- 3 files changed, 14 insertions(+), 14 deletions(-) rename docs/quick_start_guide/{authorization_flow.md => using_access_tokens_auth.md} (93%) rename docs/quick_start_guide/{authentication_flow.md => using_session_auth.md} (94%) diff --git a/docs/quick_start_guide/authorization_flow.md b/docs/quick_start_guide/using_access_tokens_auth.md similarity index 93% rename from docs/quick_start_guide/authorization_flow.md rename to docs/quick_start_guide/using_access_tokens_auth.md index 568ca5094..d493e6df2 100644 --- a/docs/quick_start_guide/authorization_flow.md +++ b/docs/quick_start_guide/using_access_tokens_auth.md @@ -1,6 +1,14 @@ -# Authorization Flow +# Using AccessTokens Authenticator -## Configure Config\AuthGroups +## Configure + +### Change Access Token Lifetime + +By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the the **app/Config/Auth.php** config file. + +```php +public int $unusedTokenLifetime = YEAR; +``` ### Change Available Groups diff --git a/docs/quick_start_guide/authentication_flow.md b/docs/quick_start_guide/using_session_auth.md similarity index 94% rename from docs/quick_start_guide/authentication_flow.md rename to docs/quick_start_guide/using_session_auth.md index d22383f38..cd42a36f8 100644 --- a/docs/quick_start_guide/authentication_flow.md +++ b/docs/quick_start_guide/using_session_auth.md @@ -1,11 +1,11 @@ -# Authentication Flow +# Using Session Authenticator Learning any new authentication system can be difficult, especially as they get more flexible and sophisticated. This guide is intended to provide short examples for common actions you'll take when working with Shield. It is not intended to be the exhaustive documentation for each section. That's better handled through the area-specific doc files. > **Note** > The examples assume that you have run the setup script and that you have copies of the `Auth` and `AuthGroups` config files in your application's **app/Config** folder. -## Configure Config\Auth +## Configure ### Configure Redirect URLs @@ -38,14 +38,6 @@ public array $sessionConfig = [ ]; ``` -### Change Access Token Lifetime - -By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the `Auth` config file. - -```php -public int $unusedTokenLifetime = YEAR; -``` - ### Enable Account Activation via Email > **Note** diff --git a/mkdocs.yml b/mkdocs.yml index 2d1bb83e9..b4b1fefd9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,8 +43,8 @@ nav: - Installation: install.md - Authenticators and Filters: authenticators_and_filters.md - Quick Start Guide: - - quick_start_guide/authentication_flow.md - - quick_start_guide/authorization_flow.md + - quick_start_guide/using_session_auth.md + - quick_start_guide/using_access_tokens_auth.md - quick_start_guide/managing_users.md - References: - Authentication: authentication.md From a3d84c8fb2fb9d79bdc1954506979bb7ef0ec907 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 09:24:52 +0900 Subject: [PATCH 07/45] docs: add "Using Authorization" and move the existing contents. --- .../using_access_tokens_auth.md | 124 ----------------- docs/quick_start_guide/using_authorization.md | 127 ++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 128 insertions(+), 124 deletions(-) create mode 100644 docs/quick_start_guide/using_authorization.md diff --git a/docs/quick_start_guide/using_access_tokens_auth.md b/docs/quick_start_guide/using_access_tokens_auth.md index d493e6df2..9938680d1 100644 --- a/docs/quick_start_guide/using_access_tokens_auth.md +++ b/docs/quick_start_guide/using_access_tokens_auth.md @@ -9,127 +9,3 @@ By default, Access Tokens can be used for 1 year since the last use. This can be ```php public int $unusedTokenLifetime = YEAR; ``` - -### Change Available Groups - -The available groups are defined in the **app/Config/AuthGroups.php** config file, under the `$groups` property. Add new entries to the array, or remove existing ones to make them available throughout your application. - -```php -public array $groups = [ - 'superadmin' => [ - 'title' => 'Super Admin', - 'description' => 'Complete control of the site.', - ], - // -]; -``` - -### Set the Default Group - -When a user registers on your site, they are assigned the group specified at `Config\AuthGroups::$defaultGroup`. Change this to one of the keys in the `$groups` array to update this. - -### Change Available Permissions - -The permissions on the site are stored in the `AuthGroups` config file also. Each one is defined by a string that represents a context and a permission, joined with a decimal point. - -```php -public array $permissions = [ - 'admin.access' => 'Can access the sites admin area', - 'admin.settings' => 'Can access the main site settings', - 'users.manage-admins' => 'Can manage other admins', - 'users.create' => 'Can create new non-admin users', - 'users.edit' => 'Can edit existing non-admin users', - 'users.delete' => 'Can delete existing non-admin users', - 'beta.access' => 'Can access beta-level features', -]; -``` - -### Assign Permissions to a Group - -Each group can have its own specific set of permissions. These are defined in `Config\AuthGroups::$matrix`. You can specify each permission by it's full name, or using the context and an asterisk (*) to specify all permissions within that context. - -```php -public array $matrix = [ - 'superadmin' => [ - 'admin.*', - 'users.*', - 'beta.access', - ], - // -]; -``` - -## Assign Permissions to a User - -Permissions can also be assigned directly to a user, regardless of what groups they belong to. This is done programatically on the `User` Entity. - -```php -$user = auth()->user(); - -$user->addPermission('users.create', 'beta.access'); -``` - -This will add all new permissions. You can also sync permissions so that the user ONLY has the given permissions directly assigned to them. Any not in the provided list are removed from the user. - -```php -$user = auth()->user(); - -$user->syncPermissions('users.create', 'beta.access'); -``` - -## Check If a User Has Permission - -When you need to check if a user has a specific permission use the `can()` method on the `User` entity. This method checks permissions within the groups they belong to and permissions directly assigned to the user. - -```php -if (! auth()->user()->can('users.create')) { - return redirect()->back()->with('error', 'You do not have permissions to access that page.'); -} -``` - -> **Note** The example above can also be done through a [controller filter](https://codeigniter.com/user_guide/incoming/filters.html) if you want to apply it to multiple pages of your site. - -## Adding a Group To a User - -Groups are assigned to a user via the `addGroup()` method. You can pass multiple groups in and they will all be assigned to the user. - -```php -$user = auth()->user(); -$user->addGroup('admin', 'beta'); -``` - -This will add all new groups. You can also sync groups so that the user ONLY belongs to the groups directly assigned to them. Any not in the provided list are removed from the user. - -```php -$user = auth()->user(); -$user->syncGroups('admin', 'beta'); -``` - -## Removing a Group From a User - -Groups are removed from a user via the `removeGroup()` method. Multiple groups may be removed at once by passing all of their names into the method. - -```php -$user = auth()->user(); -$user->removeGroup('admin', 'beta'); -``` - -## Checking If User Belongs To a Group - -You can check if a user belongs to a group with the `inGroup()` method. - -```php -$user = auth()->user(); -if ($user->inGroup('admin')) { - // do something -} -``` - -You can pass more than one group to the method and it will return `true` if the user belongs to any of the specified groups. - -```php -$user = auth()->user(); -if ($user->inGroup('admin', 'beta')) { - // do something -} -``` diff --git a/docs/quick_start_guide/using_authorization.md b/docs/quick_start_guide/using_authorization.md new file mode 100644 index 000000000..ba2a99d3b --- /dev/null +++ b/docs/quick_start_guide/using_authorization.md @@ -0,0 +1,127 @@ +# Using Authorization + +## Configure + +### Change Available Groups + +The available groups are defined in the **app/Config/AuthGroups.php** config file, under the `$groups` property. Add new entries to the array, or remove existing ones to make them available throughout your application. + +```php +public array $groups = [ + 'superadmin' => [ + 'title' => 'Super Admin', + 'description' => 'Complete control of the site.', + ], + // +]; +``` + +### Set the Default Group + +When a user registers on your site, they are assigned the group specified at `Config\AuthGroups::$defaultGroup`. Change this to one of the keys in the `$groups` array to update this. + +### Change Available Permissions + +The permissions on the site are stored in the `AuthGroups` config file also. Each one is defined by a string that represents a context and a permission, joined with a decimal point. + +```php +public array $permissions = [ + 'admin.access' => 'Can access the sites admin area', + 'admin.settings' => 'Can access the main site settings', + 'users.manage-admins' => 'Can manage other admins', + 'users.create' => 'Can create new non-admin users', + 'users.edit' => 'Can edit existing non-admin users', + 'users.delete' => 'Can delete existing non-admin users', + 'beta.access' => 'Can access beta-level features', +]; +``` + +### Assign Permissions to a Group + +Each group can have its own specific set of permissions. These are defined in `Config\AuthGroups::$matrix`. You can specify each permission by it's full name, or using the context and an asterisk (*) to specify all permissions within that context. + +```php +public array $matrix = [ + 'superadmin' => [ + 'admin.*', + 'users.*', + 'beta.access', + ], + // +]; +``` + +## Assign Permissions to a User + +Permissions can also be assigned directly to a user, regardless of what groups they belong to. This is done programatically on the `User` Entity. + +```php +$user = auth()->user(); + +$user->addPermission('users.create', 'beta.access'); +``` + +This will add all new permissions. You can also sync permissions so that the user ONLY has the given permissions directly assigned to them. Any not in the provided list are removed from the user. + +```php +$user = auth()->user(); + +$user->syncPermissions('users.create', 'beta.access'); +``` + +## Check If a User Has Permission + +When you need to check if a user has a specific permission use the `can()` method on the `User` entity. This method checks permissions within the groups they belong to and permissions directly assigned to the user. + +```php +if (! auth()->user()->can('users.create')) { + return redirect()->back()->with('error', 'You do not have permissions to access that page.'); +} +``` + +> **Note** The example above can also be done through a [controller filter](https://codeigniter.com/user_guide/incoming/filters.html) if you want to apply it to multiple pages of your site. + +## Adding a Group To a User + +Groups are assigned to a user via the `addGroup()` method. You can pass multiple groups in and they will all be assigned to the user. + +```php +$user = auth()->user(); +$user->addGroup('admin', 'beta'); +``` + +This will add all new groups. You can also sync groups so that the user ONLY belongs to the groups directly assigned to them. Any not in the provided list are removed from the user. + +```php +$user = auth()->user(); +$user->syncGroups('admin', 'beta'); +``` + +## Removing a Group From a User + +Groups are removed from a user via the `removeGroup()` method. Multiple groups may be removed at once by passing all of their names into the method. + +```php +$user = auth()->user(); +$user->removeGroup('admin', 'beta'); +``` + +## Checking If User Belongs To a Group + +You can check if a user belongs to a group with the `inGroup()` method. + +```php +$user = auth()->user(); +if ($user->inGroup('admin')) { + // do something +} +``` + +You can pass more than one group to the method and it will return `true` if the user belongs to any of the specified groups. + +```php +$user = auth()->user(); +if ($user->inGroup('admin', 'beta')) { + // do something +} +``` diff --git a/mkdocs.yml b/mkdocs.yml index b4b1fefd9..bafd6e637 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,6 +44,7 @@ nav: - Authenticators and Filters: authenticators_and_filters.md - Quick Start Guide: - quick_start_guide/using_session_auth.md + - quick_start_guide/using_authorization.md - quick_start_guide/using_access_tokens_auth.md - quick_start_guide/managing_users.md - References: From 2952e1fcd80f92d384412b66f5c61e9d48fba42b Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 09:09:45 +0900 Subject: [PATCH 08/45] docs: replace "Magic Login Links" with "Magic Link Login" For consistency. --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 615a5ed1c..0fcb10842 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,7 @@ The primary goals for Shield are: * Stateless authentication using Personal Access Tokens * Optional Email verification on account registration * Optional Email-based Two-Factor Authentication after login -* Magic Login Links when a user forgets their password +* Magic Link Login when a user forgets their password * Flexible Groups-based access control (think Roles, but more flexible) * Users can be granted additional Permissions From 0d3c652fd9f598ef0b3bff00da9f3736536163cf Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 09:14:09 +0900 Subject: [PATCH 09/45] docs: add page for Magic Link Login and move the existing content. --- docs/magic_link_login.md | 34 ++++++++++++++++++++ docs/quick_start_guide/using_session_auth.md | 33 ------------------- mkdocs.yml | 3 +- 3 files changed, 36 insertions(+), 34 deletions(-) create mode 100644 docs/magic_link_login.md diff --git a/docs/magic_link_login.md b/docs/magic_link_login.md new file mode 100644 index 000000000..700654cfd --- /dev/null +++ b/docs/magic_link_login.md @@ -0,0 +1,34 @@ +# Magic Link Login + +## Responding to Magic Link Logins + +> **Note** +> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../install.md#initial-setup). + +Magic Link logins allow a user that has forgotten their password to have an email sent with a unique, one-time login link. Once they've logged in you can decide how to respond. In some cases, you might want to redirect them to a special page where they must choose a new password. In other cases, you might simply want to display a one-time message prompting them to go to their account page and choose a new password. + +### Session Notification + +You can detect if a user has finished the magic link login by checking for a session value, `magicLogin`. If they have recently completed the flow, it will exist and have a value of `true`. + +```php +if (session('magicLogin')) { + return redirect()->route('set_password'); +} +``` + +This value sticks around in the session for 5 minutes. Once you no longer need to take any actions, you might want to delete the value from the session. + +```php +session()->removeTempdata('magicLogin'); +``` + +### Event + +At the same time the above session variable is set, a `magicLogin` [event](https://codeigniter.com/user_guide/extending/events.html) is fired off that you may subscribe to. Note that no data is passed to the event as you can easily grab the current user from the `user()` helper or the `auth()->user()` method. + +```php +Events::on('magicLogin', static function () { + // ... +}); +``` diff --git a/docs/quick_start_guide/using_session_auth.md b/docs/quick_start_guide/using_session_auth.md index cd42a36f8..134f7640b 100644 --- a/docs/quick_start_guide/using_session_auth.md +++ b/docs/quick_start_guide/using_session_auth.md @@ -65,36 +65,3 @@ public array $actions = [ 'login' => \CodeIgniter\Shield\Authentication\Actions\Email2FA::class, ]; ``` - -## Responding to Magic Link Logins - -> **Note** -> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../install.md#initial-setup). - -Magic Link logins allow a user that has forgotten their password to have an email sent with a unique, one-time login link. Once they've logged in you can decide how to respond. In some cases, you might want to redirect them to a special page where they must choose a new password. In other cases, you might simply want to display a one-time message prompting them to go to their account page and choose a new password. - -### Session Notification - -You can detect if a user has finished the magic link login by checking for a session value, `magicLogin`. If they have recently completed the flow, it will exist and have a value of `true`. - -```php -if (session('magicLogin')) { - return redirect()->route('set_password'); -} -``` - -This value sticks around in the session for 5 minutes. Once you no longer need to take any actions, you might want to delete the value from the session. - -```php -session()->removeTempdata('magicLogin'); -``` - -### Event - -At the same time the above session variable is set, a `magicLogin` [event](https://codeigniter.com/user_guide/extending/events.html) is fired off that you may subscribe to. Note that no data is passed to the event as you can easily grab the current user from the `user()` helper or the `auth()->user()` method. - -```php -Events::on('magicLogin', static function () { - // ... -}); -``` diff --git a/mkdocs.yml b/mkdocs.yml index bafd6e637..ac2d2dfcd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,8 +49,9 @@ nav: - quick_start_guide/managing_users.md - References: - Authentication: authentication.md + - auth_actions.md + - magic_link_login.md - Authorization: authorization.md - - Auth Actions: auth_actions.md - Events: events.md - Testing: testing.md - session_auth_event_and_logging.md From 0ffd7c6595f6871d0895c084511da6941b617ea1 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 09:32:48 +0900 Subject: [PATCH 10/45] docs: add "Controller Filters" and move the existing contents. --- docs/authenticators_and_filters.md | 100 ----------------------------- docs/controller_filters.md | 99 ++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 100 insertions(+), 100 deletions(-) create mode 100644 docs/controller_filters.md diff --git a/docs/authenticators_and_filters.md b/docs/authenticators_and_filters.md index 340b7fcc3..e628302b8 100644 --- a/docs/authenticators_and_filters.md +++ b/docs/authenticators_and_filters.md @@ -8,103 +8,3 @@ Shield provides the following Authenticators: - **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. - **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, you need additional setup. See [JWT Authentication](./addons/jwt.md). - -## Controller Filters - -The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes Shield provides are: - -```php -public $aliases = [ - // ... - 'session' => \CodeIgniter\Shield\Filters\SessionAuth::class, - 'tokens' => \CodeIgniter\Shield\Filters\TokenAuth::class, - 'chain' => \CodeIgniter\Shield\Filters\ChainAuth::class, - 'auth-rates' => \CodeIgniter\Shield\Filters\AuthRates::class, - 'group' => \CodeIgniter\Shield\Filters\GroupFilter::class, - 'permission' => \CodeIgniter\Shield\Filters\PermissionFilter::class, - 'force-reset' => \CodeIgniter\Shield\Filters\ForcePasswordResetFilter::class, - 'jwt' => \CodeIgniter\Shield\Filters\JWTAuth::class, -]; -``` - -Filters | Description ---- | --- -session and tokens | The `Session` and `AccessTokens` authenticators, respectively. -chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. -jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). -auth-rates | Provides a good basis for rate limiting of auth-related routes. -group | Checks if the user is in one of the groups passed in. -permission | Checks if the user has the passed permissions. -force-reset | Checks if the user requires a password reset. - -These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). - -> **Note** These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. - -## Configure Controller Filters - -### Protect All Pages - -If you want to limit all routes (e.g. `localhost:8080/admin`, `localhost:8080/panel` and ...), you need to add the following code in the **app/Config/Filters.php** file. - -```php -public $globals = [ - 'before' => [ - // ... - 'session' => ['except' => ['login*', 'register', 'auth/a/*']], - ], - // ... -]; -``` - -### Rate Limiting - -To help protect your authentication forms from being spammed by bots, it is recommended that you use -the `auth-rates` filter on all of your authentication routes. This can be done with the following -filter setup: - -```php -public $filters = [ - 'auth-rates' => [ - 'before' => [ - 'login*', 'register', 'auth/*' - ] - ] -]; -``` - -### Forcing Password Reset - -If your application requires a force password reset functionality, ensure that you exclude the auth pages and the actual password reset page from the `before` global. This will ensure that your users do not run into a *too many redirects* error. See: - -```php -public $globals = [ - 'before' => [ - //... - //... - 'force-reset' => ['except' => ['login*', 'register', 'auth/a/*', 'change-password', 'logout']] - ] -]; -``` -In the example above, it is assumed that the page you have created for users to change their password after successful login is **change-password**. - -> **Note** If you have grouped or changed the default format of the routes, ensure that your code matches the new format(s) in the **app/Config/Filter.php** file. - -For example, if you configured your routes like so: - -```php -$routes->group('accounts', static function($routes) { - service('auth')->routes($routes); -}); -``` -Then the global `before` filter for `session` should look like so: - -```php -public $globals = [ - 'before' => [ - // ... - 'session' => ['except' => ['accounts/login*', 'accounts/register', 'accounts/auth/a/*']] - ] -] -``` -The same should apply for the Rate Limiting and Forcing Password Reset. diff --git a/docs/controller_filters.md b/docs/controller_filters.md new file mode 100644 index 000000000..210d9239c --- /dev/null +++ b/docs/controller_filters.md @@ -0,0 +1,99 @@ +# Controller Filters + +The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes Shield provides are: + +```php +public $aliases = [ + // ... + 'session' => \CodeIgniter\Shield\Filters\SessionAuth::class, + 'tokens' => \CodeIgniter\Shield\Filters\TokenAuth::class, + 'chain' => \CodeIgniter\Shield\Filters\ChainAuth::class, + 'auth-rates' => \CodeIgniter\Shield\Filters\AuthRates::class, + 'group' => \CodeIgniter\Shield\Filters\GroupFilter::class, + 'permission' => \CodeIgniter\Shield\Filters\PermissionFilter::class, + 'force-reset' => \CodeIgniter\Shield\Filters\ForcePasswordResetFilter::class, + 'jwt' => \CodeIgniter\Shield\Filters\JWTAuth::class, +]; +``` + +Filters | Description +--- | --- +session and tokens | The `Session` and `AccessTokens` authenticators, respectively. +chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. +jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). +auth-rates | Provides a good basis for rate limiting of auth-related routes. +group | Checks if the user is in one of the groups passed in. +permission | Checks if the user has the passed permissions. +force-reset | Checks if the user requires a password reset. + +These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). + +> **Note** These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. + +## Configure Controller Filters + +### Protect All Pages + +If you want to limit all routes (e.g. `localhost:8080/admin`, `localhost:8080/panel` and ...), you need to add the following code in the **app/Config/Filters.php** file. + +```php +public $globals = [ + 'before' => [ + // ... + 'session' => ['except' => ['login*', 'register', 'auth/a/*']], + ], + // ... +]; +``` + +### Rate Limiting + +To help protect your authentication forms from being spammed by bots, it is recommended that you use +the `auth-rates` filter on all of your authentication routes. This can be done with the following +filter setup: + +```php +public $filters = [ + 'auth-rates' => [ + 'before' => [ + 'login*', 'register', 'auth/*' + ] + ] +]; +``` + +### Forcing Password Reset + +If your application requires a force password reset functionality, ensure that you exclude the auth pages and the actual password reset page from the `before` global. This will ensure that your users do not run into a *too many redirects* error. See: + +```php +public $globals = [ + 'before' => [ + //... + //... + 'force-reset' => ['except' => ['login*', 'register', 'auth/a/*', 'change-password', 'logout']] + ] +]; +``` +In the example above, it is assumed that the page you have created for users to change their password after successful login is **change-password**. + +> **Note** If you have grouped or changed the default format of the routes, ensure that your code matches the new format(s) in the **app/Config/Filter.php** file. + +For example, if you configured your routes like so: + +```php +$routes->group('accounts', static function($routes) { + service('auth')->routes($routes); +}); +``` +Then the global `before` filter for `session` should look like so: + +```php +public $globals = [ + 'before' => [ + // ... + 'session' => ['except' => ['accounts/login*', 'accounts/register', 'accounts/auth/a/*']] + ] +] +``` +The same should apply for the Rate Limiting and Forcing Password Reset. diff --git a/mkdocs.yml b/mkdocs.yml index ac2d2dfcd..b2762899a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,7 @@ nav: - quick_start_guide/using_access_tokens_auth.md - quick_start_guide/managing_users.md - References: + - controller_filters.md - Authentication: authentication.md - auth_actions.md - magic_link_login.md From 228ad4874ce7bdc0a16c5b15fa927c6b97883245 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 09:35:02 +0900 Subject: [PATCH 11/45] docs: change filename --- docs/{authenticators_and_filters.md => authenticators.md} | 4 +--- mkdocs.yml | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) rename docs/{authenticators_and_filters.md => authenticators.md} (86%) diff --git a/docs/authenticators_and_filters.md b/docs/authenticators.md similarity index 86% rename from docs/authenticators_and_filters.md rename to docs/authenticators.md index e628302b8..bf2e5e508 100644 --- a/docs/authenticators_and_filters.md +++ b/docs/authenticators.md @@ -1,6 +1,4 @@ -# Authenticators and Controller Filters - -## Authenticators +# Authenticators Shield provides the following Authenticators: diff --git a/mkdocs.yml b/mkdocs.yml index b2762899a..904b99ff1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,7 +41,7 @@ nav: - Getting Started: - Concepts: concepts.md - Installation: install.md - - Authenticators and Filters: authenticators_and_filters.md + - authenticators.md - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md From 6f260fe298215a845a7998177a733d41e58b8e38 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:06:44 +0900 Subject: [PATCH 12/45] docs: add descriptions --- docs/quick_start_guide/using_session_auth.md | 43 +++++++++++++++++++- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/quick_start_guide/using_session_auth.md b/docs/quick_start_guide/using_session_auth.md index 134f7640b..6c7869b62 100644 --- a/docs/quick_start_guide/using_session_auth.md +++ b/docs/quick_start_guide/using_session_auth.md @@ -1,11 +1,13 @@ # Using Session Authenticator +**Session** authenticator provides traditional Email/Password authentication. + Learning any new authentication system can be difficult, especially as they get more flexible and sophisticated. This guide is intended to provide short examples for common actions you'll take when working with Shield. It is not intended to be the exhaustive documentation for each section. That's better handled through the area-specific doc files. > **Note** > The examples assume that you have run the setup script and that you have copies of the `Auth` and `AuthGroups` config files in your application's **app/Config** folder. -## Configure +## Configuration ### Configure Redirect URLs @@ -27,7 +29,7 @@ public array $redirects = [ ### Configure Remember-me Functionality -Remember-me functionality is enabled by default for the `Session` authenticator. While this is handled in a secure manner, some sites may want it disabled. You might also want to change how long it remembers a user and doesn't require additional login. +Remember-me functionality is enabled by default. While this is handled in a secure manner, some sites may want it disabled. You might also want to change how long it remembers a user and doesn't require additional login. ```php public array $sessionConfig = [ @@ -65,3 +67,40 @@ public array $actions = [ 'login' => \CodeIgniter\Shield\Authentication\Actions\Email2FA::class, ]; ``` + +## Customizing Routes + +If you need to customize how any of the auth features are handled, you can still +use the `service('auth')->routes()` helper, but you will need to pass the `except` +option with a list of routes to customize: + +```php +service('auth')->routes($routes, ['except' => ['login', 'register']]); +``` + +Then add the routes to your customized controllers: + +```php +$routes->get('login', '\App\Controllers\Auth\LoginController::loginView'); +$routes->get('register', '\App\Controllers\Auth\RegisterController::registerView'); +``` + +Check your routes with the [spark routes](https://codeigniter.com/user_guide/incoming/routing.html#spark-routes) +command. + +## Protecting Pages + +If you want to limit all routes (e.g. `localhost:8080/admin`, `localhost:8080/panel` and ...), you need to add the following code in the **app/Config/Filters.php** file. + +```php +public $globals = [ + 'before' => [ + // ... + 'session' => ['except' => ['login*', 'register', 'auth/a/*']], + ], + // ... +]; +``` + +Check your filters with the [spark routes](https://codeigniter.com/user_guide/incoming/routing.html#spark-routes) +command. From 7008664cb89bf4f29cc85c98b48816f74f8bfbbe Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:23:26 +0900 Subject: [PATCH 13/45] docs: remove using_access_tokens_auth.md --- docs/authenticators.md | 14 ++++++++++++++ docs/quick_start_guide/using_access_tokens_auth.md | 11 ----------- mkdocs.yml | 1 - 3 files changed, 14 insertions(+), 12 deletions(-) delete mode 100644 docs/quick_start_guide/using_access_tokens_auth.md diff --git a/docs/authenticators.md b/docs/authenticators.md index bf2e5e508..c73f0ffae 100644 --- a/docs/authenticators.md +++ b/docs/authenticators.md @@ -1,8 +1,22 @@ # Authenticators +## Authenticator List + Shield provides the following Authenticators: - **Session** authenticator provides traditional Email/Password authentication. - **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. - **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, you need additional setup. See [JWT Authentication](./addons/jwt.md). + +## Configuration + +### AccessTokens Authenticator + +#### Change Access Token Lifetime + +By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the the **app/Config/Auth.php** config file. + +```php +public int $unusedTokenLifetime = YEAR; +``` diff --git a/docs/quick_start_guide/using_access_tokens_auth.md b/docs/quick_start_guide/using_access_tokens_auth.md deleted file mode 100644 index 9938680d1..000000000 --- a/docs/quick_start_guide/using_access_tokens_auth.md +++ /dev/null @@ -1,11 +0,0 @@ -# Using AccessTokens Authenticator - -## Configure - -### Change Access Token Lifetime - -By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the the **app/Config/Auth.php** config file. - -```php -public int $unusedTokenLifetime = YEAR; -``` diff --git a/mkdocs.yml b/mkdocs.yml index 904b99ff1..e27e0c0c0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,7 +45,6 @@ nav: - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md - - quick_start_guide/using_access_tokens_auth.md - quick_start_guide/managing_users.md - References: - controller_filters.md From 85fd665cb161903a9cc7447578cfee9b02367f6b Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:24:28 +0900 Subject: [PATCH 14/45] docs: change section title --- docs/quick_start_guide/using_authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quick_start_guide/using_authorization.md b/docs/quick_start_guide/using_authorization.md index ba2a99d3b..8d75c9952 100644 --- a/docs/quick_start_guide/using_authorization.md +++ b/docs/quick_start_guide/using_authorization.md @@ -1,6 +1,6 @@ # Using Authorization -## Configure +## Configuration ### Change Available Groups From adf6024b3920ebe2309200e0a19056a95572996c Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:27:47 +0900 Subject: [PATCH 15/45] docs: add links --- docs/authenticators.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/authenticators.md b/docs/authenticators.md index c73f0ffae..f6821148a 100644 --- a/docs/authenticators.md +++ b/docs/authenticators.md @@ -5,7 +5,10 @@ Shield provides the following Authenticators: - **Session** authenticator provides traditional Email/Password authentication. + See [Using Session Authenticator](./quick_start_guide/using_session_auth.md) + for usage. - **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. + See [Protecting an API with Access Tokens](./guides/api_tokens.md) for usage. - **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, you need additional setup. See [JWT Authentication](./addons/jwt.md). From cf1e5f1508c978f668599f07e7554c7d93aa12c5 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:36:14 +0900 Subject: [PATCH 16/45] docs: add "Getting Started > Configuration" --- docs/authenticators.md | 12 ------------ docs/configuration.md | 11 +++++++++++ mkdocs.yml | 1 + 3 files changed, 12 insertions(+), 12 deletions(-) create mode 100644 docs/configuration.md diff --git a/docs/authenticators.md b/docs/authenticators.md index f6821148a..351eace03 100644 --- a/docs/authenticators.md +++ b/docs/authenticators.md @@ -11,15 +11,3 @@ Shield provides the following Authenticators: See [Protecting an API with Access Tokens](./guides/api_tokens.md) for usage. - **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, you need additional setup. See [JWT Authentication](./addons/jwt.md). - -## Configuration - -### AccessTokens Authenticator - -#### Change Access Token Lifetime - -By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the the **app/Config/Auth.php** config file. - -```php -public int $unusedTokenLifetime = YEAR; -``` diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 000000000..65580f668 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,11 @@ +# Configuration + +## AccessTokens Authenticator + +### Change Access Token Lifetime + +By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the the **app/Config/Auth.php** config file. + +```php +public int $unusedTokenLifetime = YEAR; +``` diff --git a/mkdocs.yml b/mkdocs.yml index e27e0c0c0..3cd974a47 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,7 @@ nav: - Concepts: concepts.md - Installation: install.md - authenticators.md + - configuration.md - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md From 80e46ebe4bf6f9b4e1180d48da5c92915e97d6d4 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:37:28 +0900 Subject: [PATCH 17/45] docs: update link --- docs/magic_link_login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/magic_link_login.md b/docs/magic_link_login.md index 700654cfd..26687f975 100644 --- a/docs/magic_link_login.md +++ b/docs/magic_link_login.md @@ -3,7 +3,7 @@ ## Responding to Magic Link Logins > **Note** -> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../install.md#initial-setup). +> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](./install.md#initial-setup). Magic Link logins allow a user that has forgotten their password to have an email sent with a unique, one-time login link. Once they've logged in you can decide how to respond. In some cases, you might want to redirect them to a special page where they must choose a new password. In other cases, you might simply want to display a one-time message prompting them to go to their account page and choose a new password. From 604b3903d14dfedcb3ed5d343a81d8358ed4087f Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:43:58 +0900 Subject: [PATCH 18/45] docs: fix section title --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 65580f668..cd05668c4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,7 +2,7 @@ ## AccessTokens Authenticator -### Change Access Token Lifetime +### Access Token Lifetime By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the the **app/Config/Auth.php** config file. From 32ab5ca711f086a562ce029e1cc006188967c67f Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:44:14 +0900 Subject: [PATCH 19/45] docs: remove duplicated "the" --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index cd05668c4..f31ac38c2 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,7 +4,7 @@ ### Access Token Lifetime -By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the the **app/Config/Auth.php** config file. +By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the **app/Config/Auth.php** config file. ```php public int $unusedTokenLifetime = YEAR; From 38fb0daff21adb389f88429cd5a484dc04697643 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:47:22 +0900 Subject: [PATCH 20/45] docs: move Configuration to References --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 3cd974a47..129f7a6f6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,12 +42,12 @@ nav: - Concepts: concepts.md - Installation: install.md - authenticators.md - - configuration.md - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md - quick_start_guide/managing_users.md - References: + - configuration.md - controller_filters.md - Authentication: authentication.md - auth_actions.md From ae56615408985ff8372ba91c798830196b1ee9be Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 11:53:04 +0900 Subject: [PATCH 21/45] docs: add explanation to configuration.md --- docs/configuration.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index f31ac38c2..df421818d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,5 +1,20 @@ # Configuration +## Config files + +Shield has a lot of Config items. Change the default values as needed. + +If you have completed the setup according to this documentation, you will have +the following configuration files: + +- **app/Config/Auth.php** +- **app/Config/AuthGroups.php** - For Authorization +- **app/Config/AuthJWT.php** - For JWT Authentication + +Note that you do not need to have configuration files for features you do not use. + +This section describes the major Config items that are not described elsewhere. + ## AccessTokens Authenticator ### Access Token Lifetime From 969e47c88c18023cd4e415ce5113d8fcb2e5c97b Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 15:51:47 +0900 Subject: [PATCH 22/45] docs: add empty line --- docs/customization/integrating_custom_view_libs.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/customization/integrating_custom_view_libs.md b/docs/customization/integrating_custom_view_libs.md index fc97891bb..4025de85c 100644 --- a/docs/customization/integrating_custom_view_libs.md +++ b/docs/customization/integrating_custom_view_libs.md @@ -1,6 +1,8 @@ # Integrating Custom View Libraries -If your application uses a different method to convert view files to HTML than CodeIgniter's built-in `view()` helper you can easily integrate your system anywhere that a view is rendered within Shield. All controllers and actions use the `CodeIgniter\Shield\Traits\Viewable` trait which provides a simple `view()` method that takes the same arguments as the `view()` helper. This allows you to extend the Action or Controller and only change the single method of rendering the view, leaving all of the logic untouched so your app will not need to maintain Shield logic when it doesn't need to change it. +If your application uses a different method to convert view files to HTML than CodeIgniter's built-in `view()` helper, you can easily integrate your system anywhere that a view is rendered within Shield. + +All controllers and actions use the `CodeIgniter\Shield\Traits\Viewable` trait which provides a simple `view()` method that takes the same arguments as the `view()` helper. This allows you to extend the Action or Controller and only change the single method of rendering the view, leaving all of the logic untouched so your app will not need to maintain Shield logic when it doesn't need to change it. ```php use Acme\Themes\Traits\Themeable; From d7008e8594ea9da2866c28adaa394f55e12606d2 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 16:13:46 +0900 Subject: [PATCH 23/45] docs: move configuration.md to "Getting Started" --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 129f7a6f6..3cd974a47 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,12 +42,12 @@ nav: - Concepts: concepts.md - Installation: install.md - authenticators.md + - configuration.md - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md - quick_start_guide/managing_users.md - References: - - configuration.md - controller_filters.md - Authentication: authentication.md - auth_actions.md From a6a6d12d3918c7d83fa7a9d29062080f00f61836 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 18 Sep 2023 16:25:09 +0900 Subject: [PATCH 24/45] docs: add Configuration in magic_link_login.md --- docs/magic_link_login.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/magic_link_login.md b/docs/magic_link_login.md index 26687f975..ef4b2f15a 100644 --- a/docs/magic_link_login.md +++ b/docs/magic_link_login.md @@ -1,5 +1,28 @@ # Magic Link Login +Magic Link Login is a feature that allows users to log in if they forget their +password. + +## Configuration + +### Configure Magic Link Login Functionality + +Magic Link Login functionality is enabled by default. +You can change it within the **app/Config/Auth.php** file. + +```php +public bool $allowMagicLinkLogins = true; +``` + +### Magic Link Lifetime + +By default, Magic Link can be used for 1 hour. This can be easily modified +in the **app/Config/Auth.php** file. + +```php +public int $magicLinkLifetime = HOUR; +``` + ## Responding to Magic Link Logins > **Note** From 14a607c1cc1ea62deaf2cd2c6011dacf3fa87f3f Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 09:39:01 +0900 Subject: [PATCH 25/45] docs: fix rebase mistake --- docs/controller_filters.md | 20 ++++---- docs/install.md | 100 ------------------------------------- 2 files changed, 11 insertions(+), 109 deletions(-) diff --git a/docs/controller_filters.md b/docs/controller_filters.md index 210d9239c..b59a0042a 100644 --- a/docs/controller_filters.md +++ b/docs/controller_filters.md @@ -7,6 +7,7 @@ public $aliases = [ // ... 'session' => \CodeIgniter\Shield\Filters\SessionAuth::class, 'tokens' => \CodeIgniter\Shield\Filters\TokenAuth::class, + 'hmac' => \CodeIgniter\Shield\Filters\HmacAuth::class, 'chain' => \CodeIgniter\Shield\Filters\ChainAuth::class, 'auth-rates' => \CodeIgniter\Shield\Filters\AuthRates::class, 'group' => \CodeIgniter\Shield\Filters\GroupFilter::class, @@ -16,15 +17,16 @@ public $aliases = [ ]; ``` -Filters | Description ---- | --- -session and tokens | The `Session` and `AccessTokens` authenticators, respectively. -chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. -jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). -auth-rates | Provides a good basis for rate limiting of auth-related routes. -group | Checks if the user is in one of the groups passed in. -permission | Checks if the user has the passed permissions. -force-reset | Checks if the user requires a password reset. +| Filters | Description | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| session and tokens | The `Session` and `AccessTokens` authenticators, respectively. | +| chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. | +| jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). | +| hmac | The `HMAC` authenticator. See [HMAC Authentication](./guides/api_hmac_keys.md). | +| auth-rates | Provides a good basis for rate limiting of auth-related routes. | +| group | Checks if the user is in one of the groups passed in. | +| permission | Checks if the user has the passed permissions. | +| force-reset | Checks if the user requires a password reset. | These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). diff --git a/docs/install.md b/docs/install.md index 47aad61b0..59f76fd56 100644 --- a/docs/install.md +++ b/docs/install.md @@ -181,103 +181,3 @@ your project. // ... } ``` - -## Controller Filters - -The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes the shield provides are: - -```php -public $aliases = [ - // ... - 'session' => \CodeIgniter\Shield\Filters\SessionAuth::class, - 'tokens' => \CodeIgniter\Shield\Filters\TokenAuth::class, - 'hmac' => \CodeIgniter\Shield\Filters\HmacAuth::class, - 'chain' => \CodeIgniter\Shield\Filters\ChainAuth::class, - 'auth-rates' => \CodeIgniter\Shield\Filters\AuthRates::class, - 'group' => \CodeIgniter\Shield\Filters\GroupFilter::class, - 'permission' => \CodeIgniter\Shield\Filters\PermissionFilter::class, - 'force-reset' => \CodeIgniter\Shield\Filters\ForcePasswordResetFilter::class, - 'jwt' => \CodeIgniter\Shield\Filters\JWTAuth::class, -]; -``` - -| Filters | Description | -|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| session and tokens | The `Session` and `AccessTokens` authenticators, respectively. | -| chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. | -| jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). | -| hmac | The `HMAC` authenticator. See [HMAC Authentication](./guides/api_hmac_keys.md). | -| auth-rates | Provides a good basis for rate limiting of auth-related routes. | -| group | Checks if the user is in one of the groups passed in. | -| permission | Checks if the user has the passed permissions. | -| force-reset | Checks if the user requires a password reset. | - -These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). - -> **Note** These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. - -### Protect All Pages - -If you want to limit all routes (e.g. `localhost:8080/admin`, `localhost:8080/panel` and ...), you need to add the following code in the **app/Config/Filters.php** file. - -```php -public $globals = [ - 'before' => [ - // ... - 'session' => ['except' => ['login*', 'register', 'auth/a/*']], - ], - // ... -]; -``` - -### Rate Limiting - -To help protect your authentication forms from being spammed by bots, it is recommended that you use -the `auth-rates` filter on all of your authentication routes. This can be done with the following -filter setup: - -```php -public $filters = [ - 'auth-rates' => [ - 'before' => [ - 'login*', 'register', 'auth/*' - ] - ] -]; -``` - -### Forcing Password Reset - -If your application requires a force password reset functionality, ensure that you exclude the auth pages and the actual password reset page from the `before` global. This will ensure that your users do not run into a *too many redirects* error. See: - -```php -public $globals = [ - 'before' => [ - //... - //... - 'force-reset' => ['except' => ['login*', 'register', 'auth/a/*', 'change-password', 'logout']] - ] -]; -``` -In the example above, it is assumed that the page you have created for users to change their password after successful login is **change-password**. - -> **Note** If you have grouped or changed the default format of the routes, ensure that your code matches the new format(s) in the **app/Config/Filter.php** file. - -For example, if you configured your routes like so: - -```php -$routes->group('accounts', static function($routes) { - service('auth')->routes($routes); -}); -``` -Then the global `before` filter for `session` should look like so: - -```php -public $globals = [ - 'before' => [ - // ... - 'session' => ['except' => ['accounts/login*', 'accounts/register', 'accounts/auth/a/*']] - ] -] -``` -The same should apply for the Rate Limiting and Forcing Password Reset. From dfe0448cd99758140e0933af2cd271642c689094 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 09:40:45 +0900 Subject: [PATCH 26/45] docs: add empty lines and line breaks --- docs/controller_filters.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/controller_filters.md b/docs/controller_filters.md index b59a0042a..9a8eaf9be 100644 --- a/docs/controller_filters.md +++ b/docs/controller_filters.md @@ -30,7 +30,8 @@ public $aliases = [ These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). -> **Note** These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. +> **Note** +> These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. ## Configure Controller Filters @@ -79,7 +80,8 @@ public $globals = [ ``` In the example above, it is assumed that the page you have created for users to change their password after successful login is **change-password**. -> **Note** If you have grouped or changed the default format of the routes, ensure that your code matches the new format(s) in the **app/Config/Filter.php** file. +> **Note** +> If you have grouped or changed the default format of the routes, ensure that your code matches the new format(s) in the **app/Config/Filter.php** file. For example, if you configured your routes like so: @@ -88,6 +90,7 @@ $routes->group('accounts', static function($routes) { service('auth')->routes($routes); }); ``` + Then the global `before` filter for `session` should look like so: ```php @@ -98,4 +101,5 @@ public $globals = [ ] ] ``` + The same should apply for the Rate Limiting and Forcing Password Reset. From 331a81e618d25329a98f6a6768cd011a85f33e18 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 09:46:12 +0900 Subject: [PATCH 27/45] docs: improve descriptions for Filters --- docs/controller_filters.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/controller_filters.md b/docs/controller_filters.md index 9a8eaf9be..f219200c1 100644 --- a/docs/controller_filters.md +++ b/docs/controller_filters.md @@ -17,16 +17,17 @@ public $aliases = [ ]; ``` -| Filters | Description | -|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| session and tokens | The `Session` and `AccessTokens` authenticators, respectively. | -| chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. | -| jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). | -| hmac | The `HMAC` authenticator. See [HMAC Authentication](./guides/api_hmac_keys.md). | -| auth-rates | Provides a good basis for rate limiting of auth-related routes. | -| group | Checks if the user is in one of the groups passed in. | -| permission | Checks if the user has the passed permissions. | -| force-reset | Checks if the user requires a password reset. | +| Filters | Description | +|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| session | The `Session` authenticator. | +| tokens | The `AccessTokens` authenticator. | +| chained | The filter will check authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. | +| jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). | +| hmac | The `HMAC` authenticator. See [HMAC Authentication](./guides/api_hmac_keys.md). | +| auth-rates | Provides a good basis for rate limiting of auth-related routes. | +| group | Checks if the user is in one of the groups passed in. | +| permission | Checks if the user has the passed permissions. | +| force-reset | Checks if the user requires a password reset. | These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). From ba72bddd4f539e391efe65dd22dd708871087477 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 09:48:20 +0900 Subject: [PATCH 28/45] docs: add line break after **Note** --- docs/authorization.md | 15 ++++++++++----- docs/customization/table_names.md | 3 ++- docs/customization/validation_rules.md | 6 ++++-- docs/guides/api_tokens.md | 3 ++- docs/install.md | 6 ++++-- docs/quick_start_guide/managing_users.md | 3 ++- docs/quick_start_guide/using_authorization.md | 3 ++- 7 files changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/authorization.md b/docs/authorization.md index 571af598d..67d5af0df 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -57,7 +57,8 @@ public array $permissions = [ In order to grant any permissions to a group, they must have the permission assigned to the group, within the `AuthGroups` config file, under the `$matrix` property. -> **Note** This defines **group-level permissons**. +> **Note** +> This defines **group-level permissons**. The matrix is an associative array with the group name as the key, and an array of permissions that should be applied to that group. @@ -121,7 +122,8 @@ if (! $user->hasPermission('users.create')) { } ``` -> **Note** This method checks only **user-level permissions**, and does not check +> **Note** +> This method checks only **user-level permissions**, and does not check > group-level permissions. If you want to check if the user can do something, > use the `$user->can()` method instead. @@ -150,7 +152,8 @@ $routes->group('admin', ['filter' => 'group:admin,superadmin'], static function Note that the options (`filter`) passed to the outer `group()` are not merged with the inner `group()` options. -> **Note** If you set more than one filter to a route, you need to enable +> **Note** +> If you set more than one filter to a route, you need to enable > [Multiple Filters](https://codeigniter.com/user_guide/incoming/routing.html#multiple-filters). ## Managing User Permissions @@ -193,7 +196,8 @@ Returns all **user-level** permissions this user has assigned directly to them. $user->getPermissions(); ``` -> **Note** This method does not return **group-level permissions**. +> **Note** +> This method does not return **group-level permissions**. ## Managing User Groups @@ -246,7 +250,8 @@ if ($user->isActivated()) { } ``` -> **Note** If no activator is specified in the `Auth` config file, `actions['register']` property, then this will always return `true`. +> **Note** +> If no activator is specified in the `Auth` config file, `actions['register']` property, then this will always return `true`. You can check if a user has not been activated yet via the `isNotActivated()` method. diff --git a/docs/customization/table_names.md b/docs/customization/table_names.md index 2fcaad8c7..03eca1c98 100644 --- a/docs/customization/table_names.md +++ b/docs/customization/table_names.md @@ -17,4 +17,5 @@ public array $tables = [ Set the table names that you want in the array values. -> **Note** You must change the table names before running database migrations. +> **Note** +> You must change the table names before running database migrations. diff --git a/docs/customization/validation_rules.md b/docs/customization/validation_rules.md index f0442ff72..f637d4301 100644 --- a/docs/customization/validation_rules.md +++ b/docs/customization/validation_rules.md @@ -36,7 +36,8 @@ Shield has the following rules for registration: ]; ``` -> **Note** If you customize the table names, the table names +> **Note** +> If you customize the table names, the table names > (`users` and `auth_identities`) in the above rules will be automatically > changed. The rules are implemented in > `RegisterController::getValidationRules()`. @@ -78,7 +79,8 @@ If you need a different set of rules for registration, you can specify them in y ]; ``` -> **Note** If you customize the table names, set the correct table names in the +> **Note** +> If you customize the table names, set the correct table names in the > rules. ## Login diff --git a/docs/guides/api_tokens.md b/docs/guides/api_tokens.md index ed9dee901..50824d17a 100644 --- a/docs/guides/api_tokens.md +++ b/docs/guides/api_tokens.md @@ -2,7 +2,8 @@ Access Tokens can be used to authenticate users for your own site, or when allowing third-party developers to access your API. When making requests using access tokens, the token should be included in the `Authorization` header as a `Bearer` token. -> **Note** By default, `$authenticatorHeader['tokens']` is set to `Authorization`. You can change this value by setting the `$authenticatorHeader['tokens']` value in the **app/Config/Auth.php** config file. +> **Note** +> By default, `$authenticatorHeader['tokens']` is set to `Authorization`. You can change this value by setting the `$authenticatorHeader['tokens']` value in the **app/Config/Auth.php** config file. Tokens are issued with the `generateAccessToken()` method on the user. This returns a `CodeIgniter\Shield\Entities\AccessToken` instance. Tokens are hashed using a SHA-256 algorithm before being saved to the database. The access token returned when you generate it will include a `raw_token` field that contains the plain-text, un-hashed, token. You should display this to your user at once so they have a chance to copy it somewhere safe, as this is the only time this will be available. After this request, there is no way to get the raw token. diff --git a/docs/install.md b/docs/install.md index 59f76fd56..26c17c1a1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -61,7 +61,8 @@ Require it with an explicit version constraint allowing its desired stability. php spark shield:setup ``` - > **Note** If you want to customize table names, you must change the table names + > **Note** + > If you want to customize table names, you must change the table names > before running database migrations. > See [Customizing Table Names](./customization/table_names.md). @@ -138,7 +139,8 @@ your project. 5. **Migration** Run the migrations. - > **Note** If you want to customize table names, you must change the table names + > **Note** + > If you want to customize table names, you must change the table names > before running database migrations. > See [Customizing Table Names](./customization/table_names.md). diff --git a/docs/quick_start_guide/managing_users.md b/docs/quick_start_guide/managing_users.md index 84c57815b..3f4a2b3c0 100644 --- a/docs/quick_start_guide/managing_users.md +++ b/docs/quick_start_guide/managing_users.md @@ -37,7 +37,8 @@ $users = auth()->getProvider(); $users->delete($user->id, true); ``` -> **Note** The User rows use [soft deletes](https://codeigniter.com/user_guide/models/model.html#usesoftdeletes) so they are not actually deleted from the database unless the second parameter is `true`, like above. +> **Note** +> The User rows use [soft deletes](https://codeigniter.com/user_guide/models/model.html#usesoftdeletes) so they are not actually deleted from the database unless the second parameter is `true`, like above. ## Editing a User diff --git a/docs/quick_start_guide/using_authorization.md b/docs/quick_start_guide/using_authorization.md index 8d75c9952..c4d6d9f3a 100644 --- a/docs/quick_start_guide/using_authorization.md +++ b/docs/quick_start_guide/using_authorization.md @@ -79,7 +79,8 @@ if (! auth()->user()->can('users.create')) { } ``` -> **Note** The example above can also be done through a [controller filter](https://codeigniter.com/user_guide/incoming/filters.html) if you want to apply it to multiple pages of your site. +> **Note** +> The example above can also be done through a [controller filter](https://codeigniter.com/user_guide/incoming/filters.html) if you want to apply it to multiple pages of your site. ## Adding a Group To a User From a33cf5a2febbd16aa4e1443e9d66c7f6b0ba1475 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 09:51:19 +0900 Subject: [PATCH 29/45] docs: add HmacSha256 authenticator --- docs/authenticators.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/authenticators.md b/docs/authenticators.md index 351eace03..c00a4b6ec 100644 --- a/docs/authenticators.md +++ b/docs/authenticators.md @@ -9,5 +9,7 @@ Shield provides the following Authenticators: for usage. - **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. See [Protecting an API with Access Tokens](./guides/api_tokens.md) for usage. +- **HmacSha256** authenticator provides stateless authentication using HMAC Keys. + See [guides/api_hmac_keys](./guides/api_hmac_keys.md) for usage. - **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, you need additional setup. See [JWT Authentication](./addons/jwt.md). From 6584605b4eba02c57c73036f3f8548763c3f5436 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 09:55:33 +0900 Subject: [PATCH 30/45] docs: move "Managing Users" to "Guides" --- docs/{quick_start_guide => guides}/managing_users.md | 0 mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{quick_start_guide => guides}/managing_users.md (100%) diff --git a/docs/quick_start_guide/managing_users.md b/docs/guides/managing_users.md similarity index 100% rename from docs/quick_start_guide/managing_users.md rename to docs/guides/managing_users.md diff --git a/mkdocs.yml b/mkdocs.yml index 3cd974a47..95020c784 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,7 +46,6 @@ nav: - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md - - quick_start_guide/managing_users.md - References: - controller_filters.md - Authentication: authentication.md @@ -66,6 +65,7 @@ nav: - customization/user_provider.md - customization/login_identifier.md - Guides: + - guides/managing_users.md - guides/forcing_password_reset.md - guides/banning_users.md - guides/api_tokens.md From ae30aac04a71e835343fad829b1dc9c2761a6081 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 10:03:58 +0900 Subject: [PATCH 31/45] docs: add section "User Management" and change section order --- .../banning_users.md | 0 .../forcing_password_reset.md | 0 .../managing_users.md | 0 mkdocs.yml | 25 ++++++++++--------- 4 files changed, 13 insertions(+), 12 deletions(-) rename docs/{guides => user_management}/banning_users.md (100%) rename docs/{guides => user_management}/forcing_password_reset.md (100%) rename docs/{guides => user_management}/managing_users.md (100%) diff --git a/docs/guides/banning_users.md b/docs/user_management/banning_users.md similarity index 100% rename from docs/guides/banning_users.md rename to docs/user_management/banning_users.md diff --git a/docs/guides/forcing_password_reset.md b/docs/user_management/forcing_password_reset.md similarity index 100% rename from docs/guides/forcing_password_reset.md rename to docs/user_management/forcing_password_reset.md diff --git a/docs/guides/managing_users.md b/docs/user_management/managing_users.md similarity index 100% rename from docs/guides/managing_users.md rename to docs/user_management/managing_users.md diff --git a/mkdocs.yml b/mkdocs.yml index 95020c784..61622b499 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,15 +46,6 @@ nav: - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md - - References: - - controller_filters.md - - Authentication: authentication.md - - auth_actions.md - - magic_link_login.md - - Authorization: authorization.md - - Events: events.md - - Testing: testing.md - - session_auth_event_and_logging.md - Customization: - customization/table_names.md - customization/route_config.md @@ -64,13 +55,23 @@ nav: - customization/validation_rules.md - customization/user_provider.md - customization/login_identifier.md + - User Management: + - user_management/managing_users.md + - user_management/forcing_password_reset.md + - user_management/banning_users.md - Guides: - - guides/managing_users.md - - guides/forcing_password_reset.md - - guides/banning_users.md - guides/api_tokens.md - guides/api_hmac_keys.md - guides/mobile_apps.md - guides/strengthen_password.md + - References: + - controller_filters.md + - Authentication: authentication.md + - auth_actions.md + - magic_link_login.md + - Authorization: authorization.md + - Events: events.md + - Testing: testing.md + - session_auth_event_and_logging.md - Addons: - JWT Authentication: addons/jwt.md From 62685e84013c4ebc88ed5859025549c883e67a70 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 10:08:05 +0900 Subject: [PATCH 32/45] docs: change sub section order --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 61622b499..f568a7753 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,10 +50,10 @@ nav: - customization/table_names.md - customization/route_config.md - customization/redirect_urls.md - - customization/extending_controllers.md - - customization/integrating_custom_view_libs.md - customization/validation_rules.md - customization/user_provider.md + - customization/extending_controllers.md + - customization/integrating_custom_view_libs.md - customization/login_identifier.md - User Management: - user_management/managing_users.md From e52341550b9d9b87503738f9b96e54484c8a253d Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 10:15:16 +0900 Subject: [PATCH 33/45] docs: move files to references/ --- docs/{ => references}/auth_actions.md | 0 docs/{ => references}/authentication.md | 0 docs/{ => references}/authorization.md | 0 docs/{ => references}/controller_filters.md | 22 +++++++++---------- docs/{ => references}/events.md | 0 docs/{ => references}/magic_link_login.md | 2 +- .../session_auth_event_and_logging.md | 0 docs/{ => references}/testing.md | 0 mkdocs.yml | 16 +++++++------- 9 files changed, 20 insertions(+), 20 deletions(-) rename docs/{ => references}/auth_actions.md (100%) rename docs/{ => references}/authentication.md (100%) rename docs/{ => references}/authorization.md (100%) rename docs/{ => references}/controller_filters.md (87%) rename docs/{ => references}/events.md (100%) rename docs/{ => references}/magic_link_login.md (96%) rename docs/{ => references}/session_auth_event_and_logging.md (100%) rename docs/{ => references}/testing.md (100%) diff --git a/docs/auth_actions.md b/docs/references/auth_actions.md similarity index 100% rename from docs/auth_actions.md rename to docs/references/auth_actions.md diff --git a/docs/authentication.md b/docs/references/authentication.md similarity index 100% rename from docs/authentication.md rename to docs/references/authentication.md diff --git a/docs/authorization.md b/docs/references/authorization.md similarity index 100% rename from docs/authorization.md rename to docs/references/authorization.md diff --git a/docs/controller_filters.md b/docs/references/controller_filters.md similarity index 87% rename from docs/controller_filters.md rename to docs/references/controller_filters.md index f219200c1..7db3be157 100644 --- a/docs/controller_filters.md +++ b/docs/references/controller_filters.md @@ -17,17 +17,17 @@ public $aliases = [ ]; ``` -| Filters | Description | -|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| session | The `Session` authenticator. | -| tokens | The `AccessTokens` authenticator. | -| chained | The filter will check authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. | -| jwt | The `JWT` authenticator. See [JWT Authentication](./addons/jwt.md). | -| hmac | The `HMAC` authenticator. See [HMAC Authentication](./guides/api_hmac_keys.md). | -| auth-rates | Provides a good basis for rate limiting of auth-related routes. | -| group | Checks if the user is in one of the groups passed in. | -| permission | Checks if the user has the passed permissions. | -| force-reset | Checks if the user requires a password reset. | +| Filters | Description | +|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| session | The `Session` authenticator. | +| tokens | The `AccessTokens` authenticator. | +| chained | The filter will check authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens. | +| jwt | The `JWT` authenticator. See [JWT Authentication](../addons/jwt.md). | +| hmac | The `HMAC` authenticator. See [HMAC Authentication](../guides/api_hmac_keys.md). | +| auth-rates | Provides a good basis for rate limiting of auth-related routes. | +| group | Checks if the user is in one of the groups passed in. | +| permission | Checks if the user has the passed permissions. | +| force-reset | Checks if the user requires a password reset. | These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). diff --git a/docs/events.md b/docs/references/events.md similarity index 100% rename from docs/events.md rename to docs/references/events.md diff --git a/docs/magic_link_login.md b/docs/references/magic_link_login.md similarity index 96% rename from docs/magic_link_login.md rename to docs/references/magic_link_login.md index ef4b2f15a..220afffbb 100644 --- a/docs/magic_link_login.md +++ b/docs/references/magic_link_login.md @@ -26,7 +26,7 @@ public int $magicLinkLifetime = HOUR; ## Responding to Magic Link Logins > **Note** -> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](./install.md#initial-setup). +> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../install.md#initial-setup). Magic Link logins allow a user that has forgotten their password to have an email sent with a unique, one-time login link. Once they've logged in you can decide how to respond. In some cases, you might want to redirect them to a special page where they must choose a new password. In other cases, you might simply want to display a one-time message prompting them to go to their account page and choose a new password. diff --git a/docs/session_auth_event_and_logging.md b/docs/references/session_auth_event_and_logging.md similarity index 100% rename from docs/session_auth_event_and_logging.md rename to docs/references/session_auth_event_and_logging.md diff --git a/docs/testing.md b/docs/references/testing.md similarity index 100% rename from docs/testing.md rename to docs/references/testing.md diff --git a/mkdocs.yml b/mkdocs.yml index f568a7753..a830ccac7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,13 +65,13 @@ nav: - guides/mobile_apps.md - guides/strengthen_password.md - References: - - controller_filters.md - - Authentication: authentication.md - - auth_actions.md - - magic_link_login.md - - Authorization: authorization.md - - Events: events.md - - Testing: testing.md - - session_auth_event_and_logging.md + - references/controller_filters.md + - references/authentication.md + - references/auth_actions.md + - references/magic_link_login.md + - references/authorization.md + - references/events.md + - references/testing.md + - references/session_auth_event_and_logging.md - Addons: - JWT Authentication: addons/jwt.md From 780c57b5a92799088aff2ee399569b52847ec1cc Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 10:22:31 +0900 Subject: [PATCH 34/45] docs: update links --- docs/customization/user_provider.md | 2 +- docs/{ => getting_started}/authenticators.md | 8 ++++---- docs/{ => getting_started}/concepts.md | 2 +- docs/{ => getting_started}/configuration.md | 0 docs/{ => getting_started}/install.md | 4 ++-- docs/quick_start_guide/using_session_auth.md | 4 ++-- docs/references/magic_link_login.md | 2 +- docs/user_management/managing_users.md | 2 +- mkdocs.yml | 8 ++++---- 9 files changed, 16 insertions(+), 16 deletions(-) rename docs/{ => getting_started}/authenticators.md (60%) rename docs/{ => getting_started}/concepts.md (98%) rename docs/{ => getting_started}/configuration.md (100%) rename docs/{ => getting_started}/install.md (97%) diff --git a/docs/customization/user_provider.md b/docs/customization/user_provider.md index 36af8d838..12246043c 100644 --- a/docs/customization/user_provider.md +++ b/docs/customization/user_provider.md @@ -1,7 +1,7 @@ # Customizing User Provider If you want to customize user attributes, you need to create your own -[User Provider](../concepts.md#user-providers) class. +[User Provider](../getting_started/concepts.md#user-providers) class. The only requirement is that your new class MUST extend the provided `CodeIgniter\Shield\Models\UserModel`. Shield has a CLI command to quickly create a custom `UserModel` class by running the following diff --git a/docs/authenticators.md b/docs/getting_started/authenticators.md similarity index 60% rename from docs/authenticators.md rename to docs/getting_started/authenticators.md index c00a4b6ec..1ff3c9d89 100644 --- a/docs/authenticators.md +++ b/docs/getting_started/authenticators.md @@ -5,11 +5,11 @@ Shield provides the following Authenticators: - **Session** authenticator provides traditional Email/Password authentication. - See [Using Session Authenticator](./quick_start_guide/using_session_auth.md) + See [Using Session Authenticator](../quick_start_guide/using_session_auth.md) for usage. - **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. - See [Protecting an API with Access Tokens](./guides/api_tokens.md) for usage. + See [Protecting an API with Access Tokens](../guides/api_tokens.md) for usage. - **HmacSha256** authenticator provides stateless authentication using HMAC Keys. - See [guides/api_hmac_keys](./guides/api_hmac_keys.md) for usage. + See [guides/api_hmac_keys](../guides/api_hmac_keys.md) for usage. - **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, - you need additional setup. See [JWT Authentication](./addons/jwt.md). + you need additional setup. See [JWT Authentication](../addons/jwt.md). diff --git a/docs/concepts.md b/docs/getting_started/concepts.md similarity index 98% rename from docs/concepts.md rename to docs/getting_started/concepts.md index c5f6c3f65..58d4641c9 100644 --- a/docs/concepts.md +++ b/docs/getting_started/concepts.md @@ -21,7 +21,7 @@ on the standard Config class if nothing is found in the database. Shield has a model to handle user persistence. Shield calls this the "User Provider" class. A default model is provided for you by the `CodeIgniter\Shield\Models\UserModel` class. -You can use your own model to customize user attributes. See [Customizing User Provider](./customization/user_provider.md) for details. +You can use your own model to customize user attributes. See [Customizing User Provider](../customization/user_provider.md) for details. ## User Identities diff --git a/docs/configuration.md b/docs/getting_started/configuration.md similarity index 100% rename from docs/configuration.md rename to docs/getting_started/configuration.md diff --git a/docs/install.md b/docs/getting_started/install.md similarity index 97% rename from docs/install.md rename to docs/getting_started/install.md index 26c17c1a1..8363ca460 100644 --- a/docs/install.md +++ b/docs/getting_started/install.md @@ -64,7 +64,7 @@ Require it with an explicit version constraint allowing its desired stability. > **Note** > If you want to customize table names, you must change the table names > before running database migrations. - > See [Customizing Table Names](./customization/table_names.md). + > See [Customizing Table Names](../customization/table_names.md). 2. Configure **app/Config/Email.php** to allow Shield to send emails with the [Email Class](https://codeigniter.com/user_guide/libraries/email.html). @@ -142,7 +142,7 @@ your project. > **Note** > If you want to customize table names, you must change the table names > before running database migrations. - > See [Customizing Table Names](./customization/table_names.md). + > See [Customizing Table Names](../customization/table_names.md). ```console php spark migrate --all diff --git a/docs/quick_start_guide/using_session_auth.md b/docs/quick_start_guide/using_session_auth.md index 6c7869b62..3dfdf39ef 100644 --- a/docs/quick_start_guide/using_session_auth.md +++ b/docs/quick_start_guide/using_session_auth.md @@ -43,7 +43,7 @@ public array $sessionConfig = [ ### Enable Account Activation via Email > **Note** -> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../install.md#initial-setup). +> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../getting_started/install.md#initial-setup). By default, once a user registers they have an active account that can be used. You can enable Shield's built-in, email-based activation flow within the `Auth` config file. @@ -57,7 +57,7 @@ public array $actions = [ ### Enable Two-Factor Authentication > **Note** -> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../install.md#initial-setup). +> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../getting_started/install.md#initial-setup). Turned off by default, Shield's Email-based 2FA can be enabled by specifying the class to use in the `Auth` config file. diff --git a/docs/references/magic_link_login.md b/docs/references/magic_link_login.md index 220afffbb..361c7aa38 100644 --- a/docs/references/magic_link_login.md +++ b/docs/references/magic_link_login.md @@ -26,7 +26,7 @@ public int $magicLinkLifetime = HOUR; ## Responding to Magic Link Logins > **Note** -> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../install.md#initial-setup). +> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](../getting_started/install.md#initial-setup). Magic Link logins allow a user that has forgotten their password to have an email sent with a unique, one-time login link. Once they've logged in you can decide how to respond. In some cases, you might want to redirect them to a special page where they must choose a new password. In other cases, you might simply want to display a one-time message prompting them to go to their account page and choose a new password. diff --git a/docs/user_management/managing_users.md b/docs/user_management/managing_users.md index 3f4a2b3c0..9d73385d3 100644 --- a/docs/user_management/managing_users.md +++ b/docs/user_management/managing_users.md @@ -1,6 +1,6 @@ # Managing Users -Since Shield uses a more complex user setup than many other systems, separating [User Identities](../concepts.md#user-identities) from the user accounts themselves. This quick overview should help you feel more confident when working with users on a day-to-day basis. +Since Shield uses a more complex user setup than many other systems, separating [User Identities](../getting_started/concepts.md#user-identities) from the user accounts themselves. This quick overview should help you feel more confident when working with users on a day-to-day basis. ## Creating Users diff --git a/mkdocs.yml b/mkdocs.yml index a830ccac7..468d7e210 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,10 +39,10 @@ extra_javascript: nav: - Home: index.md - Getting Started: - - Concepts: concepts.md - - Installation: install.md - - authenticators.md - - configuration.md + - Concepts: getting_started/concepts.md + - getting_started/install.md + - getting_started/authenticators.md + - getting_started/configuration.md - Quick Start Guide: - quick_start_guide/using_session_auth.md - quick_start_guide/using_authorization.md From 564352a693f6fa24d333ed35234307fc563f21e4 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 10:23:45 +0900 Subject: [PATCH 35/45] docs: fix link text --- docs/getting_started/authenticators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started/authenticators.md b/docs/getting_started/authenticators.md index 1ff3c9d89..87c2b3319 100644 --- a/docs/getting_started/authenticators.md +++ b/docs/getting_started/authenticators.md @@ -10,6 +10,6 @@ Shield provides the following Authenticators: - **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. See [Protecting an API with Access Tokens](../guides/api_tokens.md) for usage. - **HmacSha256** authenticator provides stateless authentication using HMAC Keys. - See [guides/api_hmac_keys](../guides/api_hmac_keys.md) for usage. + See [Protecting an API with HMAC Keys](../guides/api_hmac_keys.md) for usage. - **JWT** authenticator provides stateless authentication using JSON Web Token. To use this, you need additional setup. See [JWT Authentication](../addons/jwt.md). From 588d17d7c0a0d0e611323405de0deb8445d45b09 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 19 Sep 2023 10:28:42 +0900 Subject: [PATCH 36/45] docs: add about app/Config/AuthToken.php --- docs/getting_started/configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting_started/configuration.md b/docs/getting_started/configuration.md index df421818d..44694bb97 100644 --- a/docs/getting_started/configuration.md +++ b/docs/getting_started/configuration.md @@ -9,6 +9,7 @@ the following configuration files: - **app/Config/Auth.php** - **app/Config/AuthGroups.php** - For Authorization +- **app/Config/AuthToken.php** - For AccessTokens and HmacSha256 Authentication - **app/Config/AuthJWT.php** - For JWT Authentication Note that you do not need to have configuration files for features you do not use. From 2e48eca57634c5ce10627205651f049f6d2f5123 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:18:42 +0900 Subject: [PATCH 37/45] docs: remove out-of-dated error description --- docs/getting_started/install.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/getting_started/install.md b/docs/getting_started/install.md index 8363ca460..8a23656b0 100644 --- a/docs/getting_started/install.md +++ b/docs/getting_started/install.md @@ -7,6 +7,7 @@ These instructions assume that you have already [installed the CodeIgniter 4 app - [Composer](https://getcomposer.org) - Codeigniter **v4.2.7** or later - A created database that you can access via the Spark CLI script + - InnoDB (not MyISAM) is required if MySQL is used. ## Composer Installation @@ -155,10 +156,6 @@ your project. 1. Remove sample migration files in **tests/_support/Database/Migrations/** 2. Or install `sqlite3` php extension - If you get `Specified key was too long` error: - - 1. Use InnoDB, not MyISAM. - 6. Configure **app/Config/Email.php** to allow Shield to send emails. ```php From 2316f763d53a73949b5dde2858e0cd7144bce6ba Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:21:20 +0900 Subject: [PATCH 38/45] docs: replace "remember me" with remember-me For consistency. --- docs/index.md | 2 +- docs/references/authentication.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 0fcb10842..8c9b4f1c5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ The primary goals for Shield are: ### Important Features -* Session-based authentication (traditional Email/Password with Remember me) +* Session-based authentication (traditional Email/Password with Remember-me) * Stateless authentication using Personal Access Tokens * Optional Email verification on account registration * Optional Email-based Two-Factor Authentication after login diff --git a/docs/references/authentication.md b/docs/references/authentication.md index e87c5d946..b827363eb 100644 --- a/docs/references/authentication.md +++ b/docs/references/authentication.md @@ -73,7 +73,7 @@ Can return a custom bit of information. These will be detailed in the method des The Session authenticator stores the user's authentication within the user's session, and on a secure cookie on their device. This is the standard password-based login used in most web sites. It supports a -secure remember me feature, and more. This can also be used to handle authentication for +secure remember-me feature, and more. This can also be used to handle authentication for single page applications (SPAs). ### attempt() From ab65804b2b61ec1cb075defe00ebe27d16d38978 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:24:32 +0900 Subject: [PATCH 39/45] docs: replace Email/Password with ID/Password --- docs/getting_started/authenticators.md | 2 +- docs/index.md | 2 +- docs/quick_start_guide/using_session_auth.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting_started/authenticators.md b/docs/getting_started/authenticators.md index 87c2b3319..bed96abba 100644 --- a/docs/getting_started/authenticators.md +++ b/docs/getting_started/authenticators.md @@ -4,7 +4,7 @@ Shield provides the following Authenticators: -- **Session** authenticator provides traditional Email/Password authentication. +- **Session** authenticator provides traditional ID/Password authentication. See [Using Session Authenticator](../quick_start_guide/using_session_auth.md) for usage. - **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. diff --git a/docs/index.md b/docs/index.md index 8c9b4f1c5..d8faf8fde 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ The primary goals for Shield are: ### Important Features -* Session-based authentication (traditional Email/Password with Remember-me) +* Session-based authentication (traditional ID/Password with Remember-me) * Stateless authentication using Personal Access Tokens * Optional Email verification on account registration * Optional Email-based Two-Factor Authentication after login diff --git a/docs/quick_start_guide/using_session_auth.md b/docs/quick_start_guide/using_session_auth.md index 3dfdf39ef..76086a855 100644 --- a/docs/quick_start_guide/using_session_auth.md +++ b/docs/quick_start_guide/using_session_auth.md @@ -1,6 +1,6 @@ # Using Session Authenticator -**Session** authenticator provides traditional Email/Password authentication. +**Session** authenticator provides traditional ID/Password authentication. Learning any new authentication system can be difficult, especially as they get more flexible and sophisticated. This guide is intended to provide short examples for common actions you'll take when working with Shield. It is not intended to be the exhaustive documentation for each section. That's better handled through the area-specific doc files. From 4f7d5927cb7088dc2663f2035c2b2a0b5036aadf Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:27:36 +0900 Subject: [PATCH 40/45] docs: add section title --- docs/references/controller_filters.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/references/controller_filters.md b/docs/references/controller_filters.md index 7db3be157..51a761f0d 100644 --- a/docs/references/controller_filters.md +++ b/docs/references/controller_filters.md @@ -1,5 +1,7 @@ # Controller Filters +## Provided Filters + The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes Shield provides are: ```php From cd757a292972dd90f848ebaecb7bd317a409d25a Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:27:50 +0900 Subject: [PATCH 41/45] docs: move note up To stand it out. --- docs/references/controller_filters.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/references/controller_filters.md b/docs/references/controller_filters.md index 51a761f0d..8c6f0372d 100644 --- a/docs/references/controller_filters.md +++ b/docs/references/controller_filters.md @@ -2,6 +2,9 @@ ## Provided Filters +> **Note** +> These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. + The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes Shield provides are: ```php @@ -33,9 +36,6 @@ public $aliases = [ These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html#applying-filters). -> **Note** -> These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. - ## Configure Controller Filters ### Protect All Pages From 10d5f4d0189d20bb084cc0936eedbd658726249c Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:29:49 +0900 Subject: [PATCH 42/45] docs: add link to CI4 user guide --- docs/references/controller_filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/controller_filters.md b/docs/references/controller_filters.md index 8c6f0372d..e10adc888 100644 --- a/docs/references/controller_filters.md +++ b/docs/references/controller_filters.md @@ -3,7 +3,7 @@ ## Provided Filters > **Note** -> These filters are already loaded for you by the registrar class located at **src/Config/Registrar.php**. +> These filters are already loaded for you by the [registrar](https://codeigniter.com/user_guide/general/configuration.html#registrars) class located at **src/Config/Registrar.php**. The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes Shield provides are: From f40a5eee0003e7f367a05e86a568aecbfb49f5a4 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:37:09 +0900 Subject: [PATCH 43/45] docs: make page title shorter --- docs/customization/route_config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/customization/route_config.md b/docs/customization/route_config.md index 729383280..01f59c412 100644 --- a/docs/customization/route_config.md +++ b/docs/customization/route_config.md @@ -1,4 +1,4 @@ -# Customizing Route Configuration +# Customizing Routes If you need to customize how any of the auth features are handled, you will likely need to update the routes to point to the correct controllers. You can still use the `service('auth')->routes()` helper, but you will need to pass the `except` option with a list of routes to customize: From 52d24fdd09412559466ac0c56d694f11ac546940 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:40:25 +0900 Subject: [PATCH 44/45] docs: add Acknowledgements --- docs/index.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/index.md b/docs/index.md index d8faf8fde..ee28fc5a8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,3 +27,22 @@ The primary goals for Shield are: ### License Shield is licensed under the MIT License - see the [LICENSE](https://github.com/codeigniter4/shield/blob/develop/LICENSE) file for details. + +### Acknowledgements + +Every open-source project depends on it's contributors to be a success. The following users have +contributed in one manner or another in making Shield: + + + Contributors + + +Made with [contrib.rocks](https://contrib.rocks). + +The following articles/sites have been fundamental in shaping the security and best practices used +within this library, in no particular order: + +- [Google Cloud: 13 best practices for user account, authentication, and password management, 2021 edition](https://cloud.google.com/blog/products/identity-security/account-authentication-and-password-management-best-practices) +- [NIST Digital Identity Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html) +- [Implementing Secure User Authentication in PHP Applications with Long-Term Persistence (Login with "Remember Me" Cookies) ](https://paragonie.com/blog/2015/04/secure-authentication-php-with-long-term-persistence) +- [Password Storage - OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) From d8c89bc03d1ff43eb9bf81ddfe857bf57ae300f8 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 20 Sep 2023 05:52:19 +0900 Subject: [PATCH 45/45] docs: update and move description for Authenticators --- docs/getting_started/authenticators.md | 7 ++++--- docs/references/authentication.md | 6 +++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/getting_started/authenticators.md b/docs/getting_started/authenticators.md index bed96abba..0714ea226 100644 --- a/docs/getting_started/authenticators.md +++ b/docs/getting_started/authenticators.md @@ -5,9 +5,10 @@ Shield provides the following Authenticators: - **Session** authenticator provides traditional ID/Password authentication. - See [Using Session Authenticator](../quick_start_guide/using_session_auth.md) - for usage. -- **AccessTokens** authenticator provides stateless authentication using Personal Access Tokens. + It uses username/email/password to authenticate against and stores the user + information in the session. See [Using Session Authenticator](../quick_start_guide/using_session_auth.md) for usage. +- **AccessTokens** authenticator provides stateless authentication using Personal + Access Tokens passed in the HTTP headers. See [Protecting an API with Access Tokens](../guides/api_tokens.md) for usage. - **HmacSha256** authenticator provides stateless authentication using HMAC Keys. See [Protecting an API with HMAC Keys](../guides/api_hmac_keys.md) for usage. diff --git a/docs/references/authentication.md b/docs/references/authentication.md index b827363eb..c1286ad4b 100644 --- a/docs/references/authentication.md +++ b/docs/references/authentication.md @@ -6,9 +6,8 @@ web apps and APIs. ## Available Authenticators -Shield ships with 2 authenticators that will serve several typical situations within web app development: the -Session authenticator, which uses username/email/password to authenticate against and stores it in the session, -and the Access Tokens authenticator which uses private access tokens passed in the headers. +Shield ships with 4 authenticators that will serve several typical situations within web app development. +You can see the [Authenticator List](../getting_started/authenticators.md). The available authenticators are defined in `Config\Auth`: @@ -18,6 +17,7 @@ public $authenticators = [ 'session' => Session::class, 'tokens' => AccessTokens::class, 'hmac' => HmacSha256::class, + // 'jwt' => JWT::class, ]; ```