开始使用

编辑此页

前提条件

此扩展包需要 Symfony 6.4+ 和 ext-openssl。

小提示： 虽然此扩展包没有强制要求你这样做，但强烈建议使用 HTTPS。

安装

添加 lexik/jwt-authentication-bundle 到你的 composer.json 文件

        1
        $ php composer.phar require "lexik/jwt-authentication-bundle"
    

注册扩展包

注册扩展包到 config/bundles.php (Flex 已经自动完成)

        1
2
3
4
        return [
    //...
    Lexik\Bundle\JWTAuthenticationBundle\LexikJWTAuthenticationBundle::class => ['all' => true],
];
    

生成 SSL 密钥

注意

对于此扩展包的 2.xx 版本，你可以使用 Web-Token 并生成 JSON Web Keys (JWK) 和 JSON Web Keysets (JWKSet) 而不是 PEM 编码的密钥。

请参考专门页面 Web-Token 功能获取更多信息。

        1
        $ php bin/console lexik:jwt:generate-keypair
    

你的密钥将位于 config/jwt/private.pem 和 config/jwt/public.pem (除非你配置了不同的路径)。

可用选项

--skip-if-exists 将在密钥已存在时静默地不做任何操作。
--overwrite 将在密钥已存在时覆盖你的密钥。

否则，将引发一个错误以防止你意外覆盖你的密钥。

配置

在你的 .env 中配置 SSL 密钥路径和密码

        1
2
3
        JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
JWT_PASSPHRASE=
    

        1
2
3
4
5
6
        # config/packages/lexik_jwt_authentication.yaml
lexik_jwt_authentication:
    secret_key: '%env(resolve:JWT_SECRET_KEY)%' # required for token creation
    public_key: '%env(resolve:JWT_PUBLIC_KEY)%' # required for token verification
    pass_phrase: '%env(JWT_PASSPHRASE)%' # required for token creation
    token_ttl: 3600 # in seconds, default is 3600
    

配置应用安全

注意

确保防火墙 login 放置在 api 之前，如果 main 存在，将其放在 api 之后，否则你将遇到 /api/login_check 路由未找到。

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
        # config/packages/security.yaml
security:
    enable_authenticator_manager: true # Only for Symfony 5.4
    # ...

    firewalls:
        login:
            pattern: ^/api/login
            stateless: true
            json_login:
                check_path: /api/login_check
                success_handler: lexik_jwt_authentication.handler.authentication_success
                failure_handler: lexik_jwt_authentication.handler.authentication_failure

        api:
            pattern:   ^/api
            stateless: true
            jwt: ~

    access_control:
        - { path: ^/api/login, roles: PUBLIC_ACCESS }
        - { path: ^/api,       roles: IS_AUTHENTICATED_FULLY }
    

配置应用路由

        1
2
3
        # config/routes.yaml
api_login_check:
    path: /api/login_check
    

API Platform 兼容性

如果检测到 API Platform，集成将使用你的安全配置完成。

如果你希望更改某些参数，你可以使用此配置进行更改

        1
2
3
4
5
6
7
        # config/packages/lexik_jwt_authentication.yaml
lexik_jwt_authentication:
    # ...
    api_platform:
        check_path: /api/login_check
        username_path: email
        password_path: security.credentials.password
    

用法

1. 获取令牌

第一步是使用用户的凭据验证用户身份。你可以使用如下简单的 curl 命令来测试获取令牌 (调整主机和端口)

Linux 或 macOS

        1
        $ curl -X POST -H "Content-Type: application/json" https://127.0.0.1/api/login_check -d '{"username":"johndoe","password":"test"}'
    

Windows

        1
        C:\> curl -X POST -H "Content-Type: application/json" https://127.0.0.1/api/login_check --data {\"username\":\"johndoe\",\"password\":\"test\"}
    

如果它工作正常，你将收到类似这样的内容

        1
2
3
        {
    "token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJleHAiOjE0MzQ3Mjc1MzYsInVzZXJuYW1lIjoia29ybGVvbiIsImlhdCI6IjE0MzQ2NDExMzYifQ.nh0L_wuJy6ZKIQWh6OrW5hdLkviTs1_bau2GqYdDCB0Yqy_RplkFghsuqMpsFls8zKEErdX5TYCOR7muX0aQvQxGQ4mpBkvMDhJ4-pE4ct2obeMTr_s4X8nC00rBYPofrOONUOR4utbzvbd4d2xT_tj4TdR_0tsr91Y7VskCRFnoXAnNT-qQb7ci7HIBTbutb9zVStOFejrb4aLbr7Fl4byeIEYgp2Gd7gY"
}
    

存储它 (客户端)，JWT 在其 TTL 过期之前 (默认 3600 秒) 是可重用的。

2. 使用令牌

只需在每次请求受保护的防火墙时传递 JWT，可以作为授权标头或作为查询参数。

默认情况下，仅启用授权标头模式：Authorization: Bearer {token}

请参阅配置参考文档以启用查询字符串参数模式或更改标头值前缀。

示例

请参阅功能性测试 JWT 保护的 API 文档或沙盒应用 Symfony4) 以获取完整的工作示例。

注意

关于令牌过期

令牌过期后的每个请求都将导致 401 响应。重新执行身份验证过程以获取新令牌。

也许你想使用 刷新令牌 来更新你的 JWT。在这种情况下，你可以查看 JWTRefreshTokenBundle。

处理 CORS 请求

这更多的是一个与 Symfony 相关的主题，但请参阅处理 CORS 请求文档以快速了解如何处理 CORS 请求。

模拟用户

对于使用 JWT 模拟用户，请参阅 https://symfony.ac.cn/doc/current/security/impersonating_user.html

Apache 用户的重要提示

正如此链接和这个链接中所述，Apache 服务器将剥离任何不是有效 HTTP BASIC AUTH 格式的 Authorization header。

如果你打算使用此扩展包的授权标头模式 (你应该这样做)，请将这些规则添加到你的 VirtualHost 配置中

        1
        SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
    