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

Паспорт - це обʼєкт, який містить користувача, який буде аутентифікований, а також інші частини інформації, на кшталт того, чи має бути перевірений пароль, або чи має бути підключена функція "запамʼятати мене".

За замовчуванням, 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), []);

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

        return $passport;
    }

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