Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Tweaks and improvements #1011

Merged
merged 1 commit into from
Apr 23, 2022
Merged

[Docs] Tweaks and improvements #1011

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
289 changes: 144 additions & 145 deletions Resources/doc/1-configuration-reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,88 +8,88 @@ Minimal configuration
~~~~~~~~~~~~~~~~~~~~~

Using RSA/ECDSA
^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~

.. code-block:: yaml

# 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'
# 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
^^^^^^^^^^
~~~~~~~~~~

.. code-block:: yaml

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

Full default configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

# 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
# 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 <https://github.com/lcobucci/jwt>`__ library.
Expand All @@ -101,11 +101,11 @@ which is based on the great
`web-token/jwt-framework <https://github.com/web-token/jwt-framework>`__
library.

To create your own encoder service, see the `JWT encoder service
customization chapter <5-encoder-service>`__.
To create your own encoder service, see the
:doc:`JWT encoder service customization chapter </5-encoder-service>`.

signature_algorithm
'''''''''''''''''''
...................

One of the algorithms supported by the default encoder for the
configured `crypto engine <#crypto_engine>`__.
Expand All @@ -115,87 +115,86 @@ configured `crypto engine <#crypto_engine>`__.
- 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 <https://github.com/lexik/LexikJWTAuthenticationBundle/pull/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
.. code-block:: yaml

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 <https://medium.com/lightrail/getting-token-authentication-right-in-a-stateless-single-page-application-57d0c6474e3>`__.
this approach are in
`this post <https://medium.com/lightrail/getting-token-authentication-right-in-a-stateless-single-page-application-57d0c6474e3>`__.

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 <https://caniuse.com/#feat=same-site-cookie-attribute>`__
Keep in mind, that SameSite attribute is **not supported** in
`some browsers <https://caniuse.com/#feat=same-site-cookie-attribute>`__

.. code-block:: yaml

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
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 <https://medium.com/lightrail/getting-token-authentication-right-in-a-stateless-single-page-application-57d0c6474e3>`__,
Keep in mind, this invalidates a requirement from the
`previously mentioned post <https://medium.com/lightrail/getting-token-authentication-right-in-a-stateless-single-page-application-57d0c6474e3>`__,
namely "JavaScript/front-end should never have access to the full JWT".

::
.. code-block:: yaml

remove_token_from_body_when_cookies_used: false
remove_token_from_body_when_cookies_used: false

Security configuration
----------------------
Expand All @@ -204,41 +203,41 @@ For Symfony 5.3 and higher, use the ``jwt`` authenticator:

.. code-block:: yaml

# config/packages/security.yaml
security:
enable_authenticator_manager: true
firewalls:
api:
# ...
jwt: ~ # enables 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)
# ...
# 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:

.. code-block:: yaml

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

Authenticator
'''''''''''''
.............

For more details about using custom authenticator in your application,
see :doc:`"Extending JWT Authenticator" </6-extending-jwt-authenticator>`.
see :doc:`Extending JWT Authenticator </6-extending-jwt-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 :doc:`"A database less
user provider" </8-jwt-user-provider>`.
instead of reloading the user from the database), see
:doc:`"A database less user provider" </8-jwt-user-provider>`.
Loading