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.
- Quick Start Guide
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.
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.
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.
public function loginRedirect(): string
{
$url = auth()->user()->inGroup('admin')
? '/admin'
: setting('Auth.redirects')['login'];
return $this->getUrl($url);
}You can customize where a user is redirected to after registration in the registerRedirect method of the Auth config file.
public function registerRedirect(): string
{
$url = setting('Auth.redirects')['register'];
return $this->getUrl($url);
}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.
public function logoutRedirect(): string
{
$url = setting('Auth.redirects')['logout'];
return $this->getUrl($url);
}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.
public array $sessionConfig = [
'field' => 'user',
'allowRemembering' => true,
'rememberCookieName' => 'remember',
'rememberLength' => 30 * DAY,
];By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the Auth config file.
public int $unusedTokenLifetime = YEAR;Turned off by default, Shield's Email-based 2FA can be enabled by specifying the class to use in the Auth config file.
public array $actions = [
'login' => \CodeIgniter\Shield\Authentication\Actions\Email2FA,
'register' => null,
];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.
public array $actions = [
'login' => null,
'register' => \CodeIgniter\Shield\Authentication\Actions\EmailActivator,
];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.
public array $groups = [
'superadmin' => [
'title' => 'Super Admin',
'description' => 'Complete control of the site.',
],
//
];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.
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.
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',
];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.
public array $matrix = [
'superadmin' => [
'admin.*',
'users.*',
'beta.access',
],
//
];Permissions can also be assigned directly to a user, regardless of what groups they belong to. This is done programatically on the User Entity.
$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.
$user = auth()->user();
$user->syncPermissions(['users.create', 'beta.access']);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.
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 if you want to apply it to multiple pages of your site.
Shield uses a more complex user setup than many other systems, separating 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, due to the User Identities, this quick overview should help you feel more confident when working with users on a day-to-day basis.
By default, the only values stored in a user 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.
$users = model('UserModel');
$user = new User([
'username' => 'foo-bar'
]);
$users->save($user);
// Get the updated user so we have the ID...
$user = $users->findById($users->getInsertID());
// Store the email/password identity for this user.
$user->createEmailIdentity($this->request->getPost(['email', 'password']));
// Add to default group
$users->addToDefaultGroup($user);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.
$users = model('UserModel');
$users->delete($user->id, true);NOTE: The User rows use soft deletes so they are not actually deleted from the database unless the second parameter is true, like above.
The UserModel::save() method has been modified to ensure that an email or password previously set on the User entity will be automatically updated in the correct UserIdentity record.
$users = model('UserModel');
$user = $users->findById(123);
$user->fill([
'username' => 'JoeSmith111',
'email' => 'joe.smith@example.com',
'password' => 'secret123'
]);
$users->save($user);If you prefer to use the update() method then you will have to update the user's appropriate UserIdentity manually.
$users = model('UserModel');
$user = $users->findById(123);
$user->fill([
'username' => 'JoeSmith111',
'email' => 'joe.smith@example.com',
'password' => 'secret123'
]);
// Saves the username field
$users->update($user);
// Updates the email and password
$user->saveEmailIdentity();