CakePHP Authentication

https://github.com/cakephp/authentication
Admin
CakePHP Authentication is a PSR7 middleware authentication stack that provides a flexible framework...
Tokens:50,301
Snippets:418
Trust Score:9.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure multiple authentication setups in getAuthenticationService()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/middleware.md

Use this PHP example to configure different authentication setups based on the request path. It loads token authentication for /api paths and session/form authentication for other paths. The example shows how to inspect the request and return an AuthenticationService instance.

```php
public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $path = $request->getPath();

    $service = new AuthenticationService();
    if (str_starts_with($path, '/api')) {
        // Accept API tokens only
        $service->loadAuthenticator('Authentication.Token', [
            'identifier' => 'Authentication.Token',
        ]);

        return $service;
    }

    // Web authentication
    // Support sessions and form login.
    $service->loadAuthenticator('Authentication.Session');
    $service->loadAuthenticator('Authentication.Form', [
        'identifier' => 'Authentication.Password',
    ]);

    return $service;
}
```

--------------------------------

### Use login helper in an integration test

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/testing.md

Call the login() helper before making a request to simulate an authenticated user. This example tests a GET request to '/bookmarks/1' and asserts a successful response.

```php
public function testGet()
{
    $this->login();
    $this->get('/bookmarks/1');
    $this->assertResponseOk();
}
```

--------------------------------

### Install with Composer

Source: https://github.com/cakephp/authentication/blob/4.x/readme.md

Install the authentication plugin using Composer.

```bash
composer require cakephp/authentication
```

--------------------------------

### Install Authentication plugin via Composer

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

Run this command from the CakePHP project root directory to install the authentication plugin. Requires Composer.

```bash
php composer.phar require cakephp/authentication
```

--------------------------------

### Token-based authentication: get token and test request

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/testing.md

Simulate token-based authentication by fetching a valid token for a known user and setting the Authorization header. The test then makes a GET request to '/api/bookmarks' and asserts a successful response.

```php
protected function getToken(): string
{
    // Get a token for a known user
    $user = $this->fetchTable('Users')->get(1, contain: ['ApiTokens']);

    return $user->api_tokens[0]->token;
}

public function testGet()
{
    $token = $this->getToken();
    $this->configRequest([
        'headers' => ['Authorization' => 'Bearer ' . $token]
    ]);
    $this->get('/api/bookmarks');
    $this->assertResponseOk();
}
```

--------------------------------

### Get User Data with get()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/view-helper.md

Retrieves user data, such as the username, using the get() method.

```php
$username = $this->Identity->get('username');
```

--------------------------------

### Install authentication 3.0 via Composer

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-2-to-3.md

Run this command to require version 3.0 of the authentication plugin. Alternatively, manually edit composer.json and run 'composer update -W'.

```bash
composer require cakephp/authentication:^3.0 -W
```

--------------------------------

### Return different authentication services for API and web

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Return different authentication services based on the URL path or request attributes, such as using JWT for API and sessions for web. The example checks the 'prefix' parameter to include API-specific or web-specific authenticators.

```php
public function getAuthenticationService(
    ServerRequestInterface $request
): AuthenticationServiceInterface {
    $service = new AuthenticationService();

    // Configuration common to both the API and web goes here.

    if ($request->getParam('prefix') === 'Api') {
        // Include API specific authenticators
    } else {
        // Web UI specific authenticators.
    }

    return $service;
}
```

--------------------------------

### Check authentication result and handle success/failure

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Shows how to get the authentication result from the component or request object, check if valid, and log status and errors on failure.

```php
// Using Authentication component
$result = $this->Authentication->getResult();

// Using request object
$result = $request->getAttribute('authentication')->getResult();

if ($result->isValid()) {
    $user = $request->getAttribute('identity');
} else {
    $this->log($result->getStatus());
    $this->log($result->getErrors());
}
```

--------------------------------

### Access identity data with get()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identity-object.md

Use the get() method to access identity data. It is aware of field mapping, unlike array access, and is strongly recommended.

```php
$identity->get('email');
$identity->get('username');
```

--------------------------------

### JWKS endpoint setup in routes.php and JwksController

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Configures a route for /.well-known/jwks.json and implements a controller action that returns a JSON Web Key Set (JWKS) using the Firebase JWT library. Requires a public key file at CONFIG/jwt.pem.

```php
// config/routes.php
$builder->setExtensions('json');
$builder->connect('/.well-known/{controller}', [
    'action' => 'index',
], [
    'controller' => 'jwks',
    'pass' => [],
]); // connect /.well-known/jwks.json to JwksController

// controller/JwksController.php
use Firebase\JWT\JWT;

public function index()
{
    $pubKey = file_get_contents(CONFIG . 'jwt.pem');
    $res = openssl_pkey_get_public($pubKey);
    $detail = openssl_pkey_get_details($res);
    $key = [
        'kty' => 'RSA',
        'alg' => 'RS256',
        'use' => 'sig',
        'e' => JWT::urlsafeB64Encode($detail['rsa']['e']),
        'n' => JWT::urlsafeB64Encode($detail['rsa']['n']),
    ];
    $keys['keys'][] = $key;

    $this->viewBuilder()->setClassName('Json');
    $this->set(compact('keys'));
    $this->viewBuilder()->setOption('serialize', 'keys');
}
```

--------------------------------

### Basic/Digest authentication test

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/testing.md

Simulate Basic or Digest authentication by setting the PHP_AUTH_USER and PHP_AUTH_PW environment variables via configRequest. The test then makes a GET request to '/api/bookmarks' and asserts a successful response.

```php
public function testGet(): void
{
    $this->configRequest([
        'environment' => [
            'PHP_AUTH_USER' => 'username',
            'PHP_AUTH_PW' => 'password',
        ],
    ]);
    $this->get('/api/bookmarks');
    $this->assertResponseOk();
}
```

--------------------------------

### Get the Successful Identifier with getIdentificationProvider()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Retrieve the authentication service and call getIdentificationProvider() to get the identifier that identified the user. Returns null on authentication failure.

```php
// In a controller action
$service = $this->request->getAttribute('authentication');

// Will be null on authentication failure, or an identifier.
$identifier = $service->getIdentificationProvider();
```

--------------------------------

### Get the Successful Authenticator with getAuthenticationProvider()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Retrieve the authentication service from the request and call getAuthenticationProvider() to get the authenticator that succeeded. Returns null on authentication failure.

```php
// In a controller action
$service = $this->request->getAttribute('authentication');

// Will be null on authentication failure, or an authenticator.
$authenticator = $service->getAuthenticationProvider();
```

--------------------------------

### Configure EnvironmentAuthenticator with token identifier

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Configure the EnvironmentAuthenticator to authenticate users based on environment variables exposed by the webserver, such as those from Shibboleth or similar SAML 1.1 implementations. The example maps the USER_NAME environment variable to the username column using a token identifier.

```php
// Configure a token identifier that maps `USER_ID` to the
// username column
$identifier = [
    'className' => 'Authentication.Token',
    'tokenField' => 'username',
    'dataField' => 'USER_NAME',
];

$service->loadAuthenticator('Authentication.Environment', [
    'identifier' => $identifier,
    'loginUrl' => '/sso',
    'fields' => [
        // Choose which environment variables exposed by your
        // authentication provider are used to authenticate
        // in your application.
        'USER_NAME',
    ],
]);
```

--------------------------------

### Enable redirectValidation in AuthenticationService

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/redirect-validation.md

Configure the 'redirectValidation' option in the AuthenticationService to enable validation. The 'enabled' key must be set to true; it defaults to false for backward compatibility. This example is placed in the getAuthenticationService() method of src/Application.php.

```php
// In src/Application.php getAuthenticationService() method
$service = new AuthenticationService();
$service->setConfig([
    'unauthenticatedRedirect' => '/users/login',
    'queryParam' => 'redirect',
    'redirectValidation' => [
        'enabled' => true,  // Enable validation (default: false)
    ],
]);
```

--------------------------------

### Access identity data via property

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identity-object.md

Property access is also possible, but it is not field-map aware. This example shows direct property access to identity fields.

```text
$identity->email;
$identity->username;
```

--------------------------------

### Set identity with AuthenticationComponent::setIdentity()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Replaces AuthComponent::setUser() with setIdentity() to persist a user into the configured authenticators. The example reads a user by access token before persisting.

```php
// Assume you need to read a user by access token
$user = $this->Users->find('byToken', token: $token)->first();

// Persist the user into configured authenticators.
$this->Authentication->setIdentity($user);
```

--------------------------------

### Get authenticated user identity via component

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Retrieves the authenticated user identity data using the Authentication component.

```php
$user = $this->Authentication->getIdentity();
```

--------------------------------

### Configure unauthenticatedRedirect and queryParam in AuthenticationService

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Configure the AuthenticationService to redirect unauthenticated users to the login page instead of raising an exception. The 'queryParam' option appends the current request target URI as a query parameter, but only for GET requests.

```php
// In the getAuthenticationService() method of your src/Application.php

$service = new AuthenticationService();

// Configure unauthenticated redirect
$service->setConfig([
    'unauthenticatedRedirect' => '/users/login',
    'queryParam' => 'redirect',
]);
```

--------------------------------

### Access authentication result and status

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Accesses the authentication result object to check validity, get a status code, and retrieve error messages or data from the identifier.

```php
$result = $request->getAttribute('authentication')->getResult();
// Boolean if the result is valid
$isValid = $result->isValid();
// A status code
$statusCode = $result->getStatus();
// An array of error messages or data if the identifier provided any
$errors = $result->getErrors();
```

--------------------------------

### Redirect after login with redirectAfterLogin()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Use redirectAfterLogin() in a controller's login method to safely redirect after a successful login. It handles both POST and GET requests and redirects to the specified URL when the authentication result is valid.

```php
public function login(): ?\Cake\Http\Response
{
    $result = $this->Authentication->getResult();

    // Regardless of POST or GET, redirect if user is logged in
    if ($result->isValid()) {
        return $this->Authentication->redirectAfterLogin([
            'controller' => 'Pages',
            'action' => 'display',
            'home',
        ]);
    }

    return null;
}
```

--------------------------------

### New AuthenticationService configuration with Password identifier

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Instantiate the service, define the password identifier, and load the Session and Form authenticators. Session should be first.

```php
// Instantiate the service
$service = new AuthenticationService();

// Define identifier
$passwordIdentifier = [
    'className' => 'Authentication.Password',
    'fields' => [
        'username' => 'email',
        'password' => 'password',
    ],
];

// Load the authenticators. Session should be first.
$service->loadAuthenticator('Authentication.Session');
$service->loadAuthenticator('Authentication.Form', [
    'identifier' => $passwordIdentifier,
]);
```

--------------------------------

### After (4.x): Using PrimaryKeySessionAuthenticator

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the new 4.x way to load PrimaryKeySessionAuthenticator to fetch fresh user data from the database on each request.

```php
$service->loadAuthenticator('Authentication.PrimaryKeySession');
```

--------------------------------

### Implement AuthenticationServiceProviderInterface in Application

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Add the required use statements and implement the interface to provide the authentication service to the middleware.

```php
// in src/Application.php

// Add the following use statements.
use Authentication\AuthenticationService;
use Authentication\AuthenticationServiceInterface;
use Authentication\AuthenticationServiceProviderInterface;
use Authentication\Middleware\AuthenticationMiddleware;
use Psr\Http\Message\ServerRequestInterface;

// Add the authentication interface.
class Application extends BaseApplication implements AuthenticationServiceProviderInterface
{
    /**
     * Returns a service provider instance.
     *
     * @param \Psr\Http\Message\ServerRequestInterface $request Request
     * @return \Authentication\AuthenticationServiceInterface
     */
    public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
    {
        $service = new AuthenticationService();
        // Configure the service. (see below for more details)
        return $service;
    }
}
```

--------------------------------

### Create identifiers with IdentifierFactory

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows how to instantiate identifiers using the new IdentifierFactory class. Supports creating from a string name, with configuration options, or passing an existing instance which is returned as-is.

```php
use Authentication\Identifier\IdentifierFactory;

// Create from string
$identifier = IdentifierFactory::create('Authentication.Password');

// Create with config
$identifier = IdentifierFactory::create('Authentication.Password', [
    'fields' => [
        'username' => 'email',
        'password' => 'password',
    ],
]);

// Pass existing instance (returns as-is)
$identifier = IdentifierFactory::create($existingIdentifier);
```

--------------------------------

### Get identity from request attribute

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Retrieves the authenticated user identity from the request. Returns null when the user is unauthenticated or credentials are invalid.

```php
$user = $request->getAttribute('identity');
```

--------------------------------

### Load the authentication plugin in bootstrap()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Add the plugin in the application's bootstrap method to enable the authentication plugin.

```php
public function bootstrap(): void
{
    parent::bootstrap();
    $this->addPlugin('Authentication');
}
```

--------------------------------

### Multiple URLs: Before and After (3.x vs 4.x)

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the 3.x behavior where multiple login URLs auto-selected the appropriate checker, and the 4.x change requiring explicit configuration of 'Authentication.Multi' as the 'urlChecker'.

```php
// This would auto-select the appropriate checker
$service->loadAuthenticator('Authentication.Form', [
    'loginUrl' => [
        '/en/users/login',
        '/de/users/login',
    ],
]);
```

```php
// Must explicitly configure MultiUrlChecker
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => 'Authentication.Multi',
    'loginUrl' => [
        '/en/users/login',
        '/de/users/login',
    ],
]);
```

--------------------------------

### Load Authentication.Identity Helper

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/view-helper.md

Loads the Authentication.Identity helper in the AppView class.

```php
$this->loadHelper('Authentication.Identity');
```

--------------------------------

### After (4.x): Using CREDENTIAL constants from PasswordIdentifier

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the new 4.x usage of CREDENTIAL constants from PasswordIdentifier for standard password authentication.

```php
use Authentication\Identifier\PasswordIdentifier;

$fields = [
    PasswordIdentifier::CREDENTIAL_USERNAME => 'email',
    PasswordIdentifier::CREDENTIAL_PASSWORD => 'password',
];
```

--------------------------------

### Get identifier from identity object

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identity-object.md

Shows how to retrieve the identifier from the identity object in three contexts: the authentication service, the component, and the request. Each call returns the primary id value of the current login identity.

```php
// Service
$authenticationService
    ->getIdentity()
    ->getIdentifier()

// Component
$this->Authentication
    ->getIdentity()
    ->getIdentifier();

// Request
$this->request
    ->getAttribute('identity')
    ->getIdentifier();
```

--------------------------------

### Combine Stateless HttpBasic with Stateful Authenticators

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Combine stateful authenticators (Session, Form) with the stateless HttpBasic authenticator. Load HttpBasic last so it can halt the request and send challenge headers when credentials are missing or invalid.

```php
use Authentication\AuthenticationService;

// Instantiate the service
$service = new AuthenticationService();

// Define identifiers
$passwordIdentifier = [
    'className' => 'Authentication.Password',
    'fields' => [
        'username' => 'email',
        'password' => 'password',
    ],
];

// Load the authenticators leaving Basic as the last one.
$service->loadAuthenticator('Authentication.Session');
$service->loadAuthenticator('Authentication.Form', [
    'identifier' => $passwordIdentifier,
]);
$service->loadAuthenticator('Authentication.HttpBasic', [
    'identifier' => 'Authentication.Token',
]);
```

--------------------------------

### Session-based authentication login helper

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/testing.md

Define a helper method that simulates a logged-in user by setting the session data. The method fetches a user by ID and stores it in the 'Auth' session key.

```php
protected function login(int $userId = 1): void
{
    $user = $this->fetchTable('Users')->get($userId);
    $this->session(['Auth' => $user]);
}
```

--------------------------------

### Configure Token Authenticator with queryParam and header

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Configures the Token authenticator to read the token from the 'token' query parameter or the 'Authorization' header with the prefix 'Token'. The token is then passed to the configured identifier.

```php
$service->loadAuthenticator('Authentication.Token', [
    'queryParam' => 'token',
    'header' => 'Authorization',
    'tokenPrefix' => 'Token'
]);
```

--------------------------------

### Import authentication classes in Application.php

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

Add these imports to src/Application.php to use the authentication plugin's classes and interfaces.

```php
use Authentication\AuthenticationService;
use Authentication\AuthenticationServiceInterface;
use Authentication\AuthenticationServiceProviderInterface;
use Authentication\Identifier\PasswordIdentifier;
use Authentication\Middleware\AuthenticationMiddleware;
use Cake\Http\MiddlewareQueue;
use Cake\Routing\Router;
use Psr\Http\Message\ServerRequestInterface;
```

--------------------------------

### Before (3.x): Using loadIdentifier() with AuthenticationService

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the deprecated 3.x pattern of loading an identifier separately via loadIdentifier() before loading an authenticator. This method is removed in 4.x.

```php
$service = new AuthenticationService();
$service->loadIdentifier('Authentication.Password');
$service->loadAuthenticator('Authentication.Form');
```

--------------------------------

### Load Plugin with CakePHP CLI

Source: https://github.com/cakephp/authentication/blob/4.x/readme.md

Load the plugin into the CakePHP application.

```bash
bin/cake plugin load Authentication
```

--------------------------------

### After (4.x): Configuring identifier within loadAuthenticator()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the new 4.x way to configure the identifier directly in the authenticator config, either as a string or with options for fields.

```php
$service = new AuthenticationService();
$service->loadAuthenticator('Authentication.Form', [
    'identifier' => 'Authentication.Password',
]);
```

```php
$service = new AuthenticationService();
$service->loadAuthenticator('Authentication.Form', [
    'identifier' => [
        'className' => 'Authentication.Password',
        'fields' => [
            'username' => 'email',
            'password' => 'password',
        ],
    ],
]);
```

--------------------------------

### Configure custom identity decorator

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identity-object.md

Shows how to set a custom identity decorator using either a callable or a class name, then pass it to the AuthenticationService configuration via the 'identityClass' key.

```php
// You can use a callable...
$identityResolver = function ($data) {
    return new MyCustomIdentity($data);
};

//...or a class name to set the identity wrapper.
$identityResolver = MyCustomIdentity::class;

// Then pass it to the service configuration
$service = new AuthenticationService([
    'identityClass' => $identityResolver,
    'authenticators' => [
        'Authentication.Form' => [
            'identifier' => 'Authentication.Password',
        ],
    ]
]);
```

--------------------------------

### Set identityCheckEvent to Controller.initialize

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Configures the AuthenticationComponent to perform identity checks during the Controller.initialize event instead of the default Controller.startup event. Place this in the controller's initialize() method.

```php
// In your controller's initialize() method.
$this->loadComponent('Authentication.Authentication', [
    'identityCheckEvent' => 'Controller.initialize',
]);
```

--------------------------------

### Login Form View Template

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

View template for the login form. It creates a form with email and password fields and a login button.

```php
// in templates/Users/login.php
<div class="users form content">
    <?= $this->Form->create() ?>
    <fieldset>
        <legend><?= __('Please enter your email and password') ?></legend>
        <?= $this->Form->control('email') ?>
        <?= $this->Form->control('password') ?>
    </fieldset>
    <?= $this->Form->button(__('Login')) ?>
    <?= $this->Form->end() ?>
</div>
```

--------------------------------

### Before (3.x): Using CREDENTIAL constants from AbstractIdentifier

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the deprecated 3.x usage of CREDENTIAL_USERNAME and CREDENTIAL_PASSWORD constants from AbstractIdentifier. These constants have moved to specific identifier implementations in 4.x.

```php
use Authentication\Identifier\AbstractIdentifier;

$fields = [
    AbstractIdentifier::CREDENTIAL_USERNAME => 'email',
    AbstractIdentifier::CREDENTIAL_PASSWORD => 'password',
];
```

--------------------------------

### Inspect login redirect target with getLoginRedirect()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Inspects the validated login redirect target before redirecting. Use getLoginRedirect() instead of reading raw redirect query string parameters directly.

```php
$target = $this->Authentication->getLoginRedirect('/home');
return $this->redirect($target);
```

--------------------------------

### Load AuthenticationComponent with logoutRedirect

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Loads the Authentication component in AppController::initialize(). The 'logoutRedirect' option defaults to false but can be set to a URL for redirect after logout.

```php
$this->loadComponent('Authentication.Authentication', [
    'logoutRedirect' => '/users/login'  // Default is false
]);
```

--------------------------------

### Define getAuthenticationService method

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

Add this method to src/Application.php to define the AuthenticationService. It configures unauthenticated redirect, loads Session and Form authenticators, and uses PasswordIdentifier with email/password fields.

```php
/**
 * Returns a service provider instance.
 *
 * @param \Psr\Http\Message\ServerRequestInterface $request Request
 * @return \Authentication\AuthenticationServiceInterface
 */
public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $service = new AuthenticationService();

    // Define where users should be redirected to when they are not authenticated
    $service->setConfig([
        'unauthenticatedRedirect' => [
            'prefix' => false,
            'plugin' => false,
            'controller' => 'Users',
            'action' => 'login',
        ],
        // or just a simple string
        'unauthenticatedRedirect' => '/users/login',
        'queryParam' => 'redirect',
    ]);

    $fields = [
        PasswordIdentifier::CREDENTIAL_USERNAME => 'email',
        PasswordIdentifier::CREDENTIAL_PASSWORD => 'password',
    ];

    // Load the authenticators. Session should be first.
    // Session just uses session data directly as identity, no identifier needed.
    $service->loadAuthenticator('Authentication.Session');
    $service->loadAuthenticator('Authentication.Form', [
        'identifier' => [
            'className' => 'Authentication.Password',
            'fields' => $fields,
        ],
        'fields' => $fields,
        'loginUrl' => Router::url([
            'prefix' => false,
            'plugin' => false,
            'controller' => 'Users',
            'action' => 'login',
        ]),
    ]);

    return $service;
}
```

--------------------------------

### StringUrlChecker with regex

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/url-checkers.md

Enables regex matching with the StringUrlChecker by setting 'useRegex' to true and providing a regular expression in 'loginUrl'.

```php
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => [
        'className' => 'Authentication.String',
        'useRegex' => true,
    ],
    'loginUrl' => '%^/[a-z]{2}/users/login/?$%',
]);
```

--------------------------------

### Configure MultiUrlChecker for multiple login URLs

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Demonstrates configuring the Form authenticator with the new MultiUrlChecker to support multiple login URLs. The 'loginUrl' option accepts an array of URL patterns, including arrays for complex routes.

```php
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => 'Authentication.Multi',
    'loginUrl' => [
        '/en/login',
        '/de/login',
        ['lang' => 'fr', 'controller' => 'Users', 'action' => 'login'],
    ],
]);
```

--------------------------------

### MultiUrlChecker with multiple string URLs

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/url-checkers.md

Configures the MultiUrlChecker with multiple string URLs for multi-language support.

```php
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => 'Authentication.Multi',
    'loginUrl' => [
        '/en/users/login',
        '/de/users/login',
    ],
]);
```

--------------------------------

### Old AuthComponent configuration

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

The previous configuration array for the AuthComponent, which is now split into identifiers and authenticators.

```php
$this->loadComponent('Auth', [
    'authentication' => [
        'Form' => [
            'fields' => [
                'username' => 'email',
                'password' => 'password',
            ]
        ]
    ]
]);
```

--------------------------------

### Implement IdentityInterface on User class

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identity-object.md

Implements Authentication\IdentityInterface on an existing User class to continue using it with the plugin. Requires getIdentifier() and getOriginalData() methods.

```php
namespace App\Model\Entity;

use Authentication\IdentityInterface;
use Cake\ORM\Entity;

class User extends Entity implements IdentityInterface
{
    /**
     * Authentication\IdentityInterface method
     */
    public function getIdentifier(): array|string|int|null
    {
        return $this->id;
    }

    /**
     * Authentication\IdentityInterface method
     */
    public function getOriginalData(): \ArrayAccess|array
    {
        return $this;
    }

    // Other methods
}
```

--------------------------------

### Load Authentication component in AppController

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

Load the Authentication component in AppController's initialize method. By default it requires an authenticated user for all actions.

```php
// in src/Controller/AppController.php
public function initialize(): void
{
    parent::initialize();

    $this->loadComponent('Authentication.Authentication');
}
```

--------------------------------

### Configure FallbackPasswordHasher and Rehash Passwords on Login

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/password-hashers.md

Configure the FallbackPasswordHasher to migrate from Legacy (md5) to Default (bcrypt) hashing, then in the login action check if the password needs rehashing and update the user record. The rehash happens on save, and the user's password is taken from the request data.

```php
$passwordIdentifier = [
    'className' => 'Authentication.Password',
    // Other config options
    'passwordHasher' => [
        'className' => 'Authentication.Fallback',
        'hashers' => [
            'Authentication.Default',
            [
                'className' => 'Authentication.Legacy',
                'hashType' => 'md5',
                'salt' => false, // turn off default usage of salt
            ],
        ],
    ],
];
```

```php
public function login(): ?\Cake\Http\Response
{
    $authentication = $this->request->getAttribute('authentication');
    $result = $authentication->getResult();

    // Regardless of POST or GET, redirect if user is logged in
    if ($result->isValid()) {
        if ($authentication->getIdentificationProvider()->needsPasswordRehash()) {
            // Rehash happens on save.
            $user = $this->fetchTable('Users')->get(
                $authentication->getIdentity()->getIdentifier()
            );
            $user->password = $this->request->getData('password');
            $this->fetchTable('Users')->saveOrFail($user);
        }

        // Redirect or display a template.
        return $this->redirect('/');
    }

    return null;
}
```

--------------------------------

### Configure PrimaryKeySession with custom idField and identifierKey

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Loads PrimaryKeySession with custom idField and identifierKey options. These propagate to the default identifier, storing the uuid field and supplying ['key' => $uuid] to the identifier.

```php
$service->loadAuthenticator('Authentication.PrimaryKeySession', [
    'idField' => 'uuid',
    'identifierKey' => 'key',
]);
```

--------------------------------

### Add AuthenticationMiddleware to middleware queue

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Add the middleware to the application's middleware queue, passing the application instance.

```php
// in src/Application.php
public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
{
    // Various other middlewares for error handling, routing etc. added here.

    // Add the middleware to the middleware queue
    $middlewareQueue->add(new AuthenticationMiddleware($this));

    return $middlewareQueue;
}
```

--------------------------------

### Configure custom resolver via config array

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identifiers.md

Configure a custom resolver by specifying its class name and additional options in the identifier's 'resolver' config. The 'className' can be a short name like 'MyResolver' or a fully qualified class name. Options are passed to the resolver constructor.

```php
$identifier = [
    'className' => 'Authentication.Password',
    'resolver' => [
        // can be a full class name: \Some\Other\Custom\Resolver::class
        'className' => 'MyResolver',
        // Pass additional options to the resolver constructor.
        'option' => 'value',
    ],
];
```

--------------------------------

### Login action using Authentication result

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Check the authentication result and redirect on success, or display an error on failed POST.

```php
public function login(): ?\Cake\Http\Response
{
    $result = $this->Authentication->getResult();

    // Regardless of POST or GET, redirect if user is logged in
    if ($result->isValid()) {
        $target = $this->Authentication->getLoginRedirect();

        return $this->redirect($target);
    }

    // Display error if user submitted and authentication failed
    if ($this->request->is('post')) {
        $this->Flash->error('Invalid username or password');
    }

    return null;
}
```

--------------------------------

### Deny action by allowing others with allowUnauthenticated()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Mimics $this->Auth->deny(['register']) by allowing unauthenticated access for all actions except 'register'.

```php
$action = $this->getRequest()->getParam('action');
if ($action !== 'register') {
    $this->Authentication->allowUnauthenticated([$action]);
}
```

--------------------------------

### Redirect after login with redirectAfterLogin()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Redirects after a successful login using redirectAfterLogin(). Uses the plugin's validated login redirect target from the current request when available, falling back to the provided default ('/home').

```php
public function login(): ?\Cake\Http\Response
{
    $result = $this->Authentication->getResult();

    if ($result && $result->isValid()) {
        return $this->Authentication->redirectAfterLogin('/home');
    }

    return null;
}
```

--------------------------------

### After (4.x): URL checker configurations

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the new 4.x ways to configure URL checkers: DefaultUrlChecker is now hardcoded (formerly CakeRouterUrlChecker) and StringUrlChecker for string-only URL checking.

```php
// DefaultUrlChecker is now hardcoded (formerly CakeRouterUrlChecker)
$service->loadAuthenticator('Authentication.Form', [
    'loginUrl' => [
        'controller' => 'Users',
        'action' => 'login',
    ],
]);
```

```php
// For string-only URL checking, explicitly use StringUrlChecker
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => 'Authentication.String',
    'loginUrl' => '/users/login',
]);
```

--------------------------------

### After (4.x): Using CREDENTIAL constants from LdapIdentifier

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the new 4.x usage of CREDENTIAL constants from LdapIdentifier for LDAP authentication, with 'uid' as the username field.

```php
use Authentication\Identifier\LdapIdentifier;

$fields = [
    LdapIdentifier::CREDENTIAL_USERNAME => 'uid',
    LdapIdentifier::CREDENTIAL_PASSWORD => 'password',
];
```

--------------------------------

### Before (3.x): URL checker configurations

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the deprecated 3.x ways to configure URL checkers: using CakeRouterUrlChecker explicitly, DefaultUrlChecker explicitly, and auto-detection. Auto-detection is removed in 4.x.

```php
// Using CakeRouterUrlChecker explicitly
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => 'Authentication.CakeRouter',
    'loginUrl' => [
        'controller' => 'Users',
        'action' => 'login',
    ],
]);
```

```php
// Using DefaultUrlChecker explicitly
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => 'Authentication.Default',
    'loginUrl' => '/users/login',
]);
```

```php
// Auto-detection (picks CakeRouter if available, otherwise Default)
$service->loadAuthenticator('Authentication.Form', [
    'loginUrl' => '/users/login',
]);
```

--------------------------------

### Impersonate a user with AuthenticationComponent::impersonate()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/impersonation.md

Use this controller action to impersonate another user. It requires a POST request, checks that the current user is staff, fetches the target user by ID, and calls impersonate() on the AuthenticationComponent. After this, all subsequent requests will have the target user as the active identity.

```php
// In a controller
public function impersonate(): \Cake\Http\Response
{
    $this->request->allowMethod(['POST']);

    $currentUser = $this->request->getAttribute('identity');

    // You should always check that the current user is allowed
    // to impersonate other users first.
    if (!$currentUser->isStaff()) {
        throw new NotFoundException();
    }

    // Fetch the user we want to impersonate.
    $targetUser = $this->fetchTable('Users')
        ->findById($this->request->getData('user_id'))
        ->firstOrFail();

    // Enable impersonation.
    $this->Authentication->impersonate($targetUser);

    return $this->redirect($this->referer());
}
```

--------------------------------

### Configure redirect validation in AuthenticationService

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/redirect-validation.md

Configures the AuthenticationService with redirect validation enabled and custom limits for depth, encoding levels, and length.

```php
$service = new AuthenticationService();
$service->setConfig([
    'unauthenticatedRedirect' => '/users/login',
    'queryParam' => 'redirect',
    'redirectValidation' => [
        'enabled' => true,
        'maxDepth' => 1,
        'maxEncodingLevels' => 1,
        'maxLength' => 2000,
    ],
]);
```

--------------------------------

### Before (3.x): Using IdentifierCollection with FormAuthenticator

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the deprecated 3.x way of creating an IdentifierCollection and passing it to FormAuthenticator. This pattern is removed in 4.x.

```php
use Authentication\Identifier\IdentifierCollection;

$identifiers = new IdentifierCollection([
    'Authentication.Password',
]);

$authenticator = new FormAuthenticator($identifiers);
```

--------------------------------

### Set up IntegrationTestTrait in a controller test

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/testing.md

Use this snippet to include the IntegrationTestTrait in your test class, which is required for simulating authentication in integration tests.

```php
// In a controller test.
use Cake\TestSuite\IntegrationTestTrait;
use Cake\TestSuite\TestCase;

class ArticlesControllerTest extends TestCase
{
    use IntegrationTestTrait;

    // Test methods and helpers to follow.
}
```

--------------------------------

### Log out with clearIdentity() and returned array

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Logs out using the authentication service via `clearIdentity()`. The result is an array containing the (immutable) request and response objects; you must use the returned instances to continue working with the modified objects.

```php
$return = $request->getAttribute('authentication')->clearIdentity($request, $response);
```

```php
[
    'response' => object(Cake\Http\Response) { ... },
    'request' => object(Cake\Http\ServerRequest) { ... },
]
```

--------------------------------

### Customize PrimaryKeySession identifier configuration

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Loads PrimaryKeySession with a custom identifier configuration, specifying the Token identifier class, tokenField, dataField, and resolver.

```php
$service->loadAuthenticator('Authentication.PrimaryKeySession', [
    'idField' => 'uuid',
    'identifier' => [
        'className' => 'Authentication.Token',
        'tokenField' => 'uuid',
        'dataField' => 'token',
        'resolver' => 'Authentication.Orm',
    ],
]);
```

--------------------------------

### Configure JWT authenticator with external JWKS endpoint

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Fetches a JSON Web Key Set from an external endpoint, caches it, and configures the JwtAuthenticator to use it for token verification. The 'keys' key is required in the JWKS, and keys should include an 'alg' key if missing.

```php
// Application.php
public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $service = new AuthenticationService();
    // ...

    $jwksUrl = 'https://appleid.apple.com/auth/keys';

    // Set of keys. The "keys" key is required. Additionally keys require a "alg" key.
    // Add it manually to your JWK array if it doesn't already exist.
    $jsonWebKeySet = Cache::remember('jwks-' . md5($jwksUrl), function () use ($jwksUrl) {
        $http = new Client();
        $response = $http->get($jwksUrl);
        return $response->getJson();
    });

    $service->loadAuthenticator('Authentication.Jwt', [
        'identifier' => 'Authentication.JwtSubject',
        'jwks' => $jsonWebKeySet,
        'returnPayload' => false
    ]);
}
```

--------------------------------

### Login Action in UsersController

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

Adds a login action to UsersController. It checks the authentication result and redirects logged-in users to '/home'; otherwise, it displays an error flash message on POST requests.

```php
// in src/Controller/UsersController.php
public function login(): ?\Cake\Http\Response
{
    $result = $this->Authentication->getResult();
    // If the user is logged in send them away.
    if ($result && $result->isValid()) {
        return $this->Authentication->redirectAfterLogin('/home');
    }
    if ($this->request->is('post')) {
        $this->Flash->error('Invalid username or password');
    }

    return null;
}
```

--------------------------------

### Log out with Authentication component

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authentication-component.md

Logs out the current identity using the Authentication component. If the `logoutRedirect` config is set, `Authentication::logout()` returns that value; otherwise it returns `false`. It does not perform any actual redirection.

```php
$this->Authentication->logout();
```

--------------------------------

### Callback identifier with simple callback returning user or null

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identifiers.md

Configures a callback identifier that returns an array of the identified user or null for failure. The callback receives the authentication data and performs identifier logic.

```php
// A simple callback identifier
$identifier = [
    'className' => 'Authentication.Callback',
    'callback' => function($data) {
        // do identifier logic

        // Return an array of the identified user or null for failure.
        if ($result) {
            return $result;
        }

        return null;
    },
];
```

--------------------------------

### Allow unauthenticated actions with allowUnauthenticated()

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Makes specific actions public by allowing unauthenticated access. Each call overwrites the current action list.

```php
// In your controller's beforeFilter method.
$this->Authentication->allowUnauthenticated(['view']);
```

--------------------------------

### Bake Users Model and Controller

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

Generates the Users model and controller using CakePHP's bake tool. Run these commands after creating the Users table as described in the CMS tutorial.

```bash
bin/cake bake model Users
bin/cake bake controller Users
```

--------------------------------

### DefaultUrlChecker vs StringUrlChecker Usage

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Demonstrates that DefaultUrlChecker (now CakePHP-based) supports both array and string URLs, while StringUrlChecker only accepts strings and throws an exception for array URLs.

```php
// DefaultUrlChecker now requires CakePHP Router
$checker = new DefaultUrlChecker();
$checker->check($request, ['controller' => 'Users', 'action' => 'login']);  // Works
$checker->check($request, '/users/login');  // Also works

// For string URL only usage:
$checker = new StringUrlChecker();
$checker->check($request, '/users/login');  // Works
$checker->check($request, ['controller' => 'Users']);  // Throws exception
```

--------------------------------

### Replicate AuthComponent hash upgrade with AuthenticationService

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Replicates AuthComponent's hash upgrade logic using the AuthenticationService. Checks if the authentication result is valid, then retrieves the identifier and calls needsPasswordRehash() to trigger a password rehash on save. Redirects to a logged-in page after successful authentication.

```php
public function login(): ?\Cake\Http\Response
{
    $result = $this->Authentication->getResult();

    // Regardless of POST or GET, redirect if user is logged in
    if ($result->isValid()) {
        $authService = $this->Authentication->getAuthenticationService();

        // Get the identifier that was used for authentication.
        $identifier = $authService->getIdentificationProvider();
        if ($identifier !== null && $identifier->needsPasswordRehash()) {
            // Rehash happens on save.
            $user = $this->fetchTable('Users')->get(
                $this->Authentication->getIdentityData('id')
            );
            $user->password = $this->request->getData('password');
            $this->fetchTable('Users')->saveOrFail($user);
        }

        // Redirect to a logged in page
        return $this->redirect([
            'controller' => 'Pages',
            'action' => 'display',
            'home',
        ]);
    }

    return null;
}
```

--------------------------------

### Before (3.x): SessionAuthenticator with identify option

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/upgrade-3-to-4.md

Shows the deprecated 3.x usage of the 'identify' option in SessionAuthenticator. This option is removed in 4.x; use PrimaryKeySessionAuthenticator instead.

```php
$service->loadAuthenticator('Authentication.Session', [
    'identify' => true,
    'identifier' => 'Authentication.Password',
]);
```

--------------------------------

### Password Identifier Configuration

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/identifiers.md

Configuration array for the Password identifier, showing custom fields, ORM resolver with a finder, and a fallback password hasher with a legacy MD5 hasher.

```php
$identifier = [
    'className' => 'Authentication.Password',
    'fields' => [
        'username' => 'email',
        'password' => 'passwd',
    ],
    'resolver' => [
        'className' => 'Authentication.Orm',
        'userModel' => 'Users',
        'finder' => 'active', // default: 'all'
    ],
    'passwordHasher' => [
        'className' => 'Authentication.Fallback',
        'hashers' => [
            'Authentication.Default' => [
                'className' => 'Authentication.Legacy',
                'hashType' => 'md5',
            ],
        ],
    ],
];
```

--------------------------------

### Login action that creates a JWT token

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

In the UsersController, this login action checks the authentication result and, if valid, creates a JWT payload with issuer, subject, and expiration, then encodes it with the private key using RS256. On failure, it returns a 401 status.

```php
use Firebase\JWT\JWT;

public function login(): void
{
    $result = $this->Authentication->getResult();
    if ($result->isValid()) {
        $privateKey = file_get_contents(CONFIG . 'jwt.key');
        $user = $result->getData();
        $payload = [
            'iss' => 'myapp',
            'sub' => $user->id,
            'exp' => time() + 60,
        ];
        $json = [
            'token' => JWT::encode($payload, $privateKey, 'RS256'),
        ];
    } else {
        $this->response = $this->response->withStatus(401);
        $json = [];
    }
    $this->set(compact('json'));
    $this->viewBuilder()->setOption('serialize', 'json');
}
```

--------------------------------

### StringUrlChecker with string URL

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/url-checkers.md

Uses the StringUrlChecker for a single string URL.

```php
$service->loadAuthenticator('Authentication.Form', [
    'urlChecker' => 'Authentication.String',
    'loginUrl' => '/users/login',
]);
```

--------------------------------

### DefaultUrlChecker with string URL

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/url-checkers.md

Configures the default URL checker with a single string URL for the login page.

```php
$service->loadAuthenticator('Authentication.Form', [
    'loginUrl' => '/users/login',
]);
```

--------------------------------

### Custom userModel configuration for Password identifier

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/migration-from-the-authcomponent.md

Configuration for using a custom userModel with the Orm resolver in the Password identifier.

```php
// Instantiate the service
$service = new AuthenticationService();

// Define identifier
$passwordIdentifier = [
    'className' => 'Authentication.Password',
    'resolver' => [
        'className' => 'Authentication.Orm',
        'userModel' => 'Employees',
    ],
    'fields' => [
        'username' => 'email',
        'password' => 'password',
    ],
];
```

--------------------------------

### Logout Action in UsersController

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/index.md

Logs out the user and redirects to the login action. No template is needed because the action redirects.

```php
// in src/Controller/UsersController.php
public function logout(): \Cake\Http\Response
{
    $this->Authentication->logout();

    return $this->redirect(['controller' => 'Users', 'action' => 'login']);
}
```

--------------------------------

### Token Identifier Input Array

Source: https://github.com/cakephp/authentication/blob/4.x/docs/en/authenticators.md

Shows the array structure that the token authenticator always passes to the configured identifier, with the key 'token' and the token value.

```php
[
    'token' => '{token-value}',
]
```
Tokens:
Raw