Configuration

The package is configured with environment variables, that the services of the package read (%env(...)%), and with the services and the routes that the application imports. Everything has a default, and the ones that are not safe to guess (the client of Keycloak, the database) have none.

What the application imports

The services and the routes are the same for every provider: the application imports them and chooses the provider with AUTH_PROVIDER.

# config/services.yaml
imports:
    - { resource: '../vendor/derafu/auth/resources/config/auth-services.yaml' }

# config/routes.yaml
imports:
    - { resource: '../vendor/derafu/auth/resources/config/auth-routes.yaml' }

The services bring everything that the application needs: the manager of the authentication with its two channels (web and API), the authorization with the access rules, the translations of the package, and the three providers, of which only the chosen one is made. See How it works. The session and the flash messages are not part of the provider: the middlewares and the variables SESSION_* come from derafu/session, which a site that uses derafu/foundation already has. The routes are /auth/login, /auth/logout and /auth/profile (see Profile), /auth/callback and the routes of the API tokens: the callback answers 404 with a provider whose login is a form, and the tokens with one that has none. The logout accepts only POST (see Security).

The middlewares

For Derafu HTTP’s shared pipeline, import auth-http-services.yaml instead of auth-services.yaml:

# config/services.yaml
imports:
    - { resource: '../vendor/derafu/auth/resources/config/auth-http-services.yaml' }

This imports the base Auth services and contributes authentication with priority 350 and authorization with priority 300 through derafu_http.middleware. Higher priorities run first. Do not repeat those registrations or rebuild the request handler in the site.

The application supplies the HTTP pipeline and, for the web channel, the session and flash middleware. Foundation already supplies these, together with CSRF: session 500, flash 450, CSRF 400, authentication 350, authorization 300, dispatch 200.

The router goes first because the login and the logout have routes. Session and flash precede authentication, which uses them; authentication precedes authorization, which reads the user it adds to the request.

For another PSR-15 pipeline, keep importing auth-services.yaml and attach its authentication and authorization middlewares in that same order. The base YAML registers them without activating a pipeline. The optional HTTP YAML does not import a kernel or session services, and does not require derafu/http as a package dependency.

The cache pool

The providers use a PSR-6 pool (Psr\Cache\CacheItemPoolInterface): the database and htpasswd providers for the count of the failed logins (they need it: without one the first count fails with a message that says so), and the Keycloak provider for the keys of the realm (it is optional, without it the keys are read in every request that verifies a token). derafu/foundation registers one in the cache directory of the kernel. An application that has its own declares the same id.

The provider

The variable is read when a piece of the provider is needed (the login, the API, the profile), not when the container is built: with it empty or wrong the pages that do not use the provider keep working, and what needs it fails with a message that says what to set and which providers there are.

Variables of the access rules

They are the same in every provider, and they are about who may enter which path, not about how a request is identified.

Variables of the web channel

The login path is not a variable: it is the callback (AUTH_KEYCLOAK_WEB_CALLBACK_PATH) in Keycloak and /auth/login in the database and htpasswd providers.

Variables of the API channel

Variables of login attempt limits

Database and Htpasswd use one shared Derafu\Auth\Contract\LoginThrottleInterface instance and the same policy for web login and HTTP Basic. The application must provide a PSR-6 cache pool when this throttle is used.

Variables of the session

The session is the one of Mezzio, with the session of PHP, and its variables (SESSION_NAME, SESSION_COOKIE_SECURE, SESSION_COOKIE_SAMESITE and the others) are the ones of derafu/session.

Variables of Keycloak

AUTH_KEYCLOAK_URL=https://auth.example.com
AUTH_KEYCLOAK_REALM=my-realm
AUTH_KEYCLOAK_CLIENT_ID=my-app
AUTH_KEYCLOAK_CLIENT_SECRET=the-secret
AUTH_KEYCLOAK_WEB_REDIRECT_URI=https://app.example.com/auth/callback

How the login works, and how to configure the client in Keycloak, is in Keycloak.

Variables of the database provider

More in Database.

Variables of the htpasswd provider

More in Htpasswd.

Changing the services

Injectable backend services are registered under their interfaces in Derafu\Auth\Contract. An application replaces an implementation by declaring the same service ID after importing the package YAML. Tagged contributions keep their individual IDs; controllers and pipeline middleware have their own entry-point IDs. For example, the anonymous user, that every piece that needs one takes if the application declares it (without it they make AnonymousUser):

Derafu\Auth\Contract\UserInterface:
    class: App\Auth\GuestUser

Or the flow that a provider gives to the web channel:

Derafu\Auth\Contract\WebFlowInterface:
    class: App\Auth\MyKeycloakWebFlow
    lazy: true

The services are lazy (lazy: true), and the ones that an application declares should be too. The translator reaches the channels by autowiring when the application has one (Symfony\Contracts\Translation\TranslatorInterface): see Translations.

Backend service contracts

The built-in configuration implementations use DatabaseConfigurationInterface, HtpasswdConfigurationInterface and KeycloakConfigurationInterface. Replace a configuration service under its interface to obtain the same settings from another source. Environment-variable defaults and validation remain the built-in implementations’ responsibility.

Database and Htpasswd use PasswordUserRepositoryInterface, which extends UserRepositoryInterface with find(): authentication checks a password, while lookup reloads current user details and roles for an existing session. Their service IDs are distinct because they access different storage:

services:
    Derafu\Auth\Contract\PasswordUserRepositoryInterface $database:
        class: App\Auth\DatabaseUsers
        lazy: true
        autowire: true

This replaces the database repository in both its web flow and HTTP Basic scheme. The Htpasswd repository uses Derafu\Auth\Contract\PasswordUserRepositoryInterface $htpasswd.

Keycloak exposes KeycloakUserRepositoryInterface for its OAuth/OIDC operations, KeycloakTokenVerifierInterface, KeycloakAccountClientInterface and KeycloakSessionManagerInterface. The latter extends SessionManagerInterface with tokens and login state. Its account receives token management through the existing ApiTokenManagerInterface. A replacement implements its contract; it does not have to extend the package’s concrete implementation.

Provider-specific flows, API schemes and accounts also use interface IDs:

The unqualified interfaces still resolve the services of the provider selected with AUTH_PROVIDER. Backend services reference their explicit backend dependency to avoid resolving themselves through that selection. No concrete-class aliases are registered for these services.

Authentication form definitions

The shared FormManagerInterface service is registered directly with FormManager, independently of provider selection. It accepts a registered definition’s FQCN or an object implementing Derafu\Auth\Contract\FormInterface. Register additional definition services with their class name as the service ID and the derafu_auth.form tag:

services:
    App\Auth\LoginFormDefinition:
        autowire: true
        tags: ['derafu_auth.form']

The container builds each definition with its own dependencies when requested. The manager resolves definitions through a restricted lazy locator and caches each resolved definition by class name. It receives no generic provider configuration and does not instantiate definition classes itself. An unregistered class or an invalid tagged service raises a translatable configuration exception.

An object definition supplied directly needs no registration; this supports runtime context such as Keycloak’s user-specific password help. Form data is applied to each new form instance after obtaining the definition.

Without a DI container, construct FormManager with the form factory, the form data processor and a PSR-11 locator whose keys are the definition class names.

The configuration without a container

The configuration classes take an array, with the same keys that the YAML gives them, so the pieces work without a container too (this is how the tests of the package use them). The manager of the authentication is assembled with the channels, the one of each provider included:

use Derafu\Auth\Authentication\AuthenticationManager;
use Derafu\Auth\Authentication\Channel\Api\ApiChannel;
use Derafu\Auth\Authentication\Channel\Api\ApiConfiguration;
use Derafu\Auth\Authentication\Channel\Web\WebChannel;
use Derafu\Auth\Authentication\Channel\Web\WebConfiguration;
use Derafu\Auth\Authorization\AccessRules;
use Derafu\Auth\Provider\Keycloak\Api\KeycloakBearerScheme;
use Derafu\Auth\Provider\Keycloak\KeycloakConfiguration;
use Derafu\Auth\Provider\Keycloak\KeycloakUserRepository;
use Derafu\Auth\Provider\Keycloak\Web\KeycloakSessionManager;
use Derafu\Auth\Provider\Keycloak\Web\KeycloakWebFlow;

$keycloak = new KeycloakConfiguration([
    'keycloak_url' => 'https://auth.example.com',
    'realm' => 'my-realm',
    'client_id' => 'my-app',
    'client_secret' => 'the-secret',
    'redirect_uri' => 'https://app.example.com/auth/callback',
]);
$users = new KeycloakUserRepository($keycloak);
$sessions = new KeycloakSessionManager();
$web = new WebConfiguration(['logout_redirect_path' => '/bye']);
$rules = new AccessRules(['protected_paths' => ['/dashboard']]);

$authentication = new AuthenticationManager(
    [
        // Asked first.
        new ApiChannel(new ApiConfiguration(['paths' => ['/api']]), new KeycloakBearerScheme($users, $keycloak)),
        // The last one: the channel of every request that is not of another.
        new WebChannel(new KeycloakWebFlow($users, $keycloak, $web, $sessions), $web, $sessions),
    ],
    $rules
);