Secure JWT Bundle

Symfony bundle that makes JWT more secure

Install

Installation is not fluent and error free yet, but it is easy to work around:

composer require connectholland/secure-jwt-bundle

Will give error in post installation:

Cannot autowire service "ConnectHolland\SecureJWTBundle\EventSubscriber\LoginSubscriber": argument "$googleAuthenticator" of method "__construct()" references class "Scheb\TwoFactorBundle\Security\TwoFactor\Provider\Google\GoogleAuthenticator" but no such service exists.

Configure scheb twofactor Google:

In the scheb_two_factor.yaml file:

scheb_two_factor:
    security_tokens:
        - Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken
    google:
        enabled: true
        server_name: Secure Server
        issuer: Connect Holland
        digits: 6
        window: 1

Run

composer require connectholland/secure-jwt-bundle

Again to finish the installation.

BTW1: Installation and configuration of the scheb twofactor bundle before installation of this bundle will also prevent this error.
BTW2: of course a PR that fixes these issues is welcome :)

Cookie storage

Tokens in local storage are insecure, so if you use tokens from a web interface you should store them somewhere else. A secure cookie is a good location. Configure cookie storage as follows:

Let the lexik/jwt-authentication-bundle look at cookies:

In the lexik_jwt_authentication.yaml config file:

lexik_jwt_authentication:
    secret_key: '%env(resolve:JWT_SECRET_KEY)%'
    public_key: '%env(resolve:JWT_PUBLIC_KEY)%'
    pass_phrase: '%env(JWT_PASSPHRASE)%'

    token_extractors:
            # Default header auth, can be useful to allow for other auth types (for example /api)
            authorization_header:
                enabled: true

            # Make sure this is enabled
            cookie:
                enabled: true
                name:    BEARER
                set_cookies:
                    BEARER: ~

Make sure the token is set as a secure cookie

In the security.yaml config file:

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

Invalidate tokens

By default tokens are valid until they expire. This makes is impossible to really log out. You can configure token invalidatation to allow logouts:

Create database table

In the doctrine.yaml file:

doctrine:
    orm:
        mappings:
            ConnectHolland\SecureJWTBundle:
                is_bundle: true
                type: annotation
                dir: '%kernel.project_dir%/vendor/connectholland/secure-jwt-bundle/src/Entity'
                prefix: 'ConnectHolland\SecureJWTBundle\Entity'
                alias: SecureJWTBundle

And run migrations:

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate -n

Configure API endpoint logout

In the api_platform.yaml file:

api_platform:
    mapping:
        paths: ['%kernel.project_dir%/vendor/connectholland/secure-jwt-bundle/src/Message']

Of course do not remove other required paths that might already be in the paths configuration.

There will be a logout endpoint in your API. This endpoint requires a message formatted like:

{
  "logout": "some string"
}

The value of logout is not important and not used. This field is required because API platform requires at least one field in the message. (A better solution for this is welcome).

Do not allow invalidated tokens

In the security.yaml file:

    api:
        pattern: ^/api
        stateless: true
        anonymous: true
        guard:
            authenticators:
                - ConnectHolland\SecureJWTBundle\Security\Guard\JWTTokenAuthenticator

Two Factor Authentication in JWT

Configure Google Authenticator

In the scheb_two_factor.yaml file:

scheb_two_factor:
    security_tokens:
        - Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken
    google:
        enabled: true
        server_name: Secure Server
        issuer: Connect Holland
        digits: 6
        window: 1

Use the two_factor_jwt security listener and provider

In the security.yaml file:

    login:
        pattern:  ^/api/login
        stateless: true
        anonymous: true        
        two_factor_jwt:
            check_path:               /api/login_check
            success_handler:          ConnectHolland\SecureJWTBundle\Security\Http\Authentication\AuthenticationSuccessHandler
            failure_handler:          ConnectHolland\SecureJWTBundle\Security\Http\Authentication\AuthenticationFailureHandler

Implement the right interfaces

Your User object should implement ConnectHolland\SecureJWTBundle\Entity\TwoFactorUserInterface.

Using 2FA

curl -X POST http://host/api/users/authenticate -H 'Content-Type: application/json' -d '{"username": "username", "password": "password"}'

This will give the following response:

{
  "result":"ok",
  "status":"two factor authentication required"
}

If 2FA is not yet setup you will receive:

{
  "result":"ok",
  "message":"use provided QR code to set up two factor authentication",
  "qr":"QR code (data URL)"
}

In the next call add the two factor challenge:

curl -X POST http://host/api/users/authenticate -H 'Content-Type: application/json' -d '{"username": "username", "password": "password", "challenge": "123456"}'

If correct you'll receive:

{
  "result":"ok"
}

The response headers will include a secure cookie containing the JWT token to allow future authenticated calls.

2FA Remember this device

The remember device functionality allows users to skip the 2fa for a configurable amount of days. The default configuration is set to false, which means it doesn't set a REMEMBER_DEVICE cookie after logging in. The default amount of days is set to 30.

To configure:

In the config/packages folder of the root project create a new file called: connect_holland_secure_jwt.yaml

In this file the configuration can be set:

connect_holland_secure_jwt:
  is_remembered: true
  expiry_days: 14

As mentioned before, after logging in a REMEMBER_DEVICE cookie will be set. It will contain a unix expiry time and the email of the user.

Besides placing the cookie it will be persisted in the: secure_jwt_remember_device_token table. This entity can be found in src/Entity/RememberDeviceToken.php

Recover codes

You can retrieve recovery codes for 2FA which allow you to reset 2FA. If a valid recovery code is entered as challenge, 2FA will be reset and you'll get a QR code response.