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

The application puts four middlewares between the router and the dispatcher, in this order (the others of the list are the ones that every site has):

Psr\Http\Server\RequestHandlerInterface:
    class: Derafu\Http\Service\RequestHandler
    public: true
    arguments:
        $middlewares:
            - '@Derafu\Http\Middleware\StaticFilesMiddleware'
            - '@Derafu\Http\Middleware\RequestFactoryMiddleware'
            - '@Derafu\Http\Middleware\RouterMiddleware'
            - '@Mezzio\Session\SessionMiddleware'
            - '@Mezzio\Flash\FlashMessageMiddleware'
            - '@Derafu\Auth\Authentication\AuthenticationMiddleware'
            - '@Derafu\Auth\Authorization\AuthorizationMiddleware'
            - '@Derafu\Http\Middleware\DispatcherMiddleware'
            - '@Derafu\Http\Middleware\ResponseNormalizerMiddleware'

With the database provider the middleware of the CSRF tokens of derafu/csrf goes after the flash messages (see Database).

The router goes first because the login and the logout have routes: a path that has no route never reaches the authentication. The session and the flash messages go before the authentication, which uses them, and the authentication before the authorization, which reads the user that it puts in the request.

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 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

The services of the package are declared by their interface or class, so an application replaces one by declaring the same id after the import. 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.

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
);