From ebfa46d280b903a7a97b8649403d5841a2317fa5 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 14:31:37 +0900 Subject: [PATCH 01/18] docs: add "What is Shield?" --- docs/index.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/index.md b/docs/index.md index 8d1103e7a..c7b11c8ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,35 @@ # Shield Documentation +## What is Shield? + +Shield is an authentication and authorization framework for CodeIgniter 4. While +it does provide a base set of tools that are commonly used in websites, it is +designed to be flexible and easily customizable. + +### Primary Goals + +The primary goals for Shield are: + +1. It must be very flexible and allow developers to extend/override almost any part of it. +2. It must have security at its core. It is an auth lib after all. +3. To cover many auth needs right out of the box, but be simple to add additional functionality to. + +### Important Features + +* 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 + +### License + +Shield is licensed under the MIT License - see the [LICENSE](https://github.com/codeigniter4/shield/blob/develop/LICENSE) file for details. + +## Getting Started + * [Installation Guide](install.md) * [Concepts You Need To Know](concepts.md) * [Quick Start Guide](quickstart.md) From d649989923be9a554337c95e65bebd877ef0be5b Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 14:32:23 +0900 Subject: [PATCH 02/18] docs: remove TOC It is redundant because TOC is put in the right column. --- docs/auth_actions.md | 4 ---- docs/authentication.md | 28 ---------------------------- docs/authorization.md | 25 ------------------------- docs/banning_users.md | 4 ---- docs/concepts.md | 7 ------- docs/customization.md | 15 --------------- docs/events.md | 10 ---------- docs/forcing_password_reset.md | 8 -------- docs/install.md | 13 ------------- docs/quickstart.md | 27 --------------------------- 10 files changed, 141 deletions(-) diff --git a/docs/auth_actions.md b/docs/auth_actions.md index 4fb2a5866..e7275b0b2 100644 --- a/docs/auth_actions.md +++ b/docs/auth_actions.md @@ -1,9 +1,5 @@ # Authentication Actions -- [Authentication Actions](#authentication-actions) - - [Configuring Actions](#configuring-actions) - - [Defining New Actions](#defining-new-actions) - Authentication Actions are a way to group actions that can happen after login or registration. Shield ships with two actions you can use, and makes it simple for you to define your own. diff --git a/docs/authentication.md b/docs/authentication.md index 7a5f026e1..e87c5d946 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,33 +1,5 @@ # Authentication -- [Authentication](#authentication) - - [Available Authenticators](#available-authenticators) - - [Auth Helper](#auth-helper) - - [Authenticator Responses](#authenticator-responses) - - [isOK()](#isok) - - [reason()](#reason) - - [extraInfo()](#extrainfo) - - [Session Authenticator](#session-authenticator) - - [attempt()](#attempt) - - [check()](#check) - - [loggedIn()](#loggedin) - - [logout()](#logout) - - [forget()](#forget) - - [Access Token Authenticator](#access-token-authenticator) - - [Access Token/API Authentication](#access-tokenapi-authentication) - - [Generating Access Tokens](#generating-access-tokens) - - [Revoking Access Tokens](#revoking-access-tokens) - - [Retrieving Access Tokens](#retrieving-access-tokens) - - [Access Token Lifetime](#access-token-lifetime) - - [Access Token Scopes](#access-token-scopes) - - [HMAC SHA256 Token Authenticator](#hmac-sha256-token-authenticator) - - [HMAC Keys/API Authentication](#hmac-keysapi-authentication) - - [Generating HMAC Access Keys](#generating-hmac-access-keys) - - [Revoking HMAC Keys](#revoking-hmac-keys) - - [Retrieving HMAC Keys](#retrieving-hmac-keys) - - [HMAC Keys Lifetime](#hmac-keys-lifetime) - - [HMAC Keys Scopes](#hmac-keys-scopes) - Authentication is the process of determining that a visitor actually belongs to your website, and identifying them. Shield provides a flexible and secure authentication system for your web apps and APIs. diff --git a/docs/authorization.md b/docs/authorization.md index 7265ce6c2..571af598d 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -1,30 +1,5 @@ # Authorization -- [Authorization](#authorization) - - [Defining Available Groups](#defining-available-groups) - - [Default User Group](#default-user-group) - - [Defining Available Permissions](#defining-available-permissions) - - [Assigning Permissions to Groups](#assigning-permissions-to-groups) - - [Authorizing Users](#authorizing-users) - - [can()](#can) - - [inGroup()](#ingroup) - - [hasPermission()](#haspermission) - - [Authorizing via Routes](#authorizing-via-routes) - - [Managing User Permissions](#managing-user-permissions) - - [addPermission()](#addpermission) - - [removePermission()](#removepermission) - - [syncPermissions()](#syncpermissions) - - [getPermissions()](#getpermissions) - - [Managing User Groups](#managing-user-groups) - - [addGroup()](#addgroup) - - [removeGroup()](#removegroup) - - [syncGroups()](#syncgroups) - - [getGroups()](#getgroups) - - [User Activation](#user-activation) - - [Checking Activation Status](#checking-activation-status) - - [Activating a User](#activating-a-user) - - [Deactivating a User](#deactivating-a-user) - Authorization happens once a user has been identified through authentication. It is the process of determining what actions a user is allowed to do within your site. diff --git a/docs/banning_users.md b/docs/banning_users.md index b0a81c4da..b4fea4c40 100644 --- a/docs/banning_users.md +++ b/docs/banning_users.md @@ -2,10 +2,6 @@ Shield provides a way to ban users from your application. This is useful if you need to prevent a user from logging in, or logging them out in the event that they breach your terms of service. -- [Checking if the User is Banned](#check-if-a-user-is-banned) -- [Banning a User](#banning-a-user) -- [Unbanning a User](#unbanning-a-user) -- [Getting the Reason for Ban ](#getting-the-reason-for-ban) ### Check if a User is Banned diff --git a/docs/concepts.md b/docs/concepts.md index eaf57379a..dc1b17452 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -2,13 +2,6 @@ This document covers some of the base concepts used throughout the library. -- [Shield Concepts](#shield-concepts) - - [Repository State](#repository-state) - - [Settings](#settings) - - [User Providers](#user-providers) - - [User Identities](#user-identities) - - [Password Validators](#password-validators) - ## Repository State Shield is designed so that the initial setup of your application can all happen in code with nothing required to be diff --git a/docs/customization.md b/docs/customization.md index 52f6108a3..66e21312e 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -1,20 +1,5 @@ # Customizing Shield -- [Customizing Shield](#customizing-shield) - - [Custom Table Names](#custom-table-names) - - [Route Configuration](#route-configuration) - - [Custom Redirect URLs](#custom-redirect-urls) - - [Customize Login Redirect](#customize-login-redirect) - - [Customize Register Redirect](#customize-register-redirect) - - [Customize Logout Redirect](#customize-logout-redirect) - - [Extending the Controllers](#extending-the-controllers) - - [Integrating Custom View Libraries](#integrating-custom-view-libraries) - - [Custom Validation Rules](#custom-validation-rules) - - [Registration](#registration) - - [Login](#login) - - [Custom User Provider](#custom-user-provider) - - [Custom Login Identifier](#custom-login-identifier) - ## Custom Table Names If you want to change the default table names, you can change the table names diff --git a/docs/events.md b/docs/events.md index c1609f030..b1360de48 100644 --- a/docs/events.md +++ b/docs/events.md @@ -2,16 +2,6 @@ Shield fires off several events during the lifecycle of the application that your code can tap into. -- [Events](#events) - - [Responding to Events](#responding-to-events) - - [Event List](#event-list) - - [register](#register) - - [login](#login) - - [failedLogin](#failedlogin) - - [logout](#logout) - - [magicLogin](#magiclogin) - - [Event Timing](#event-timing) - ## Responding to Events When you want to respond to an event that Shield publishes, you will need to add it to your **app/Config/Events.php** diff --git a/docs/forcing_password_reset.md b/docs/forcing_password_reset.md index 927b3aec8..241af0988 100644 --- a/docs/forcing_password_reset.md +++ b/docs/forcing_password_reset.md @@ -2,14 +2,6 @@ Depending on the scope of your application, there may be times when you'll decide that it is absolutely necessary to force user(s) to reset their password. This practice is common when you find out that users of your application do not use strong passwords OR there is a reasonable suspicion that their passwords have been compromised. This guide provides you with ways to achieve this. -- [Forcing Password Reset](#forcing-password-reset) - - [Available Methods](#available-methods) - - [Check if a User Requires Password Reset](#check-if-a-user-requires-password-reset) - - [Force Password Reset On a User](#force-password-reset-on-a-user) - - [Remove Force Password Reset Flag On a User](#remove-force-password-reset-flag-on-a-user) - - [Force Password Reset On Multiple Users](#force-password-reset-on-multiple-users) - - [Force Password Reset On All Users](#force-password-reset-on-all-users) - ## Available Methods Shield provides a way to enforce password resets throughout your application. The `Resettable` trait on the `User` entity and the `UserIdentityModel` provides the following methods to do so. diff --git a/docs/install.md b/docs/install.md index c3452f19c..ecf9ab3a3 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,18 +1,5 @@ # Installation -- [Installation](#installation) - - [Requirements](#requirements) - - [Composer Installation](#composer-installation) - - [Troubleshooting](#troubleshooting) - - [IMPORTANT: composer error](#important-composer-error) - - [Initial Setup](#initial-setup) - - [Command Setup](#command-setup) - - [Manual Setup](#manual-setup) - - [Controller Filters](#controller-filters) - - [Protect All Pages](#protect-all-pages) - - [Rate Limiting](#rate-limiting) - - [Forcing Password Reset](#forcing-password-reset) - These instructions assume that you have already [installed the CodeIgniter 4 app starter](https://codeigniter.com/user_guide/installation/installing_composer.html) as the basis for your new project, set up your **.env** file, and created a database that you can access via the Spark CLI script. ## Requirements diff --git a/docs/quickstart.md b/docs/quickstart.md index 49e25a38f..3281985e9 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -4,33 +4,6 @@ Learning any new authentication system can be difficult, especially as they get > **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. -- [Quick Start Guide](#quick-start-guide) - - [Authentication Flow](#authentication-flow) - - [Configure Config\\Auth](#configure-configauth) - - [Configure Redirect URLs](#configure-redirect-urls) - - [Configure Remember-me Functionality](#configure-remember-me-functionality) - - [Change Access Token Lifetime](#change-access-token-lifetime) - - [Enable Account Activation via Email](#enable-account-activation-via-email) - - [Enable Two-Factor Authentication](#enable-two-factor-authentication) - - [Responding to Magic Link Logins](#responding-to-magic-link-logins) - - [Session Notification](#session-notification) - - [Event](#event) - - [Authorization Flow](#authorization-flow) - - [Configure Config\\AuthGroups](#configure-configauthgroups) - - [Change Available Groups](#change-available-groups) - - [Set the Default Group](#set-the-default-group) - - [Change Available Permissions](#change-available-permissions) - - [Assign Permissions to a Group](#assign-permissions-to-a-group) - - [Assign Permissions to a User](#assign-permissions-to-a-user) - - [Check If a User Has Permission](#check-if-a-user-has-permission) - - [Adding a Group To a User](#adding-a-group-to-a-user) - - [Removing a Group From a User](#removing-a-group-from-a-user) - - [Checking If User Belongs To a Group](#checking-if-user-belongs-to-a-group) - - [Managing Users](#managing-users) - - [Creating Users](#creating-users) - - [Deleting Users](#deleting-users) - - [Editing a User](#editing-a-user) - ## Authentication Flow ### Configure Config\Auth From eb48201f630a66fcfd9eae386eccba3fd31f4eef Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 14:33:23 +0900 Subject: [PATCH 03/18] docs: remove white speaces --- docs/banning_users.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/banning_users.md b/docs/banning_users.md index b4fea4c40..54e1196fd 100644 --- a/docs/banning_users.md +++ b/docs/banning_users.md @@ -2,16 +2,15 @@ Shield provides a way to ban users from your application. This is useful if you need to prevent a user from logging in, or logging them out in the event that they breach your terms of service. +### Check if a User is Banned -### Check if a User is Banned - -You can check if a user is banned using `isBanned()` method on the `User` entity. The method returns a boolean `true`/`false`. +You can check if a user is banned using `isBanned()` method on the `User` entity. The method returns a boolean `true`/`false`. ```php if ($user->isBanned()) { //... } -``` +``` ### Banning a User @@ -26,7 +25,7 @@ $user->ban('Your reason for banning the user here'); ### Unbanning a User -Unbanning a user can be done using the `unBan()` method on the `User` entity. This method will also reset the `status_message` property. +Unbanning a user can be done using the `unBan()` method on the `User` entity. This method will also reset the `status_message` property. ```php $user->unBan(); @@ -38,4 +37,4 @@ The reason for the ban can be obtained user the `getBanMessage()` method on the ```php $user->getBanMessage(); -``` \ No newline at end of file +``` From 0ca67e33eaf27f3c69dfed5952cb4af5824bfc9b Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 14:33:40 +0900 Subject: [PATCH 04/18] docs: add section title --- docs/testing.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/testing.md b/docs/testing.md index 27cd64dbe..30766858a 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,6 +1,8 @@ # Testing -When performing [HTTP testing](https://codeigniter.com/user_guide/testing/feature.html) in your applications, you +## HTTP Feature Testing + +When performing [HTTP Feature Testing](https://codeigniter.com/user_guide/testing/feature.html) in your applications, you will often need to ensure you are logged in to check security, or simply to access protected locations. Shield provides the `AuthenticationTesting` trait to help you out. Use it within the test class and then you can use the `actingAs()` method that takes a User instance. This user will be logged in during the test. @@ -24,7 +26,7 @@ class ActionsTest extends TestCase ->withSession([ 'auth_action' => Email2FA::class, ])->get('/auth/a/show'); - + $result->assertStatus(200); // Should auto-populate in the form $result->assertSee($this->user->email); From b6020564b5f6c35084035ed154070482c3db9798 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 14:33:55 +0900 Subject: [PATCH 05/18] docs: reorganize TOC --- mkdocs.yml | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 8e3d3140d..ed9048c0f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,18 +38,21 @@ extra_javascript: nav: - Home: index.md - - Installation: install.md - - Concepts: concepts.md - - Quick Start Guide: quickstart.md - - Authentication: authentication.md - - Authorization: authorization.md - - Auth Actions: auth_actions.md - - Events: events.md - - Testing: testing.md - - Customization: customization.md - - Forcing Password Reset: forcing_password_reset.md - - Banning Users: banning_users.md - - session_auth_event_and_logging.md + - Getting Started: + - Installation: install.md + - Concepts: concepts.md + - Quick Start Guide: quickstart.md + - References: + - Authentication: authentication.md + - Authorization: authorization.md + - Auth Actions: auth_actions.md + - Events: events.md + - Testing: testing.md + - Forcing Password Reset: forcing_password_reset.md + - Banning Users: banning_users.md + - session_auth_event_and_logging.md + - Customization: + - customization.md - Guides: - guides/api_hmac_keys.md - guides/api_tokens.md From f9fbb4a48435fcf7d8c9ffd75f32fa7a03c0d2f2 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 16:51:16 +0900 Subject: [PATCH 06/18] docs: split quickstart.md --- docs/authenticaton_flow.md | 108 ++++++++++++++ docs/authorization_flow.md | 127 ++++++++++++++++ docs/index.md | 10 +- docs/managing_users.md | 57 ++++++++ docs/quickstart.md | 292 ------------------------------------- mkdocs.yml | 5 +- 6 files changed, 305 insertions(+), 294 deletions(-) create mode 100644 docs/authenticaton_flow.md create mode 100644 docs/authorization_flow.md create mode 100644 docs/managing_users.md delete mode 100644 docs/quickstart.md diff --git a/docs/authenticaton_flow.md b/docs/authenticaton_flow.md new file mode 100644 index 000000000..7827d0ab9 --- /dev/null +++ b/docs/authenticaton_flow.md @@ -0,0 +1,108 @@ +# Authentication Flow + +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 Redirect URLs + +If you need everyone to redirect to a single URL after login/logout/register actions, you can modify the `Config\Auth::$redirects` array in **app/Config/Auth.php**`** to specify the url to redirect to. + +By default, a successful login or register attempt will all redirect to `/`, while a logout action +will redirect to a [named route](https://codeigniter.com/user_guide/incoming/routing.html#using-named-routes "See routing docs") `login` or a *URI path* `/login`. You can change the default URLs used within the **`**app/Config/Auth.php** config file: + +```php +public array $redirects = [ + 'register' => '/', + 'login' => '/', + 'logout' => 'login', +]; +``` + +> **Note** +> This redirect happens after the specified action is complete. In the case of register or login, it might not happen immediately. For example, if you have any Auth Actions specified, they will be redirected when those actions are completed successfully. If no Auth Actions are specified, they will be redirected immediately after registration or login. + +### Configure Remember-me Functionality + +Remember-me functionality is enabled by default for the `Session` handler. 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 = [ + 'field' => 'user', + 'allowRemembering' => true, + 'rememberCookieName' => 'remember', + 'rememberLength' => 30 * DAY, +]; +``` + +### 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** +> You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](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. + +```php +public array $actions = [ + 'register' => \CodeIgniter\Shield\Authentication\Actions\EmailActivator::class, + 'login' => null, +]; +``` + +### 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). + +Turned off by default, Shield's Email-based 2FA can be enabled by specifying the class to use in the `Auth` config file. + +```php +public array $actions = [ + 'register' => null, + '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/docs/authorization_flow.md b/docs/authorization_flow.md new file mode 100644 index 000000000..568ca5094 --- /dev/null +++ b/docs/authorization_flow.md @@ -0,0 +1,127 @@ +# Authorization Flow + +## Configure Config\AuthGroups + +### 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/index.md b/docs/index.md index c7b11c8ee..994283c94 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,7 +32,15 @@ Shield is licensed under the MIT License - see the [LICENSE](https://github.com/ * [Installation Guide](install.md) * [Concepts You Need To Know](concepts.md) -* [Quick Start Guide](quickstart.md) + +## Quick Start Guide + +* [Authentication Flow](authenticaton_flow.md) +* [Authorization Flow](authorization_flow.md) +* [Managing Users](managing_users.md) + +## References + * [Authentication](authentication.md) * [Authorization](authorization.md) * [Auth Actions](auth_actions.md) diff --git a/docs/managing_users.md b/docs/managing_users.md new file mode 100644 index 000000000..e963a3b34 --- /dev/null +++ b/docs/managing_users.md @@ -0,0 +1,57 @@ +# 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. + +## Creating Users + +By default, the only values stored in the users table is the username. The first step is to create the user record with the username. If you don't have a username, be sure to set the value to `null` anyway, so that it passes CodeIgniter's empty data check. + +```php +use CodeIgniter\Shield\Entities\User; + +// Get the User Provider (UserModel by default) +$users = auth()->getProvider(); + +$user = new User([ + 'username' => 'foo-bar', + 'email' => 'foo.bar@example.com', + 'password' => 'secret plain text password', +]); +$users->save($user); + +// To get the complete user object with ID, we need to get from the database +$user = $users->findById($users->getInsertID()); + +// Add to default group +$users->addToDefaultGroup($user); +``` + +## Deleting Users + +A user's data can be spread over a few different tables so you might be concerned about how to delete all of the user's data from the system. This is handled automatically at the database level for all information that Shield knows about, through the `onCascade` settings of the table's foreign keys. You can delete a user like any other entity. + +```php +// Get the User Provider (UserModel by default) +$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. + +## Editing a User + +The `UserModel::save()`, `update()` and `insert()` methods have been modified to ensure that an email or password previously set on the `User` entity will be automatically updated in the correct `UserIdentity` record. + +```php +// Get the User Provider (UserModel by default) +$users = auth()->getProvider(); + +$user = $users->findById(123); +$user->fill([ + 'username' => 'JoeSmith111', + 'email' => 'joe.smith@example.com', + 'password' => 'secret123' +]); +$users->save($user); +``` diff --git a/docs/quickstart.md b/docs/quickstart.md deleted file mode 100644 index 3281985e9..000000000 --- a/docs/quickstart.md +++ /dev/null @@ -1,292 +0,0 @@ -# Quick Start Guide - -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. - -## Authentication Flow - -### Configure Config\Auth - -#### Configure Redirect URLs - -If you need everyone to redirect to a single URL after login/logout/register actions, you can modify the `Config\Auth::$redirects` array in **app/Config/Auth.php**`** to specify the url to redirect to. - -By default, a successful login or register attempt will all redirect to `/`, while a logout action -will redirect to a [named route](https://codeigniter.com/user_guide/incoming/routing.html#using-named-routes "See routing docs") `login` or a *URI path* `/login`. You can change the default URLs used within the **`**app/Config/Auth.php** config file: - -```php -public array $redirects = [ - 'register' => '/', - 'login' => '/', - 'logout' => 'login', -]; -``` - -> **Note** This redirect happens after the specified action is complete. In the case of register or login, it might not happen immediately. For example, if you have any Auth Actions specified, they will be redirected when those actions are completed successfully. If no Auth Actions are specified, they will be redirected immediately after registration or login. - -#### Configure Remember-me Functionality - -Remember-me functionality is enabled by default for the `Session` handler. 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 = [ - 'field' => 'user', - 'allowRemembering' => true, - 'rememberCookieName' => 'remember', - 'rememberLength' => 30 * DAY, -]; -``` - -#### 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** You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](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. - -```php -public array $actions = [ - 'register' => \CodeIgniter\Shield\Authentication\Actions\EmailActivator::class, - 'login' => null, -]; -``` - -#### 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). - -Turned off by default, Shield's Email-based 2FA can be enabled by specifying the class to use in the `Auth` config file. - -```php -public array $actions = [ - 'register' => null, - '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 () { - // ... -}); -``` - - -## Authorization Flow - -### Configure Config\AuthGroups - -#### 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 -} -``` - -## 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. - -### Creating Users - -By default, the only values stored in the users table is the username. The first step is to create the user record with the username. If you don't have a username, be sure to set the value to `null` anyway, so that it passes CodeIgniter's empty data check. - -```php -use CodeIgniter\Shield\Entities\User; - -// Get the User Provider (UserModel by default) -$users = auth()->getProvider(); - -$user = new User([ - 'username' => 'foo-bar', - 'email' => 'foo.bar@example.com', - 'password' => 'secret plain text password', -]); -$users->save($user); - -// To get the complete user object with ID, we need to get from the database -$user = $users->findById($users->getInsertID()); - -// Add to default group -$users->addToDefaultGroup($user); -``` - -### Deleting Users - -A user's data can be spread over a few different tables so you might be concerned about how to delete all of the user's data from the system. This is handled automatically at the database level for all information that Shield knows about, through the `onCascade` settings of the table's foreign keys. You can delete a user like any other entity. - -```php -// Get the User Provider (UserModel by default) -$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. - -### Editing a User - -The `UserModel::save()`, `update()` and `insert()` methods have been modified to ensure that an email or password previously set on the `User` entity will be automatically updated in the correct `UserIdentity` record. - -```php -// Get the User Provider (UserModel by default) -$users = auth()->getProvider(); - -$user = $users->findById(123); -$user->fill([ - 'username' => 'JoeSmith111', - 'email' => 'joe.smith@example.com', - 'password' => 'secret123' -]); -$users->save($user); -``` diff --git a/mkdocs.yml b/mkdocs.yml index ed9048c0f..08fe66e39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,7 +41,10 @@ nav: - Getting Started: - Installation: install.md - Concepts: concepts.md - - Quick Start Guide: quickstart.md + - Quick Start Guide: + - authenticaton_flow.md + - authorization_flow.md + - managing_users.md - References: - Authentication: authentication.md - Authorization: authorization.md From 79ff70c848844268c5e4f809ac264481f46f4eb9 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 16:57:21 +0900 Subject: [PATCH 07/18] docs: remove redundant TOC --- docs/index.md | 32 -------------------------------- 1 file changed, 32 deletions(-) diff --git a/docs/index.md b/docs/index.md index 994283c94..3384d3360 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,35 +27,3 @@ 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. - -## Getting Started - -* [Installation Guide](install.md) -* [Concepts You Need To Know](concepts.md) - -## Quick Start Guide - -* [Authentication Flow](authenticaton_flow.md) -* [Authorization Flow](authorization_flow.md) -* [Managing Users](managing_users.md) - -## References - -* [Authentication](authentication.md) -* [Authorization](authorization.md) -* [Auth Actions](auth_actions.md) -* [Events](events.md) -* [Testing](testing.md) -* [Customization](customization.md) -* [Forcing Password Reset](forcing_password_reset.md) -* [Banning Users](banning_users.md) - -## Guides - -* [Protecting an API with Access Tokens](guides/api_tokens.md) -* [Mobile Authentication with Access Tokens](guides/mobile_apps.md) -* [How to Strengthen the Password](guides/strengthen_password.md) - -## Addons - -* [JWT Authentication](addons/jwt.md) From c14253af51da6c5b01c11e92eb5ddcbd418a9bb3 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 16:58:29 +0900 Subject: [PATCH 08/18] docs: move two pages to Guides --- mkdocs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 08fe66e39..4bc40484c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,14 +51,14 @@ nav: - Auth Actions: auth_actions.md - Events: events.md - Testing: testing.md - - Forcing Password Reset: forcing_password_reset.md - - Banning Users: banning_users.md - session_auth_event_and_logging.md - Customization: - customization.md - Guides: - - guides/api_hmac_keys.md + - Forcing Password Reset: forcing_password_reset.md + - Banning Users: banning_users.md - guides/api_tokens.md + - guides/api_hmac_keys.md - guides/mobile_apps.md - guides/strengthen_password.md - Addons: From 5db81205a30743f28c6743250a7d2b55f470ea79 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 16:59:22 +0900 Subject: [PATCH 09/18] docs: move Concepts to first --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 4bc40484c..23c179231 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,8 +39,8 @@ extra_javascript: nav: - Home: index.md - Getting Started: - - Installation: install.md - Concepts: concepts.md + - Installation: install.md - Quick Start Guide: - authenticaton_flow.md - authorization_flow.md From e43e689ce8a6c719e5497d5f096225b5575bb3d9 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 17:10:13 +0900 Subject: [PATCH 10/18] docs: move two files to guides/ --- docs/{ => guides}/banning_users.md | 0 docs/{ => guides}/forcing_password_reset.md | 0 mkdocs.yml | 4 ++-- 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/{ => guides}/banning_users.md (100%) rename docs/{ => guides}/forcing_password_reset.md (100%) diff --git a/docs/banning_users.md b/docs/guides/banning_users.md similarity index 100% rename from docs/banning_users.md rename to docs/guides/banning_users.md diff --git a/docs/forcing_password_reset.md b/docs/guides/forcing_password_reset.md similarity index 100% rename from docs/forcing_password_reset.md rename to docs/guides/forcing_password_reset.md diff --git a/mkdocs.yml b/mkdocs.yml index 23c179231..567f5f45a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -55,8 +55,8 @@ nav: - Customization: - customization.md - Guides: - - Forcing Password Reset: forcing_password_reset.md - - Banning Users: banning_users.md + - guides/forcing_password_reset.md + - guides/banning_users.md - guides/api_tokens.md - guides/api_hmac_keys.md - guides/mobile_apps.md From 32a68b048ab45e83708a1015875bd511692e827a Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 17:11:56 +0900 Subject: [PATCH 11/18] docs: fix typo in file name --- docs/{authenticaton_flow.md => authentication_flow.md} | 0 mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{authenticaton_flow.md => authentication_flow.md} (100%) diff --git a/docs/authenticaton_flow.md b/docs/authentication_flow.md similarity index 100% rename from docs/authenticaton_flow.md rename to docs/authentication_flow.md diff --git a/mkdocs.yml b/mkdocs.yml index 567f5f45a..7b64bf5c3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,7 +42,7 @@ nav: - Concepts: concepts.md - Installation: install.md - Quick Start Guide: - - authenticaton_flow.md + - authentication_flow.md - authorization_flow.md - managing_users.md - References: From ac9aff9da4601bc02c7716d2cbb286cb735b151a Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 17:12:59 +0900 Subject: [PATCH 12/18] docs: move three files to quick_start_guide/ --- docs/{ => quick_start_guide}/authentication_flow.md | 0 docs/{ => quick_start_guide}/authorization_flow.md | 0 docs/{ => quick_start_guide}/managing_users.md | 0 mkdocs.yml | 6 +++--- 4 files changed, 3 insertions(+), 3 deletions(-) rename docs/{ => quick_start_guide}/authentication_flow.md (100%) rename docs/{ => quick_start_guide}/authorization_flow.md (100%) rename docs/{ => quick_start_guide}/managing_users.md (100%) diff --git a/docs/authentication_flow.md b/docs/quick_start_guide/authentication_flow.md similarity index 100% rename from docs/authentication_flow.md rename to docs/quick_start_guide/authentication_flow.md diff --git a/docs/authorization_flow.md b/docs/quick_start_guide/authorization_flow.md similarity index 100% rename from docs/authorization_flow.md rename to docs/quick_start_guide/authorization_flow.md diff --git a/docs/managing_users.md b/docs/quick_start_guide/managing_users.md similarity index 100% rename from docs/managing_users.md rename to docs/quick_start_guide/managing_users.md diff --git a/mkdocs.yml b/mkdocs.yml index 7b64bf5c3..ad589d868 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,9 +42,9 @@ nav: - Concepts: concepts.md - Installation: install.md - Quick Start Guide: - - authentication_flow.md - - authorization_flow.md - - managing_users.md + - quick_start_guide/authentication_flow.md + - quick_start_guide/authorization_flow.md + - quick_start_guide/managing_users.md - References: - Authentication: authentication.md - Authorization: authorization.md From 0c60b997b4cbc0fb46c8d31dc78187113c01662a Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 17:13:31 +0900 Subject: [PATCH 13/18] docs: fix indentation --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index ad589d868..5c63132ce 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,7 +53,7 @@ nav: - Testing: testing.md - session_auth_event_and_logging.md - Customization: - - customization.md + - customization.md - Guides: - guides/forcing_password_reset.md - guides/banning_users.md From 4db37306cc36249f4241fee24df0359f9c8d759a Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 17:27:17 +0900 Subject: [PATCH 14/18] docs: split customization.md --- docs/customization.md | 312 ------------------ docs/customization/extending_controllers.md | 31 ++ .../integrating_custom_view_libs.md | 18 + docs/customization/login_identifier.md | 34 ++ docs/customization/redirect_urls.md | 60 ++++ docs/customization/route_config.md | 14 + docs/customization/table_names.md | 20 ++ docs/customization/user_provider.md | 20 ++ docs/customization/validation_rules.md | 106 ++++++ mkdocs.yml | 9 +- 10 files changed, 311 insertions(+), 313 deletions(-) delete mode 100644 docs/customization.md create mode 100644 docs/customization/extending_controllers.md create mode 100644 docs/customization/integrating_custom_view_libs.md create mode 100644 docs/customization/login_identifier.md create mode 100644 docs/customization/redirect_urls.md create mode 100644 docs/customization/route_config.md create mode 100644 docs/customization/table_names.md create mode 100644 docs/customization/user_provider.md create mode 100644 docs/customization/validation_rules.md diff --git a/docs/customization.md b/docs/customization.md deleted file mode 100644 index 66e21312e..000000000 --- a/docs/customization.md +++ /dev/null @@ -1,312 +0,0 @@ -# Customizing Shield - -## Custom Table Names - -If you want to change the default table names, you can change the table names -in **app/Config/Auth.php**. - -```php -public array $tables = [ - 'users' => 'users', - 'identities' => 'auth_identities', - 'logins' => 'auth_logins', - 'token_logins' => 'auth_token_logins', - 'remember_tokens' => 'auth_remember_tokens', - 'groups_users' => 'auth_groups_users', - 'permissions_users' => 'auth_permissions_users', -]; -``` - -Set the table names that you want in the array values. - -> **Note** You must change the table names before running database migrations. - -## Route Configuration - -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: - -```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'); -``` - -## Custom Redirect URLs - -### Customize Login Redirect - -You can customize where a user is redirected to on login with the `loginRedirect()` method of the **app/Config/Auth.php** config file. This is handy if you want to redirect based on user group or other criteria. - -```php -public function loginRedirect(): string -{ - $url = auth()->user()->inGroup('admin') - ? '/admin' - : setting('Auth.redirects')['login']; - - return $this->getUrl($url); -} -``` - -Oftentimes, you will want to have different redirects for different user groups. A simple example -might be that you want admins redirected to `/admin` while all other groups redirect to `/`. -The **app/Config/Auth.php** config file also includes methods that you can add additional logic to in order to -achieve this: - -```php -public function loginRedirect(): string -{ - if (auth()->user()->can('admin.access')) { - return '/admin'; - } - - $url = setting('Auth.redirects')['login']; - - return $this->getUrl($url); -} -``` - -### Customize Register Redirect - -You can customize where a user is redirected to after registration in the `registerRedirect()` method of the **app/Config/Auth.php** config file. - -```php -public function registerRedirect(): string -{ - $url = setting('Auth.redirects')['register']; - - return $this->getUrl($url); -} -``` - -### Customize Logout Redirect - -The logout redirect can also be overridden by the `logoutRedirect()` method of the **app/Config/Auth.php** config file. This will not be used as often as login and register, but you might find the need. For example, if you programatically logged a user out you might want to take them to a page that specifies why they were logged out. Otherwise, you might take them to the home page or even the login page. - -```php -public function logoutRedirect(): string -{ - $url = setting('Auth.redirects')['logout']; - - return $this->getUrl($url); -} -``` - -## Extending the Controllers - -Shield has the following controllers that can be extended to handle -various parts of the authentication process: - -- **ActionController** handles the after-login and after-registration actions, like Two Factor Authentication and Email Verification. -- **LoginController** handles the login process. -- **RegisterController** handles the registration process. Overriding this class allows you to customize the User Provider, the User Entity, and the validation rules. -- **MagicLinkController** handles the "lost password" process that allows a user to login with a link sent to their email. This allows you to - override the message that is displayed to a user to describe what is happening, if you'd like to provide more information than simply swapping out the view used. - -It is not recommended to copy the entire controller into **app/Controllers** and change its namespace. Instead, you should create a new controller that extends -the existing controller and then only override the methods needed. This allows the other methods to stay up to date with any security -updates that might happen in the controllers. - -```php -themedView($view, $data, $options); - } -} -``` - -## Custom Validation Rules - -### Registration - -Shield has the following rules for registration: - -```php -[ - 'username' => [ - 'label' => 'Auth.username', - 'rules' => [ - 'required', - 'max_length[30]', - 'min_length[3]', - 'regex_match[/\A[a-zA-Z0-9\.]+\z/]', - 'is_unique[users.username]', - ], - ], - 'email' => [ - 'label' => 'Auth.email', - 'rules' => [ - 'required', - 'max_length[254]', - 'valid_email', - 'is_unique[auth_identities.secret]', - ], - ], - 'password' => [ - 'label' => 'Auth.password', - 'rules' => 'required|strong_password', - ], - 'password_confirm' => [ - 'label' => 'Auth.passwordConfirm', - 'rules' => 'required|matches[password]', - ], -]; -``` - -> **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()`. - -If you need a different set of rules for registration, you can specify them in your `Validation` configuration (**app/Config/Validation.php**) like: - -```php - //-------------------------------------------------------------------- - // Rules For Registration - //-------------------------------------------------------------------- - public $registration = [ - 'username' => [ - 'label' => 'Auth.username', - 'rules' => [ - 'required', - 'max_length[30]', - 'min_length[3]', - 'regex_match[/\A[a-zA-Z0-9\.]+\z/]', - 'is_unique[users.username]', - ], - ], - 'email' => [ - 'label' => 'Auth.email', - 'rules' => [ - 'required', - 'max_length[254]', - 'valid_email', - 'is_unique[auth_identities.secret]', - ], - ], - 'password' => [ - 'label' => 'Auth.password', - 'rules' => 'required|strong_password', - ], - 'password_confirm' => [ - 'label' => 'Auth.passwordConfirm', - 'rules' => 'required|matches[password]', - ], - ]; -``` - -> **Note** If you customize the table names, set the correct table names in the -> rules. - -### Login - -Similar to the process for validation rules in the **Registration** section, you can add rules for the login form to **app/Config/Validation.php** and change the rules. - -```php - //-------------------------------------------------------------------- - // Rules For Login - //-------------------------------------------------------------------- - public $login = [ - // 'username' => [ - // 'label' => 'Auth.username', - // 'rules' => 'required|max_length[30]|min_length[3]|regex_match[/\A[a-zA-Z0-9\.]+\z/]', - // ], - 'email' => [ - 'label' => 'Auth.email', - 'rules' => 'required|max_length[254]|valid_email', - ], - 'password' => [ - 'label' => 'Auth.password', - 'rules' => 'required', - ], - ]; -``` - -## Custom User Provider - -If you want to customize user attributes, you need to create your own -[User Provider](./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 -command in the terminal: - -```console -php spark shield:model UserModel -``` - -The class name is optional. If none is provided, the generated class name would be `UserModel`. - -After creating the class, set the `$userProvider` property in **app/Config/Auth.php** as follows: - -```php -public string $userProvider = \App\Models\UserModel::class; -``` - -## Custom Login Identifier - -If your application has a need to use something other than `email` or `username`, you may specify any valid column within the `users` table that you may have added. This allows you to easily use phone numbers, employee or school IDs, etc as the user identifier. You must implement the following steps to set this up: - -This only works with the Session authenticator. - -1. Create a [migration](http://codeigniter.com/user_guide/dbmgmt/migration.html) that adds a new column to the `users` table. -2. Edit `app/Config/Auth.php` so that the new column you just created is within the `$validFields` array. - - ```php - public array $validFields = [ - 'employee_id' - ]; - ``` - - If you have multiple login forms on your site that use different credentials, you must have all of the valid identifying fields in the array. - - ```php - public array $validFields = [ - 'email', - 'employee_id' - ]; - ``` - > **Warning** - > It is very important for security that if you add a new column for identifier you must write a new **Validation Rules** and then set it using the [custom-validation-rules](https://github.com/codeigniter4/shield/blob/develop/docs/customization.md#custom-validation-rules) description. - -3. Edit the login form to change the name of the default `email` input to the new field name. - - ```php - -
- -
- ``` diff --git a/docs/customization/extending_controllers.md b/docs/customization/extending_controllers.md new file mode 100644 index 000000000..ea03a54ee --- /dev/null +++ b/docs/customization/extending_controllers.md @@ -0,0 +1,31 @@ +# Extending the Controllers + +Shield has the following controllers that can be extended to handle +various parts of the authentication process: + +- **ActionController** handles the after-login and after-registration actions, like Two Factor Authentication and Email Verification. +- **LoginController** handles the login process. +- **RegisterController** handles the registration process. Overriding this class allows you to customize the User Provider, the User Entity, and the validation rules. +- **MagicLinkController** handles the "lost password" process that allows a user to login with a link sent to their email. This allows you to + override the message that is displayed to a user to describe what is happening, if you'd like to provide more information than simply swapping out the view used. + +It is not recommended to copy the entire controller into **app/Controllers** and change its namespace. Instead, you should create a new controller that extends +the existing controller and then only override the methods needed. This allows the other methods to stay up to date with any security +updates that might happen in the controllers. + +```php +themedView($view, $data, $options); + } +} +``` diff --git a/docs/customization/login_identifier.md b/docs/customization/login_identifier.md new file mode 100644 index 000000000..ea96993a4 --- /dev/null +++ b/docs/customization/login_identifier.md @@ -0,0 +1,34 @@ +# Customizing Login Identifier + +If your application has a need to use something other than `email` or `username`, you may specify any valid column within the `users` table that you may have added. This allows you to easily use phone numbers, employee or school IDs, etc as the user identifier. You must implement the following steps to set this up: + +This only works with the Session authenticator. + +1. Create a [migration](http://codeigniter.com/user_guide/dbmgmt/migration.html) that adds a new column to the `users` table. +2. Edit `app/Config/Auth.php` so that the new column you just created is within the `$validFields` array. + + ```php + public array $validFields = [ + 'employee_id' + ]; + ``` + + If you have multiple login forms on your site that use different credentials, you must have all of the valid identifying fields in the array. + + ```php + public array $validFields = [ + 'email', + 'employee_id' + ]; + ``` + > **Warning** + > It is very important for security that if you add a new column for identifier you must write a new **Validation Rules** and then set it using the [custom-validation-rules](https://github.com/codeigniter4/shield/blob/develop/docs/customization.md#custom-validation-rules) description. + +3. Edit the login form to change the name of the default `email` input to the new field name. + + ```php + +
+ +
+ ``` diff --git a/docs/customization/redirect_urls.md b/docs/customization/redirect_urls.md new file mode 100644 index 000000000..5ecf6834b --- /dev/null +++ b/docs/customization/redirect_urls.md @@ -0,0 +1,60 @@ +# Customizing Redirect URLs + +## Customize Login Redirect + +You can customize where a user is redirected to on login with the `loginRedirect()` method of the **app/Config/Auth.php** config file. This is handy if you want to redirect based on user group or other criteria. + +```php +public function loginRedirect(): string +{ + $url = auth()->user()->inGroup('admin') + ? '/admin' + : setting('Auth.redirects')['login']; + + return $this->getUrl($url); +} +``` + +Oftentimes, you will want to have different redirects for different user groups. A simple example +might be that you want admins redirected to `/admin` while all other groups redirect to `/`. +The **app/Config/Auth.php** config file also includes methods that you can add additional logic to in order to +achieve this: + +```php +public function loginRedirect(): string +{ + if (auth()->user()->can('admin.access')) { + return '/admin'; + } + + $url = setting('Auth.redirects')['login']; + + return $this->getUrl($url); +} +``` + +## Customize Register Redirect + +You can customize where a user is redirected to after registration in the `registerRedirect()` method of the **app/Config/Auth.php** config file. + +```php +public function registerRedirect(): string +{ + $url = setting('Auth.redirects')['register']; + + return $this->getUrl($url); +} +``` + +## Customize Logout Redirect + +The logout redirect can also be overridden by the `logoutRedirect()` method of the **app/Config/Auth.php** config file. This will not be used as often as login and register, but you might find the need. For example, if you programatically logged a user out you might want to take them to a page that specifies why they were logged out. Otherwise, you might take them to the home page or even the login page. + +```php +public function logoutRedirect(): string +{ + $url = setting('Auth.redirects')['logout']; + + return $this->getUrl($url); +} +``` diff --git a/docs/customization/route_config.md b/docs/customization/route_config.md new file mode 100644 index 000000000..729383280 --- /dev/null +++ b/docs/customization/route_config.md @@ -0,0 +1,14 @@ +# Customizing Route Configuration + +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: + +```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'); +``` diff --git a/docs/customization/table_names.md b/docs/customization/table_names.md new file mode 100644 index 000000000..2fcaad8c7 --- /dev/null +++ b/docs/customization/table_names.md @@ -0,0 +1,20 @@ +# Customizing Table Names + +If you want to change the default table names, you can change the table names +in **app/Config/Auth.php**. + +```php +public array $tables = [ + 'users' => 'users', + 'identities' => 'auth_identities', + 'logins' => 'auth_logins', + 'token_logins' => 'auth_token_logins', + 'remember_tokens' => 'auth_remember_tokens', + 'groups_users' => 'auth_groups_users', + 'permissions_users' => 'auth_permissions_users', +]; +``` + +Set the table names that you want in the array values. + +> **Note** You must change the table names before running database migrations. diff --git a/docs/customization/user_provider.md b/docs/customization/user_provider.md new file mode 100644 index 000000000..f55ac2cd4 --- /dev/null +++ b/docs/customization/user_provider.md @@ -0,0 +1,20 @@ +# Customizing User Provider + +If you want to customize user attributes, you need to create your own +[User Provider](./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 +command in the terminal: + +```console +php spark shield:model UserModel +``` + +The class name is optional. If none is provided, the generated class name would be `UserModel`. + +After creating the class, set the `$userProvider` property in **app/Config/Auth.php** as follows: + +```php +public string $userProvider = \App\Models\UserModel::class; +``` diff --git a/docs/customization/validation_rules.md b/docs/customization/validation_rules.md new file mode 100644 index 000000000..f0442ff72 --- /dev/null +++ b/docs/customization/validation_rules.md @@ -0,0 +1,106 @@ +# Customizing Validation Rules + +## Registration + +Shield has the following rules for registration: + +```php +[ + 'username' => [ + 'label' => 'Auth.username', + 'rules' => [ + 'required', + 'max_length[30]', + 'min_length[3]', + 'regex_match[/\A[a-zA-Z0-9\.]+\z/]', + 'is_unique[users.username]', + ], + ], + 'email' => [ + 'label' => 'Auth.email', + 'rules' => [ + 'required', + 'max_length[254]', + 'valid_email', + 'is_unique[auth_identities.secret]', + ], + ], + 'password' => [ + 'label' => 'Auth.password', + 'rules' => 'required|strong_password', + ], + 'password_confirm' => [ + 'label' => 'Auth.passwordConfirm', + 'rules' => 'required|matches[password]', + ], +]; +``` + +> **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()`. + +If you need a different set of rules for registration, you can specify them in your `Validation` configuration (**app/Config/Validation.php**) like: + +```php + //-------------------------------------------------------------------- + // Rules For Registration + //-------------------------------------------------------------------- + public $registration = [ + 'username' => [ + 'label' => 'Auth.username', + 'rules' => [ + 'required', + 'max_length[30]', + 'min_length[3]', + 'regex_match[/\A[a-zA-Z0-9\.]+\z/]', + 'is_unique[users.username]', + ], + ], + 'email' => [ + 'label' => 'Auth.email', + 'rules' => [ + 'required', + 'max_length[254]', + 'valid_email', + 'is_unique[auth_identities.secret]', + ], + ], + 'password' => [ + 'label' => 'Auth.password', + 'rules' => 'required|strong_password', + ], + 'password_confirm' => [ + 'label' => 'Auth.passwordConfirm', + 'rules' => 'required|matches[password]', + ], + ]; +``` + +> **Note** If you customize the table names, set the correct table names in the +> rules. + +## Login + +Similar to the process for validation rules in the **Registration** section, you can add rules for the login form to **app/Config/Validation.php** and change the rules. + +```php + //-------------------------------------------------------------------- + // Rules For Login + //-------------------------------------------------------------------- + public $login = [ + // 'username' => [ + // 'label' => 'Auth.username', + // 'rules' => 'required|max_length[30]|min_length[3]|regex_match[/\A[a-zA-Z0-9\.]+\z/]', + // ], + 'email' => [ + 'label' => 'Auth.email', + 'rules' => 'required|max_length[254]|valid_email', + ], + 'password' => [ + 'label' => 'Auth.password', + 'rules' => 'required', + ], + ]; +``` diff --git a/mkdocs.yml b/mkdocs.yml index 5c63132ce..f18ca9d7c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,7 +53,14 @@ nav: - Testing: testing.md - session_auth_event_and_logging.md - Customization: - - customization.md + - 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/login_identifier.md - Guides: - guides/forcing_password_reset.md - guides/banning_users.md From f5be15954cfd74fd6b4c012d71b78a87a25fa202 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 17:29:13 +0900 Subject: [PATCH 15/18] docs: update links --- docs/concepts.md | 2 +- docs/customization/login_identifier.md | 2 +- docs/customization/user_provider.md | 2 +- docs/guides/strengthen_password.md | 2 +- docs/install.md | 4 ++-- docs/quick_start_guide/authentication_flow.md | 6 +++--- docs/quick_start_guide/managing_users.md | 2 +- 7 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index dc1b17452..c5f6c3f65 100644 --- a/docs/concepts.md +++ b/docs/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 Shield](./customization.md#custom-user-provider) 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/customization/login_identifier.md b/docs/customization/login_identifier.md index ea96993a4..2239d3ad8 100644 --- a/docs/customization/login_identifier.md +++ b/docs/customization/login_identifier.md @@ -22,7 +22,7 @@ This only works with the Session authenticator. ]; ``` > **Warning** - > It is very important for security that if you add a new column for identifier you must write a new **Validation Rules** and then set it using the [custom-validation-rules](https://github.com/codeigniter4/shield/blob/develop/docs/customization.md#custom-validation-rules) description. + > It is very important for security that if you add a new column for identifier, you must write a new **Validation Rules** and then set it using the [Customizing Validation Rules](./validation_rules.md) description. 3. Edit the login form to change the name of the default `email` input to the new field name. diff --git a/docs/customization/user_provider.md b/docs/customization/user_provider.md index f55ac2cd4..36af8d838 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](../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/guides/strengthen_password.md b/docs/guides/strengthen_password.md index 102dc9b1d..6fad8ea5c 100644 --- a/docs/guides/strengthen_password.md +++ b/docs/guides/strengthen_password.md @@ -107,7 +107,7 @@ By default, Shield has the validation rules for maximum password length. - 72 bytes for PASSWORD_BCRYPT - 255 characters for others -You can customize the validation rule. See [Customizing Shield](../customization.md). +You can customize the validation rule. See [Customizing Validation Rules](../customization/validation_rules.md). ## $supportOldDangerousPassword diff --git a/docs/install.md b/docs/install.md index ecf9ab3a3..47aad61b0 100644 --- a/docs/install.md +++ b/docs/install.md @@ -63,7 +63,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 Shield](./customization.md#custom-table-names). + > 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). @@ -140,7 +140,7 @@ your project. > **Note** If you want to customize table names, you must change the table names > before running database migrations. - > See [Customizing Shield](./customization.md#custom-table-names). + > See [Customizing Table Names](./customization/table_names.md). ```console php spark migrate --all diff --git a/docs/quick_start_guide/authentication_flow.md b/docs/quick_start_guide/authentication_flow.md index 7827d0ab9..428e14703 100644 --- a/docs/quick_start_guide/authentication_flow.md +++ b/docs/quick_start_guide/authentication_flow.md @@ -49,7 +49,7 @@ public int $unusedTokenLifetime = YEAR; ### 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](../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. @@ -63,7 +63,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](../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. @@ -77,7 +77,7 @@ public array $actions = [ ## 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/quick_start_guide/managing_users.md b/docs/quick_start_guide/managing_users.md index e963a3b34..84c57815b 100644 --- a/docs/quick_start_guide/managing_users.md +++ b/docs/quick_start_guide/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](../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 From d19c6e3a118ab9fbf99da00e05461cec7997c59f Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 21:18:23 +0900 Subject: [PATCH 16/18] docs: fix invalid markdown --- docs/quick_start_guide/authentication_flow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/quick_start_guide/authentication_flow.md b/docs/quick_start_guide/authentication_flow.md index 428e14703..40de6e511 100644 --- a/docs/quick_start_guide/authentication_flow.md +++ b/docs/quick_start_guide/authentication_flow.md @@ -9,10 +9,10 @@ Learning any new authentication system can be difficult, especially as they get ### Configure Redirect URLs -If you need everyone to redirect to a single URL after login/logout/register actions, you can modify the `Config\Auth::$redirects` array in **app/Config/Auth.php**`** to specify the url to redirect to. +If you need everyone to redirect to a single URL after login/logout/register actions, you can modify the `Config\Auth::$redirects` array in **app/Config/Auth.php** to specify the url to redirect to. By default, a successful login or register attempt will all redirect to `/`, while a logout action -will redirect to a [named route](https://codeigniter.com/user_guide/incoming/routing.html#using-named-routes "See routing docs") `login` or a *URI path* `/login`. You can change the default URLs used within the **`**app/Config/Auth.php** config file: +will redirect to a [named route](https://codeigniter.com/user_guide/incoming/routing.html#using-named-routes "See routing docs") `login` or a *URI path* `/login`. You can change the default URLs used within the **app/Config/Auth.php** config file: ```php public array $redirects = [ From 33a4c582f24a367da6d33170884da4c3f0f0e4d6 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 21:18:40 +0900 Subject: [PATCH 17/18] docs: replace handler with authenticator --- docs/quick_start_guide/authentication_flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quick_start_guide/authentication_flow.md b/docs/quick_start_guide/authentication_flow.md index 40de6e511..d22383f38 100644 --- a/docs/quick_start_guide/authentication_flow.md +++ b/docs/quick_start_guide/authentication_flow.md @@ -27,7 +27,7 @@ public array $redirects = [ ### Configure Remember-me Functionality -Remember-me functionality is enabled by default for the `Session` handler. 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 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. ```php public array $sessionConfig = [ From 811505450863c1a316711c8d59649ca55ce4af7f Mon Sep 17 00:00:00 2001 From: kenjis Date: Sun, 17 Sep 2023 21:23:06 +0900 Subject: [PATCH 18/18] docs: add "official" --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 3384d3360..81a746ebc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ ## What is Shield? -Shield is an authentication and authorization framework for CodeIgniter 4. While +Shield is the official authentication and authorization framework for CodeIgniter 4. While it does provide a base set of tools that are commonly used in websites, it is designed to be flexible and easily customizable.