Download the PHP package mainick/keycloak-client-bundle without Composer

KeycloakClientBundle

The KeycloakClientBundle bundle is a wrapper for the stevenmaguire/oauth2-keycloak package, designed to simplify Keycloak integration into your application in Symfony and provide additional functionality for token management and user information access. It also includes a listener to verify the token on every request.

Configuration

Before installing this package, you need to configure it manually. You can do this by creating a mainick_keycloak_client.yaml file in the config/packages directory of your project and adding the following configuration:

Additionally, it's recommended to add the following environment variables to your project's environment file (e.g., .env or .env.local) with the appropriate values for your configuration:

Make sure to replace the placeholder values with your actual configuration values. Once you have configured the package and environment variables, you can proceed with the installation.

Installation

You can install this package using Composer:

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:

By configuring the package before installation, you ensure that it will be ready to use once installed.

Usage

Get the Keycloak client

You can get the Keycloak client by injecting the Mainick\KeycloakClientBundle\Interface\IamClientInterface interface in your controller or service.

To use it, you need to add the following configuration to your config/services.yaml file:

Then, you can use it in your controller or service:

Perform the desired operations, such as retrieving additional user claims, assigned roles, associated groups, etc.

Token Verification Listener

The KeycloakClientBundle includes a built-in listener, TokenAuthListener, that automatically validates the JWT token on every request, ensuring the security and validity of your Keycloak integration. This listener seamlessly handles token validation, allowing you to focus on your application's logic.

Using TokenAuthListener

In your Symfony project, add the TokenAuthListener to your config/services.yaml file as a registered service and tag it as a kernel.event_listener. This will enable the listener to trigger on every request.

Retrieve user information

Additionally, the TokenAuthListener adds an user attribute to the Symfony request object, which contains the UserRepresentationDTO object.

This user attribute contains the user information fetched from the JWT token and is an instance of the UserRepresentationDTO class. This allows your application to easily access user-related data when processing requests.

Excluding Routes from Token Validation

TokenAuthListener verifies the token for all incoming requests by default. However, if you have specific routes for which you want to exclude token validation, you can do so using the ExcludeTokenValidationAttribute attribute.

To exclude token validation for a particular route, apply the ExcludeTokenValidationAttribute to the corresponding controller method.

When the ExcludeTokenValidationAttribute is applied to a method, TokenAuthListener will skip token validation for requests to that specific route.

Symfony Security Configuration

Bundle configuration

To use the KeycloakClientBundle with Symfony's security component, you need to configure the security system to use the Keycloak client.

First you need to add a new section to the bundle configuration file:

Then you need to configure the Keycloak redirect uri to the mainick_keycloak_security_auth_connect_check bundle route, which redirects to the default route or referer route after successful login.

It's recommended to change the following environment variable to your project's environment file (e.g., .env or .env.local) with the uri. The same URI must be configured in the Keycloak application client:

Below is the complete configuration file:

Route configuration

Create a new file in to load pre configured bundle routes.

Security configuration

Then you need to configure the security system to use the Keycloak client. You can do this by adding the following configuration to your config/packages/security.yaml file to use the bundle's UserProvider:

Here is a simple configuration that restrict access to routes only to user with roles "ROLE_USER" or "ROLE_ADMIN" :

Logout

To logout the user, you can use the following code:

or create a link in your twig template:

This will redirect the user to the Keycloak logout page, where the user will be logged out from the Keycloak server.

Redirect after login

To redirect the user to a specific route after login, you can set the TARGET_ROUTE_NAME environment variable to the desired route name.

This will redirect the user to the app_home route after a successful login.

Troubleshooting - You have Access Denied in your browser

If you have an Access Denied error in your browser, it is maybe because scope roles is misconfigured.

For correction:

1. Check whether the ROLE_ADMIN and ROLE_USER roles have been created for the application client.
2. Click on Client scopes on left panel, then roles:
3. Click on Mappers tab, then client roles:
4. Disabled Add to userinfo, click on Save, then enabled Add to userinfo and click on Save:

Please check the roles assigned to the user in Keycloak and the roles configured in the Symfony security configuration.

Running the Tests

Install the Composer dependencies:

Then run the test suite:

Author

• Maico Orazio

License

The MIT License (MIT). Please see License File for more information.

Contributing

We welcome your contributions! If you wish to enhance this package or have found a bug, feel free to create a pull request or report an issue in the issue tracker.

Please see CONTRIBUTING for details.