Migration guide - Auth module to SecurityGui module

Edit on GitHub

We gave up the Auth module in favor of using Symfony Security. Symfony Security allows more flexible customization of the authorization system. More detailed information can be found in the official documentation.

More details are listed below:

  • All public API for modules Auth, AuthMailConnector, AuthMailConnectorExtension is deprecated.
  • AuthFacade::login() and AuthFacade::logout() was replaced with the implementation of Spryker\Shared\SecurityExtension\Dependency\Plugin\SecurityPluginInterface. For the Back Office authentication it was implemented at SecurityGui module with UserSecurityPlugin.
  • AuthFacade::isAuthenticated()is replaced with SecurityFacade::isUserLoggedIn().
  • AuthFacade::requestPasswordReset() is replaced with UserPasswordResetFacade::requestPasswordReset().
  • AuthFacade::isValidPasswordResetToken() is replaced with UserPasswordResetFacade::isValidPasswordResetToken().
  • AuthFacade::resetPassword() is replaced with UserPasswordResetFacade::setNewPassword().
  • UserFacade::expandMailWithUserData() was deprecated. Handling of user password reset mail is implemented in UserPasswordReset module.
  • Zed Backoffice login URL was changed to /security-gui/login.

To migrate from the Auth module to Symfony Security, do the following:

Update spryker-feature/spryker-core

Info

The steps in this section show you how to re-configure the YVES system user and update the configuration file to avoid using the Auth module constants, which will be removed.

  1. Run:

    composer require spryker-feature/spryker-core:dev-master
    
  2. Adjust config/Shared/common/config_oauth-development.php.

    • Remove:
    use Spryker\Shared\Auth\AuthConstants;
    
    • Add:
    use Spryker\Shared\SecuritySystemUser\SecuritySystemUserConstants;
    
    • Change:
    $config[AuthConstants::AUTH_DEFAULT_CREDENTIALS]['yves_system']['token'] = 'JDJ5JDEwJFE0cXBwYnVVTTV6YVZXSnVmM2l1UWVhRE94WkQ4UjBUeHBEWTNHZlFRTEd4U2F6QVBqejQ2';
    

    to:

    $config[SecuritySystemUserConstants::AUTH_DEFAULT_CREDENTIALS]['yves_system']['token'] = 'JDJ5JDEwJFE0cXBwYnVVTTV6YVZXSnVmM2l1UWVhRE94WkQ4UjBUeHBEWTNHZlFRTEd4U2F6QVBqejQ2';
    
  3. Adjust config/Shared/config_default.php.

    • Remove:
    use Spryker\Shared\Auth\AuthConstants;
    
    • Add:
    use Spryker\Shared\SecuritySystemUser\SecuritySystemUserConstants;
    
    • Change:
    $config[AuthConstants::AUTH_DEFAULT_CREDENTIALS] = [
    'yves_system' => [
        'rules' => [
            [
                'bundle' => '*',
                'controller' => 'gateway',
                'action' => '*',
            ],
        ],
        'token' => getenv('SPRYKER_ZED_REQUEST_TOKEN') ?: '',
    ],
    ];
    

    to:

    $config[SecuritySystemUserConstants::AUTH_DEFAULT_CREDENTIALS] = [
    'yves_system' => [
        'token' => getenv('SPRYKER_ZED_REQUEST_TOKEN') ?: '',
    ],
    ];
    
    • Change:
    $config[AuthConstants::SYSTEM_USER_SESSION_REDIS_LIFE_TIME] = 20;
    

    to:

    $config[SecuritySystemUserConstants::SYSTEM_USER_SESSION_REDIS_LIFE_TIME] = 20;
    
  4. Adjust tests/PyzTest/Zed/Console/_data/cli_sandbox/config/Shared/config_default.php.

    • Remove:
    use Spryker\Shared\Auth\AuthConstants;
    
    • Add:
    use Spryker\Shared\SecuritySystemUser\SecuritySystemUserConstants;
    
    • Change:
    $config[AuthConstants::AUTH_ZED_ENABLED]
    

    to:

    $config[ZedRequestConstants::AUTH_ZED_ENABLED]
    
    • Change:
    $config[AuthConstants::AUTH_DEFAULT_CREDENTIALS] = [
    'yves_system' => [
        'rules' => [
            [
                'bundle' => '*',
                'controller' => 'gateway',
                'action' => '*',
            ],
        ],
        'token' => 'JDJ5JDEwJFE0cXBwYnVVTTV6YVZXSnVmM2l1UWVhRE94WkQ4UjBUeHBEWTNHZlFRTEd4U2F6QVBqejQ2', // Please replace this token for your project
    ],
    ];
    

    to:

    $config[SecuritySystemUserConstants::AUTH_DEFAULT_CREDENTIALS] = [
    'yves_system' => [
        'token' => 'JDJ5JDEwJFE0cXBwYnVVTTV6YVZXSnVmM2l1UWVhRE94WkQ4UjBUeHBEWTNHZlFRTEd4U2F6QVBqejQ2', // Please replace this token for your project
    ],
    ];
    
    • If you are using the plugin Spryker/Zed/Auth/Communication/Plugin/SessionRedis/SystemUserSessionRedisLifeTimeCalculatorPlugin in src/Pyz/Zed/SessionRedis/SessionRedisDependencyProvider::getSessionRedisLifeTimeCalculatorPlugins(), please replace it with Spryker/Zed/SecuritySystemUser/Communication/Plugin/SessionRedis/SystemUserSessionRedisLifeTimeCalculatorPlugin.

Update Security module

Info

Updating the Security module is necessary to use the SecurityGui module, which replaces part of the Auth module’s functionality.

Run:

composer update spryker/security --with-dependencies

Update spryker-feature/spryker-core-back-office

Info

This section contains the basic steps for migrating from the Auth module to the SecurityGui module.

  1. Run:
composer require spryker-feature/spryker-core-back-office:dev-master
  1. Adjust config/Shared/config_default.php.

    • Change:
    $config[AclConstants::ACL_DEFAULT_RULES] = [
    [
        'bundle' => 'auth',
        'controller' => '*',
        'action' => '*',
        'type' => 'allow',
    

    to:

    $config[AclConstants::ACL_DEFAULT_RULES] = [
    [
        'bundle' => 'security-gui',
        'controller' => '*',
        'action' => '*',
        'type' => 'allow',
    
  2. Adjust src/Pyz/Zed/Application/ApplicationDependencyProvider.php.

Add Spryker\Zed\Security\Communication\Plugin\Application\SecurityApplicationPlugin to getApplicationPlugins().

 /**
     * @return \Spryker\Shared\ApplicationExtension\Dependency\Plugin\ApplicationPluginInterface[]
     */
    protected function getApplicationPlugins(): array
    {
        $plugins = [
            ...,
            new SecurityApplicationPlugin(),
        ];

        ...
    }

  1. Adjust src/Pyz/Zed/EventDispatcher/EventDispatcherDependencyProvider.php.

Remove AuthorizationEventDispatcherPlugin() and RedirectAfterLoginEventDispatcherPlugin() from getEventDispatcherPlugins().

  1. Adjust src/Pyz/Zed/Mail/MailDependencyProvider.php.

Remove RestorePasswordMailTypePlugin() and add UserPasswordResetMailTypePlugin() instead in provideBusinessLayerDependencies(Container $container).

    /**
     * @param \Spryker\Zed\Kernel\Container $container
     *
     * @return \Spryker\Zed\Kernel\Container
     */
    public function provideBusinessLayerDependencies(Container $container)
    {
        $container = parent::provideBusinessLayerDependencies($container);

        $container->extend(static::MAIL_TYPE_COLLECTION, function (MailTypeCollectionAddInterface $mailCollection) {
            $mailCollection
                ...
                ->add(new UserPasswordResetMailTypePlugin())
                ...
                ;

            return $mailCollection;
        });

        ...
    }
  1. Update src/Pyz/Zed/Security/SecurityDependencyProvider.php with code:
<?php

/**
 * This file is part of the Spryker Commerce OS.
 * For full license information, please view the LICENSE file that was distributed with this source code.
 */

namespace Pyz\Zed\Security;

use Spryker\Zed\Security\SecurityDependencyProvider as SprykerSecurityDependencyProvider;
use Spryker\Zed\SecurityGui\Communication\Plugin\Security\UserSecurityPlugin;
use Spryker\Zed\SecuritySystemUser\Communication\Plugin\Security\SystemUserSecurityPlugin;
use Spryker\Zed\User\Communication\Plugin\Security\UserSessionHandlerSecurityPlugin;

class SecurityDependencyProvider extends SprykerSecurityDependencyProvider
{
    /**
     * @return \Spryker\Shared\SecurityExtension\Dependency\Plugin\SecurityPluginInterface[]
     */
    protected function getSecurityPlugins(): array
    {
        return [
            new UserSessionHandlerSecurityPlugin(),
            new SystemUserSecurityPlugin(),
            new UserSecurityPlugin(),
        ];
    }
}
  1. Update src/Pyz/Zed/SecurityGui/SecurityGuiConfig.php with code:
<?php

/**
 * This file is part of the Spryker Commerce OS.
 * For full license information, please view the LICENSE file that was distributed with this source code.
 */

namespace Pyz\Zed\SecurityGui;

use Spryker\Zed\SecurityGui\SecurityGuiConfig as SprykerSecurityGuiConfig;

class SecurityGuiConfig extends SprykerSecurityGuiConfig
{
    protected const IGNORABLE_ROUTE_PATTERN = '^/(security-gui|health-check|_profiler/wdt)';
}
  1. Update src/Pyz/Zed/UserPasswordReset/UserPasswordResetDependencyProvider.php with code:
<?php

/**
 * This file is part of the Spryker Commerce OS.
 * For full license information, please view the LICENSE file that was distributed with this source code.
 */

namespace Pyz\Zed\UserPasswordReset;

use Spryker\Zed\UserPasswordReset\UserPasswordResetDependencyProvider as SprykerUserPasswordResetDependencyProvider;
use Spryker\Zed\UserPasswordResetMail\Communication\Plugin\UserPasswordReset\MailUserPasswordResetRequestHandlerPlugin;

class UserPasswordResetDependencyProvider extends SprykerUserPasswordResetDependencyProvider
{
    /**
     * @return \Spryker\Zed\UserPasswordResetExtension\Dependency\Plugin\UserPasswordResetRequestHandlerPluginInterface[]
     */
    public function getUserPasswordResetRequestHandlerPlugins(): array
    {
        return [
            new MailUserPasswordResetRequestHandlerPlugin(),
        ];
    }
}

Remove the old modules

Info

This section guides you how to remove the old module files.

  1. If the Auth module has not been uninstalled, run:
composer remove spryker/auth
  1. Run:
composer remove spryker/auth-mail-connector spryker/auth-mail-connector-extension
  1. Remove src/Orm/Zed/Auth folder, including all the files.
  2. Remove src/Pyz/Zed/Auth folder, including all the files.
  3. Remove src/Pyz/Zed/AuthMailConnector folder, including all the files.

Update SprykerTests

Info

This action is required for the SprykerTests to be up-to-date.

  1. Run:
composer update spryker/application --with-dependencies
  1. Adjust tests/PyzTest/Zed/Console/_data/cli_sandbox/config/Shared/config_default.php.

    • Change:
    $config[AclConstants::ACL_DEFAULT_CREDENTIALS] = [
    'yves_system' => [
        'rules' => [
            [
                'bundle' => '*',
                'controller' => 'gateway',
                'action' => '*',
                'type' => 'allow',
            ],
        ],
    ],
    ];
    

    to:

    $config[AclConstants::ACL_DEFAULT_CREDENTIALS] = [
    'yves_system' => [
        'rules' => [],
    ],
    ];
    
    • Change:
    $config[AclConstants::ACL_DEFAULT_RULES] = [
    [
        'bundle' => 'auth',
        'controller' => 'login',
        'action' => 'index',
        'type' => 'allow',
    ],
    [
        'bundle' => 'auth',
        'controller' => 'login',
        'action' => 'check',
        'type' => 'allow',
    ],
    [
        'bundle' => 'auth',
        'controller' => 'password',
        'action' => 'reset',
        'type' => 'allow',
    ],
    [
        'bundle' => 'auth',
        'controller' => 'password',
        'action' => 'reset-request',
        'type' => 'allow',
    ],
    

    to:

    $config[AclConstants::ACL_DEFAULT_RULES] = [
    [
        'bundle' => 'security-gui',
        'controller' => '*',
        'action' => '*',
        'type' => 'allow',
    ],
    
    • Change:
        [
        'bundle' => 'heartbeat',
        'controller' => 'index',
        'action' => 'index',
        'type' => 'allow',
    ],
    ];
    

    to:

        [
        'bundle' => 'health-check',
        'controller' => 'index',
        'action' => 'index',
        'type' => 'allow',
    ],
    ];
    
    • Change:
    $config[AclConstants::ACL_USER_RULE_WHITELIST] = [
    [
        'bundle' => 'application',
        'controller' => '*',
        'action' => '*',
        'type' => 'allow',
    ],
    [
        'bundle' => 'auth',
        'controller' => '*',
        'action' => '*',
        'type' => 'allow',
    ],
    [
        'bundle' => 'heartbeat',
        'controller' => 'heartbeat',
        'action' => 'index',
        'type' => 'allow',
    ],
    ];
    

    to:

    $config[AclConstants::ACL_USER_RULE_WHITELIST] = [
    [
        'bundle' => 'application',
        'controller' => '*',
        'action' => '*',
        'type' => 'allow',
    ],
    ];
    

Generate transfers

Info

This section helps you to generate transfer objects.

Run:

console transfer:generate

Update database

Info

This section helps you to generate the new Propel classes.

Run:

console propel:install

Estimated migration time: 2 hours.