1-configuration-reference.md

Configuration reference

Bundle configuration

Minimal configuration

Using RSA/ECDSA

# config/packages/lexik_jwt_authentication.yaml
#...
lexik_jwt_authentication:
    secret_key: '%kernel.project_dir%/config/jwt/private.pem' # path to the secret key OR raw secret key, required for creating tokens
    public_key: '%kernel.project_dir%/config/jwt/public.pem'  # path to the public key OR raw public key, required for verifying tokens
    pass_phrase: 'yourpassphrase' # required for creating tokens
    # Additional public keys are used to verify signature of incoming tokens, if the key provided in "public_key" configuration node doesn't verify the token
    additional_public_keys:
        - '%kernel.project_dir%/config/jwt/public1.pem'
        - '%kernel.project_dir%/config/jwt/public2.pem'
        - '%kernel.project_dir%/config/jwt/public3.pem'

Using HMAC

#  config/packages/lexik_jwt_authentication.yaml
#...
lexik_jwt_authentication:
    secret_key: yoursecret

Full default configuration

# config/packages/lexik_jwt_authentication.yaml
# ...
lexik_jwt_authentication:
    secret_key: ~
    public_key: ~
    pass_phrase: ~
    token_ttl: 3600 # token TTL in seconds, defaults to 1 hour
    user_identity_field: username  # key under which the user identity will be stored in the token payload
    clock_skew: 0

    # token encoding/decoding settings
    encoder:
        # token encoder/decoder service - default implementation based on the lcobucci/jwt library
        service:            lexik_jwt_authentication.encoder.lcobucci

        # encryption algorithm used by the encoder service
        signature_algorithm: RS256

    # token extraction settings
    token_extractors:
        # look for a token as Authorization Header
        authorization_header:
            enabled: true
            prefix:  Bearer
            name:    Authorization

        # check token in a cookie
        cookie:
            enabled: false
            name:    BEARER
            
        # check token in query string parameter
        query_parameter:
            enabled: false
            name:    bearer
        
        # check token in a cookie
        split_cookie:
            enabled: false
            cookies:
                - jwt_hp
                - jwt_s
                
    # remove the token from the response body when using cookies
    remove_token_from_body_when_cookies_used: true

Encoder configuration

service

Defaults to lexik_jwt_authentication.encoder.lcobucci which is based on the Lcobucci/JWT library.

For an advanced token encoding with higher encryption support, please see the Spomky-Labs/lexik-jose-bridge which is based on the great web-token/jwt-framework library.

To create your own encoder service, see the JWT encoder service customization chapter.

signature_algorithm

One of the algorithms supported by the default encoder for the configured crypto engine.

• HS256, HS384, HS512 (HMAC)
• RS256, RS384, RS512 (RSA)
• ES256, ES384, ES512 (ECDSA)

Automatically generating cookies

You are now able to automatically generate secure and httpOnly cookies when the cookie token extractor is enabled #753.

token_extractors: 
    cookie: 
        enabled: true
        name: BEARER
# ...
set_cookies:
    BEARER: ~

# Full config with defaults:
#  BEARER:
#      lifetime: null (defaults to token ttl)
#      samesite: lax
#      path: /
#      domain: null (null means automatically set by symfony)
#      secure: true (default to true)
#      httpOnly: true

Automatically generating split cookies

You are also able to automatically generate split cookies. Benefits of this approach are in this post.

Set the signature cookie (jwt_s) lifetime to 0 to create session cookies.

Keep in mind, that SameSite attribute is not supported in some browsers

token_extractors:
    split_cookie:
        enabled: true
        cookies:
            - jwt_hp
            - jwt_s

set_cookies:
    jwt_hp:
        lifetime: null
        samesite: strict
        path: /
        domain: null
        httpOnly: false
        split:
            - header
            - payload

    jwt_s:
        lifetime: 0
        samesite: strict
        path: /
        domain: null
        httpOnly: true
        split:
            - signature

Keep the token in the body when using cookies

When using cookies the response defaults to an empty body and result code 204. It is possible to modify this behaviour.

Keep in mind, this invalidates a requirement from the previously mentioned post, namely "JavaScript/front-end should never have access to the full JWT".

remove_token_from_body_when_cookies_used: false

Security configuration

For Symfony 5.3 and higher, use the jwt authenticator:

# config/packages/security.yaml
security:
    enable_authenticator_manager: true
    firewalls:
        api:
            # ...
            jwt: ~ # enables the jwt authenticator

        # Full config with defaults:
        #    jwt:
        #        provider: null  (you can put provider here or just ignore this config)
        #        authenticator: lexik_jwt_authentication.security.jwt_authenticator (default jwt authenticator)
        # ...

For Symfony versions prior to 5.3, use the Guard authenticator:

    firewalls:
        # ...
        api:
            # ...
            guard:
                authenticators:
                    - 'lexik_jwt_authentication.jwt_token_authenticator'

authenticator

For more details about using custom authenticator in your application, see "Extending Authenticator"

database-less user provider

For a database-less authentication (i.e. trusting into the JWT data instead of reloading the user from the database), see "A database less user provider".