Паспорта безопасности

Паспорт - это объект, содержащий пользователя, который будет аутентифицирован, а также других частей информации, вроде должен ли быть проверен пароль, или должна ли быть подключена функция "запомнить меня".

По умолчанию, Passport требует пользователя и идентификационных данных (например, пароль).

Используйте UserBadge, чтобы присоединить пользователя к паспорту. UserBadge требует идентификатор пользователя (например, имя пользователя или адрес электронной почты):

1
2
3
4

use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;

// ...
$passport = new Passport(new UserBadge($userIdentifier), $credentials);

Идентификатор пользователя

Идентификатор пользователя - это уникальная строка, которая идентифицирует пользователя. Часто это что-то вроде его адреса электронной почты или имени пользователя, но это может быть любое уникальное значение, связанное с пользователем. Оно позволяет загрузить пользователя через сконфигурированный поставщик пользователей .

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// src/Security/CustomAuthenticator.php
namespace App\Security;

use App\Repository\UserRepository;
// ...

class CustomAuthenticator extends AbstractAuthenticator
{
    public function __construct(
        private UserRepository $userRepository,
    ) {
    }

    public function authenticate(Request $request): Passport
    {
        // ...

        return new Passport(
            new UserBadge($email, function (string $userIdentifier): ?UserInterface {
                return $this->userRepository->findOneBy(['email' => $userIdentifier]);
            }),
            $credentials
        );
    }
}

Некоторые приложения нормализуют идентификаторы пользователей перед их обработкой. Например, перевод идентификаторов в нижний регистр помогает рассматривать такие значения, как "john.doe",
"John.Doe" или "JOHN.DOE" как эквивалентные в системах, где идентификаторы не чувствительны к регистру.

При необходимости вы можете передать нормализатор как третий аргумент UserBadge. Это вызываемое получает $userIdentifier и должно вернуть строку.

Пример ниже использует нормализатор, который преобразует имена пользователей в нормализованный, исключительно ASCII, формат в нижнем регистре:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/Security/NormalizedUserBadge.php
namespace App\Security;

use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use function Symfony\Component\String\u;

final class NormalizedUserBadge extends UserBadge
{
    public function __construct(string $identifier)
    {
        $callback = static fn (string $identifier): string => u($identifier)->normalize(UnicodeString::NFKC)->ascii()->lower()->toString();

        parent::__construct($identifier, null, $callback);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/Security/PasswordAuthenticator.php
namespace App\Security;

final class PasswordAuthenticator extends AbstractLoginFormAuthenticator
{
    // упрощено для краткости
    public function authenticate(Request $request): Passport
    {
        $username = (string) $request->request->get('username', '');
        $password = (string) $request->request->get('password', '');

        $request->getSession()
            ->set(SecurityRequestAttributes::LAST_USERNAME, $username);

        return new Passport(
            new NormalizedUserBadge($username),
            new PasswordCredentials($password),
            [
                // всі інші корисні бейджі
            ]
        );
    }
}

Полномочия пользователя

Полномочия пользователя используются для аутентификации пользователя, то есть для проверки валидности предоставленной информации (такой как пароль, токен API или пользовательские полномочия).

Следующие классы идентификационных данных поддерживаются по умолчанию:

PasswordCredentials

Это требует простого текстового $password, который валидируется с использованием кодировщика паролей, сконфигурированного для пользователя :

1
2
3
4

use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\PasswordCredentials;

// ...
return new Passport(new UserBadge($email), new PasswordCredentials($plaintextPassword));

CustomCredentials

Позволяет пользовательскому замыканию проверять идентификационные данные:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\CustomCredentials;

// ...
return new Passport(new UserBadge($email), new CustomCredentials(
    // Если эта функция возвращает что-либо, кроме `true`, идентификационные данные
    // помечаются, как не валидные.
    // Параметр $credentials равняется следующему аргументу этого класса
    function (string $credentials, UserInterface $user): bool {
        return $user->getApiToken() === $credentials;
    },

    // Пользовательские идентификационные данные
    $apiToken
));

Паспорт самовалидации

Если вам не нужно проверять идентификационные данные (например, при использовании токенов API), вы можете использовать SelfValidatingPassport. Этот класс требует только объект UserBadge, и, по желанию, Знаки паспорта.

Бейджи паспорта

Passport также дополнительно позволяет вам добавлять бейджи безопасности. Бейджи добавляют паспорту больше данных (чтобы расширить безопасность). По умолчанию, следующие бейджи поддерживаются:

RememberMeBadge

Когда этот бейдж добавляется к паспорту, аутентификатор обозначает, что поддерживается "запомнить меня". Используется ли на самом деле "запомнить меня", зависит от специальной конфигурации remember_me. Прочтите Как добавить функциональность входа в систему "Запомнить меня", чтобы узнать больше.

PasswordUpgradeBadge

Это используется для автоматического обновления пароля до нового хеша после успешного входа в систему. Этот знак требует простого текстового пароля и установщика обновлений паролей (например, хранилище пользователей). См. Как мигрировать хеш пароля.

CsrfTokenBadge

Автоматически валидирует CSRF-токены для этого аутентификатора во время аутентификации. Конструктор требует ID токена (уникальны для каждой формы) и CSRF-токен (уникальный для каждого запроса). См. Как реализовать CSRF-защиту.

PreAuthenticatedUserBadge

Означает, что этот пользователь был предварительно аутентифицирован (т.е. до запуска Symfony). Пропускает пред-аутентификационную проверку пользователей.

Например, если вы хотите добавить CSRF к вашему пользовательскому аутентификатору, вы запустите паспорт таким образом:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// src/Service/LoginAuthenticator.php
namespace App\Service;

// ...
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\CsrfTokenBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;

class LoginAuthenticator extends AbstractAuthenticator
{
    public function authenticate(Request $request): Passport
    {
        $password = $request->getPayload()->get('password');
        $username = $request->getPayload()->get('username');
        $csrfToken = $request->getPayload()->get('csrf_token');

        // ...

        return new Passport(
            new UserBadge($username),
            new PasswordCredentials($password),
            [new CsrfTokenBadge('login', $csrfToken)]
        );
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// ...
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;

class LoginAuthenticator extends AbstractAuthenticator
{
    // ...

    public function authenticate(Request $request): Passport
    {
        // ... обработать запрос

        $passport = new SelfValidatingPassport(new UserBadge($username), []);

        // установить пользовательский атрибут (например, область действия)
        $passport->setAttribute('scope', $oauthScope);

        return $passport;
    }

    public function createToken(Passport $passport, string $firewallName): TokenInterface
    {
        // прочитать значение атрибута
        return new CustomOauthToken($passport->getUser(), $passport->getAttribute('scope'));
    }
}