Keycloak security adapter for bearer only clients

v1.3.2 2023-02-20 13:28 UTC

This package is auto-updated.

Last update: 2023-05-20 14:00:53 UTC


This Symfony bundle is an adapter that allows securing API using keycloak Bearer Only clients.


Befor installing the bundle, automatic packages configuration can be activated with the following command:

composer config extra.symfony.allow-contrib true

With composer:

composer require abel/keycloak-bearer-only-adapter-bundle


If you want to set up keycloak locally you can download it here and follow instructions from the official documentation.

Bundle configuration

Via a recipe (Automatic)

This bundle hase a Symfony recipe that allow the automation of configuration via the Symfony Flex Composer plugin. To enable recipe for your project, run the following command:

composer config extra.symfony.allow-contrib true


Having a running keycloak locally or in Docker and already configured a client with Access Type = bearer-only here is the configuration to use:

# config/packages/abel_keycloak_bearer_only_adapter.yaml
    issuer: '%env(OAUTH_KEYCLOAK_ISSUER)%' # your accessible keycloak url
    realm: '%env(OAUTH_KEYCLOAK_REALM)%' # your keycloak realm name
    client_id: '%env(OAUTH_KEYCLOAK_CLIENT_ID)%' # your keycloak client id
    client_secret: '%env(OAUTH_KEYCLOAK_CLIENT_SECRET)%' # your keycloak client secret
    #ssl_verification: False # by default ssl_verification is set to False

The best practice is to load your configuration from .env file.

# .env
###> Abel_keycloak_bearer_only_adapter ###
###< Abel_keycloak_bearer_only_adapter ###

Since Keycloak 17 the default distribution is now powered by Quarkus, while the legacy WildFly powered distribution will still be around until June 2022
The new distribution introduces a number of breaking changes, including:

  • /auth removed from the default context path
    ⚠️ If you are using a legacy version make sure to include /auth in OAUTH_KEYCLOAK_ISSUER
    Example: keycloak:8080/auth

In case of using Keycloak with Docker locally replace issuer value with your keycloak container reference in the network

For example, you can use the service name, or container IPAdresse that you can get using this command:

docker inspect <container id> | grep "IPAddress"

Symfony security configuration

To secure your API with Keycloak you must change the default security configuration in symfony.

Here is a simple configuration that restrict access to /api/* routes only to user with role ROLE_API :

# config/packages/security.yaml
    enable_authenticator_manager: true
            id: ABEL\Bundle\keycloakBearerOnlyAdapterBundle\Security\User\KeycloakBearerUserProvider
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
            pattern: ^/api/
            provider: keycloak_bearer_user_provider
              - ABEL\Bundle\keycloakBearerOnlyAdapterBundle\Security\Authenticator\KeycloakBearerAuthenticator
            stateless: true
        - { path: ^/api/, roles: ROLE_API }

ℹ️ Referring to Symfony documentation, roles must start with ROLE_ (otherwise, things won't work as expected)

Keycloak configuration

To configure keycloak to work with this bundle, here is a step by step documentation for a basic configuration of keycloak.


Bundle Version Symfony Version
V1.0.1 >=4.0.0 <5.0.0
V1.1.* (uses old authentication systeme with guard) >=5.0.0 <6.0.0
V1.2.* (uses new authentication systeme) >=5.3.0 <6.0.0
V1.3.* >=6.0.0 <7.0.0