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 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);
}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);
}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;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 = [
'register' => \CodeIgniter\Shield\Authentication\Actions\EmailActivator::class,
'login' => null,
];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 = [
'register' => null,
'login' => \CodeIgniter\Shield\Authentication\Actions\Email2FA::class,
];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.
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.
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.
session()->removeTempdata('magicLogin');At the same time the above session variable is set, a magicLogin event 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.
Events::on('magicLogin', static function () {
// ...
});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.
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.
$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.
$user = auth()->user();
$user->syncGroups('admin', 'beta');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.
$user = auth()->user();
$user->removeGroup('admin', 'beta');You can check if a user belongs to a group with the inGroup method.
$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.
$user = auth()->user();
if ($user->inGroup('admin', 'beta')) {
// do something
}Since 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.
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.
use CodeIgniter\Shield\Entities\User;
$users = model('UserModel');
$user = new User([
'username' => 'foo-bar',
'email' => '[email protected]',
'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);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(), 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.
$users = model('UserModel');
$user = $users->findById(123);
$user->fill([
'username' => 'JoeSmith111',
'email' => '[email protected]',
'password' => 'secret123'
]);
$users->save($user);