You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/0 - install.md
+5-53Lines changed: 5 additions & 53 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,7 @@
1
1
# Installation
2
2
3
+
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.
4
+
3
5
Installation is done through [Composer](https://getcomposer.org). The example assumes you have it installed globally.
4
6
If you have it installed as a phar, or othewise you will need to adjust the way you call composer itself.
5
7
@@ -75,11 +77,12 @@ public $ruleSets = [
75
77
76
78
## Controller Filters
77
79
78
-
Shield provides 3 [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can
80
+
Shield provides 4 [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can
79
81
use to protect your routes, `session`, `tokens`, and `chained`. The first two cover the `Session` and
80
82
`AccessTokens` authenticators, respectively. The `chained` filter will check both authenticators in sequence
81
83
to see if the user is logged in through either of authenticators, allowing a single API endpoint to
82
-
work for both an SPA using session auth, and a mobile app using access tokens.
84
+
work for both an SPA using session auth, and a mobile app using access tokens. The fourth, `auth-rates`,
85
+
provides a good basis for rate limiting of auth-related routes.
83
86
84
87
These filters are already loaded for you by the registrar class located at `src/Config/Registrar.php`.
85
88
@@ -110,54 +113,3 @@ public $filters = [
110
113
]
111
114
];
112
115
```
113
-
114
-
## Further Customization
115
-
116
-
### Route Configuration
117
-
118
-
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:
Shield has the following controllers that can be extended to handle
134
-
various parts of the authentication process:
135
-
136
-
- **ActionController** handles the after login and after-registration actions that can be ran, like Two Factor Authentication and Email Verification.
137
-
138
-
- **LoginController** handles the login process.
139
-
140
-
- **RegisterController** handles the registration process. Overriding this class allows you to customize the User Provider, the User Entity, and the validation rules.
141
-
142
-
- **MagicLinkController** handles the "lost password" process that allows a user to login with a link sent to their email. Allows you to
143
-
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.
144
-
145
-
It is not recommended to copy the entire controller into app and change it's namespace. Instead, you should create a new controller that extends
146
-
the existing controller and then only override the methods needed. This allows the other methods to always stay up to date with any security
147
-
updates that might happen in the controllers.
148
-
149
-
```php
150
-
<?php
151
-
152
-
namespace App\Controllers;
153
-
154
-
use CodeIgniter\Shield\Controllers\LoginController as ShieldLogin;
Copy file name to clipboardExpand all lines: docs/1 - concepts.md
+24-15Lines changed: 24 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,38 +4,47 @@ This document covers some of the base concepts used throughout the library.
4
4
5
5
## Repository State
6
6
7
-
Shield is designed so that the initial setup of your application can all happen in code with nothing required to be saved in the database. This means you do not have to create large seeder files that need
8
-
to run within each environment. Instead, it can be placed under version control, though the Settings library allows those settings to be easily
9
-
stored in the database if you create an interface for the user to update those settings at.
7
+
Shield is designed so that the initial setup of your application can all happen in code with nothing required to be
8
+
saved in the database. This means you do not have to create large seeder files that need to run within each environment.
9
+
Instead, it can be placed under version control, though the Settings library allows those settings to be easily stored
10
+
in the database if you create an interface for the user to update those settings.
10
11
11
12
## Settings
12
13
13
-
In place of the CodeIgniter `config()` helper, Shield uses the official
14
-
[Settings](https://github.com/codeigniter4/settings) library. This provides a way to save any Config class values to the database if you want to modify them, but falls back on the standard Config class if nothing is found in the database.
14
+
In place of the CodeIgniter `config()` helper, Shield uses the official [Settings](https://github.com/codeigniter4/settings)
15
+
library. This provides a way to save any Config class values to the database if you want to modify them, but falls back
16
+
on the standard Config class if nothing is found in the database.
15
17
16
18
## User Providers
17
19
18
-
To make the system as flexible as possible, you can define which class should be able to interact with your chosen persistence system to get the user records. Typically this is going to be a Model, and one is provided for you, at `CodeIgniter\Shield\Models\UserModel`. This is defined in `Config\Auth->userProvider`.
20
+
You can use your own models to handle user persistence. Shield calls this the "User Provider" class. A default model
21
+
is provided for you at `CodeIgniter\Shield\Models\UserModel`. You can change this in the `Config\Auth->userProvider` setting.
22
+
The only requirement is that your new class MUST extend the provided `UserModel`.
19
23
20
24
```php
21
25
public $userProvider = 'CodeIgniter\Shield\Models\UserModel';
22
26
```
23
27
24
28
## User Identities
25
29
26
-
User accounts are stored separately from the information needed to identify that user. These identifying pieces of data we call User Identities. By default, the library has two types of identities: one for standard email/password information, and one for access tokens.
30
+
User accounts are stored separately from the information needed to identify that user. These identifying pieces of data are
31
+
called User Identities. By default, the library has two types of identities: one for standard email/password information,
32
+
and one for access tokens.
27
33
28
-
By keeping the identity information loosely coupled from the user account itself, it frees the system up to more easily integrate third-party sign-in systems, JWT systems, and more, all on a single user. With small overrides you could even allow a single user to have multiple email/password combinations if your needs demands the functionality.
34
+
Keeping these identities loosely coupled from the user account itself facilitates integrations with third-party sign-in systems, JWT systems, and more - all on a single user.
29
35
30
-
While this has the potential to make the system more complex, the `email` and `password` fields are automatically looked up for you when attempting to access from the User entity. Caution should be used to craft queries that will pull in the `email` field when you need to display it to the user, as you could easily run into some n+1 slow queries otherwise.
36
+
While this has the potential to make the system more complex, the `email` and `password` fields are automatically
37
+
looked up for you when attempting to access them from the User entity. Caution should be used to craft queries that will pull
38
+
in the `email` field when you need to display it to the user, as you could easily run into some n+1 slow queries otherwise.
31
39
32
-
When you `save($user)` a `User` instance in the `UserModel`, the email/password identity will automatically be updated. If no email/password identity exists, you must
33
-
pass both the email and the password to the User instance prior to calling `save()`.
40
+
When you `save($user)` a `User` instance in the `UserModel`, the email/password identity will automatically be updated.
41
+
If no email/password identity exists, you must pass both the email and the password to the User instance prior to calling `save()`.
34
42
35
43
## Password Validators
36
44
37
-
When registering a user account, the user's password must be validated to ensure it matches the security requirements of your application. To make the system as flexible as possible Shield uses a pipeline of
38
-
Validators to handle the validation. This allows you turn on or off any validation systems that are appropriate for your application. The following Validators are available:
45
+
When registering a user account, the user's password must be validated to ensure it matches the security requirements of
46
+
your application. Shield uses a pipeline of Validators to handle the validation. This allows you turn on or off any validation
47
+
systems that are appropriate for your application. The following Validators are available:
39
48
40
49
-**CompositionValidator** validates the makeup of the password itself. This used to include things
41
50
like ensuring it contained a symbol, a number, etc. According to the current
@@ -50,11 +59,11 @@ Validators to handle the validation. This allows you turn on or off any validati
50
59
`Config\Auth->maxSimilarity`. The default value is 50, but see the docblock in the config
51
60
file for more details. This is enabled by default.
52
61
-**DictionaryValidator** will compare the password against a provided file with about 600,000
53
-
frequently used passwords as has been seen in various data dumps over the years. If the
62
+
frequently used passwords that have been seen in various data dumps over the years. If the
54
63
chosen password matches any found in the file, it will be rejected. This is enabled by default.
55
64
-**PwnedValidator** is like the `DictionaryValidator`. Instead of comparing to a local file, it
56
65
uses a third-party site, [Have I Been Pwned](https://haveibeenpwned.com/Passwords) to check
57
-
against a list of over 500 million leaked passwords from many data dumps across the web.
66
+
against a list of over 630 million leaked passwords from many data dumps across the web.
58
67
The search is done securely, and provides more information than the simple dictionary version.
59
68
However, this does require an API call to a third-party which not every application will
60
69
find acceptable. You should use either this validator or the `DictionaryValidator`, not both.
0 commit comments