CodeIgniter Shield Documentation

CodeIgniter Shield is the official authentication and authorization framework for CodeIgniter 4. It provides a flexible, security-focused foundation that can be extended or overridden to meet specific application needs.

Supported Authentication Methods

• Session-based Authentication: Traditional ID/Password login with 'Remember-me' functionality.
• Stateless Authentication: Supports Access Token, HMAC SHA256 Token, or JWT (JSON Web Token).

Key Security and Access Control Features

• Two-Factor Authentication (2FA): Optional email-based 2FA after login.
• Email Verification: Optional verification during account registration.
• Magic Link Login: Allows users to log in via email if they forget their password.
• Access Control: Uses flexible Group-based Access Control (similar to Roles) and individual Permissions.

Extensibility and Integration

• User Management: Includes a ready-to-use User Entity and User Provider (UserModel).
• Settings: Integrates with the CodeIgniter settings library, allowing configuration to be stored in version control or updated in the database.
• Customization: Provides easily extendable controllers and views that can be swapped out for custom implementations.
• Auth Helper: A simple helper is provided for common authentication actions.

Shield supports several authentication strategies depending on your application's needs:

• Session-based: Traditional email/username and password authentication. Includes secure "remember-me" functionality and comes with controllers and views for registration, login, and password recovery. Ideal for standard web applications.
• Access Token: Stateless authentication where users can have multiple unique tokens (similar to GitHub tokens). Best for third-party API access or mobile applications.
• HMAC SHA256 Token: An advanced version of Access Token authentication. Instead of passing a secret key in the request, a shared secret is used to create a hash signature of the request body, increasing security.
• JSON Web Token (JWT): A compact, self-contained method for securely transmitting information as a JSON object, commonly used for web application authentication and authorization.

Shield uses a flexible RBAC system where users can belong to multiple groups. Groups act as roles (e.g., admin, user), and permissions can be assigned to these groups or directly to individual users.

To configure your authorization system, you must edit Config\AuthGroups to define:

1. Groups: The available roles.
2. Default Group: The group assigned to new registrants.
3. Permissions: The specific actions available in the system.
4. Matrix: The mapping of permissions to groups.

// Config\AuthGroups.php

public array $groups = [
    'superadmin' => [
        'title'       => 'Super Admin',
        'description' => 'Optional description of the group.',
    ],
];

public string $defaultGroup = 'user';

public array $permissions = [
    'admin.access'        => 'Can access the sites admin area',
    'users.create'        => 'Can create new non-admin users',
    'beta.access'         => 'Can access beta-level features'
];

public array $matrix = [
    'admin' => [
        'admin.access',
        'users.create',
        'beta.access'
    ],
];

A Gateway Action is a single custom action used to manage multiple possible verification methods (e.g., choosing between Email or SMS 2FA). Instead of registering multiple actions for login, you register one 'Gateway' action.

Implementation details:

1. Conditionality: The gateway can implement ConditionalActionInterface to check if the user has any supported identity (e.g., return $user->getIdentity('mfa_email') !== null || $user->getIdentity('mfa_sms') !== null;).
2. Lifecycle:
   • show(): Displays the available methods to the user.
   • handle(): Validates the user's choice, sends the challenge, and remembers the selected method.
   • verify(): Verifies the challenge.
3. Identity Type: The gateway must return a single action identity type via getType() (e.g., mfa_gateway). Do not create separate identities for each sub-method.
4. State: Use the extra value of the identity for the pending action message. Store internal gateway state (like the selected method) in other identity fields (like secret2) or application-owned tables.

Shield decouples user accounts from the data used to identify them through a concept called User Identities.

• User Account: The central entity representing a person.
• User Identity: A specific method of identification (e.g., email/password, access tokens, JWT).

This decoupling allows a single user to have multiple ways to sign in (e.g., both a standard password and a third-party OAuth provider).

Key Behaviors:

• The email and password fields are automatically accessible from the User entity.
• When calling $userModel->save($user), the email/password identity is automatically updated.
• Important: If no email/password identity exists yet, you must pass both the email and password to the User instance before calling save().

Caution: When querying users, ensure you pull in the email field to avoid N+1 query performance issues when displaying user information.