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
By default, a successful login or register attempt will all redirect to `/`, while a logout action
30
-
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 `Auth` config file:
32
+
### Customize Login Redirect
33
+
34
+
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.
31
35
32
36
```php
33
-
public array $redirects = [
34
-
'register' => '/',
35
-
'login' => '/',
36
-
'logout' => 'login',
37
-
];
37
+
public function loginRedirect(): string
38
+
{
39
+
$url = auth()->user()->inGroup('admin')
40
+
? '/admin'
41
+
: setting('Auth.redirects')['login'];
42
+
43
+
return $this->getUrl($url);
44
+
}
38
45
```
39
46
40
47
Oftentimes, you will want to have different redirects for different user groups. A simple example
41
48
might be that you want admins redirected to `/admin` while all other groups redirect to `/`.
42
-
The `Auth` config file also includes methods that you can add additional logic to in order to
49
+
The **app/Config/Auth.php** config file also includes methods that you can add additional logic to in order to
43
50
achieve this:
44
51
45
52
```php
@@ -55,6 +62,32 @@ public function loginRedirect(): string
55
62
}
56
63
```
57
64
65
+
### Customize Register Redirect
66
+
67
+
You can customize where a user is redirected to after registration in the `registerRedirect()` method of the **app/Config/Auth.php** config file.
68
+
69
+
```php
70
+
public function registerRedirect(): string
71
+
{
72
+
$url = setting('Auth.redirects')['register'];
73
+
74
+
return $this->getUrl($url);
75
+
}
76
+
```
77
+
78
+
### Customize Logout Redirect
79
+
80
+
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.
81
+
82
+
```php
83
+
public function logoutRedirect(): string
84
+
{
85
+
$url = setting('Auth.redirects')['logout'];
86
+
87
+
return $this->getUrl($url);
88
+
}
89
+
```
90
+
58
91
## Extending the Controllers
59
92
60
93
Shield has the following controllers that can be extended to handle
Copy file name to clipboardExpand all lines: docs/quickstart.md
+50-82Lines changed: 50 additions & 82 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,38 +2,45 @@
2
2
3
3
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.
4
4
5
-
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.
5
+
> **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.
-[Change Available Groups](#change-available-groups)
21
+
-[Set the Default Group](#set-the-default-group)
22
+
-[Change Available Permissions](#change-available-permissions)
23
+
-[Assign Permissions to a Group](#assign-permissions-to-a-group)
24
+
-[Assign Permissions to a User](#assign-permissions-to-a-user)
25
25
-[Check If a User Has Permission](#check-if-a-user-has-permission)
26
-
-[Adding A Group To A User](#adding-a-group-to-a-user)
27
-
-[Removing A Group From A User](#removing-a-group-from-a-user)
28
-
-[Checking If User Belongs To A Group](#checking-if-user-belongs-to-a-group)
26
+
-[Adding a Group To a User](#adding-a-group-to-a-user)
27
+
-[Removing a Group From a User](#removing-a-group-from-a-user)
28
+
-[Checking If User Belongs To a Group](#checking-if-user-belongs-to-a-group)
29
29
-[Managing Users](#managing-users)
30
30
-[Creating Users](#creating-users)
31
31
-[Deleting Users](#deleting-users)
32
-
-[Editing A User](#editing-a-user)
32
+
-[Editing a User](#editing-a-user)
33
33
34
34
## Authentication Flow
35
35
36
-
If you need everyone to redirect to a single URL after login/logout/register actions, you can modify the `Config\Auth::redirects` array to specify the url to redirect to.
36
+
### Configure Config\Auth
37
+
38
+
#### Configure Redirect URLs
39
+
40
+
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.
41
+
42
+
By default, a successful login or register attempt will all redirect to `/`, while a logout action
43
+
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:
37
44
38
45
```php
39
46
public array $redirects = [
@@ -43,50 +50,9 @@ public array $redirects = [
43
50
];
44
51
```
45
52
46
-
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.
47
-
48
-
### Customize register redirect
49
-
50
-
You can customize where a user is redirected to after registration in the `registerRedirect` method of the `Auth` config file.
51
-
52
-
```php
53
-
public function registerRedirect(): string
54
-
{
55
-
$url = setting('Auth.redirects')['register'];
53
+
> **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.
56
54
57
-
return $this->getUrl($url);
58
-
}
59
-
```
60
-
61
-
### Customize login redirect
62
-
63
-
You can further customize where a user is redirected to on login with the `loginRedirect` method of the `Auth` config file. This is handy if you want to redirect based on user group or other criteria.
64
-
65
-
```php
66
-
public function loginRedirect(): string
67
-
{
68
-
$url = auth()->user()->inGroup('admin')
69
-
? '/admin'
70
-
: setting('Auth.redirects')['login'];
71
-
72
-
return $this->getUrl($url);
73
-
}
74
-
```
75
-
76
-
### Customize logout redirect
77
-
78
-
The logout redirect can also be overridden by the `logoutRedirect` method of the `Auth` 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.
79
-
80
-
```php
81
-
public function logoutRedirect(): string
82
-
{
83
-
$url = setting('Auth.redirects')['logout'];
84
-
85
-
return $this->getUrl($url);
86
-
}
87
-
```
88
-
89
-
### Customize Remember-me functionality
55
+
#### Configure Remember-me Functionality
90
56
91
57
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.
92
58
@@ -99,17 +65,17 @@ public array $sessionConfig = [
99
65
];
100
66
```
101
67
102
-
### Change Access Token Lifetime
68
+
####Change Access Token Lifetime
103
69
104
70
By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the `Auth` config file.
105
71
106
72
```php
107
73
public int $unusedTokenLifetime = YEAR;
108
74
```
109
75
110
-
### Enable Account Activation via Email
76
+
####Enable Account Activation via Email
111
77
112
-
> **Note** You need to configure `app/Config/Email.php` to allow Shield to send emails. See [Installation](install.md#initial-setup).
78
+
> **Note** You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](install.md#initial-setup).
113
79
114
80
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.
115
81
@@ -120,9 +86,9 @@ public array $actions = [
120
86
];
121
87
```
122
88
123
-
### Enable Two-Factor Authentication
89
+
####Enable Two-Factor Authentication
124
90
125
-
> **Note** You need to configure `app/Config/Email.php` to allow Shield to send emails. See [Installation](install.md#initial-setup).
91
+
> **Note** You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](install.md#initial-setup).
126
92
127
93
Turned off by default, Shield's Email-based 2FA can be enabled by specifying the class to use in the `Auth` config file.
128
94
@@ -135,7 +101,7 @@ public array $actions = [
135
101
136
102
### Responding to Magic Link Logins
137
103
138
-
> **Note** You need to configure `app/Config/Email.php` to allow Shield to send emails. See [Installation](install.md#initial-setup).
104
+
> **Note** You need to configure **app/Config/Email.php** to allow Shield to send emails. See [Installation](install.md#initial-setup).
139
105
140
106
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.
141
107
@@ -168,9 +134,11 @@ Events::on('magicLogin', static function () {
168
134
169
135
## Authorization Flow
170
136
171
-
### Change Available Groups
137
+
### Configure Config\AuthGroups
138
+
139
+
#### Change Available Groups
172
140
173
-
The available groups are defined in the `AuthGroups` config file, under the `$groups` property. Add new entries to the array, or remove existing ones to make them available throughout your application.
141
+
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.
174
142
175
143
```php
176
144
public array $groups = [
@@ -182,11 +150,11 @@ public array $groups = [
182
150
];
183
151
```
184
152
185
-
### Set the Default Group
153
+
####Set the Default Group
186
154
187
155
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.
188
156
189
-
### Change Available Permissions
157
+
####Change Available Permissions
190
158
191
159
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.
192
160
@@ -202,7 +170,7 @@ public array $permissions = [
202
170
];
203
171
```
204
172
205
-
### Assign Permissions to a Group
173
+
####Assign Permissions to a Group
206
174
207
175
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.
208
176
@@ -217,7 +185,7 @@ public array $matrix = [
217
185
];
218
186
```
219
187
220
-
### Assign Permissions to a User
188
+
####Assign Permissions to a User
221
189
222
190
Permissions can also be assigned directly to a user, regardless of what groups they belong to. This is done programatically on the `User` Entity.
223
191
@@ -245,11 +213,11 @@ if (! auth()->user()->can('users.create')) {
245
213
}
246
214
```
247
215
248
-
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.
216
+
> **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.
249
217
250
-
### Adding A Group To A User
218
+
### Adding a Group To a User
251
219
252
-
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.
220
+
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.
253
221
254
222
```php
255
223
$user = auth()->user();
@@ -263,18 +231,18 @@ $user = auth()->user();
263
231
$user->syncGroups('admin', 'beta');
264
232
```
265
233
266
-
### Removing A Group From A User
234
+
### Removing a Group From a User
267
235
268
-
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.
236
+
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.
269
237
270
238
```php
271
239
$user = auth()->user();
272
240
$user->removeGroup('admin', 'beta');
273
241
```
274
242
275
-
### Checking If User Belongs To A Group
243
+
### Checking If User Belongs To a Group
276
244
277
-
You can check if a user belongs to a group with the `inGroup` method.
245
+
You can check if a user belongs to a group with the `inGroup()` method.
278
246
279
247
```php
280
248
$user = auth()->user();
@@ -327,9 +295,9 @@ $users = model('UserModel');
327
295
$users->delete($user->id, true);
328
296
```
329
297
330
-
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.
298
+
> **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.
331
299
332
-
### Editing A User
300
+
### Editing a User
333
301
334
302
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.
0 commit comments