112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
ABELkeycloakBearerOnlyAdapterBundle
|
|
===================================
|
|
|
|
This Symfony bundle is an adapter that allows securing API using keycloak Bearer Only clients.
|
|
|
|
## Installation
|
|
|
|
> 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
|
|
```
|
|
|
|
## Configuration
|
|
|
|
If you want to set up keycloak locally you can download it [here](https://www.keycloak.org/downloads) and follow instructions from [the official documentation](https://www.keycloak.org/docs/latest/server_installation/index.html).
|
|
|
|
### 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
|
|
```
|
|
|
|
#### Manual
|
|
Having a running keycloak locally or in Docker and already configured a client with **Access Type = bearer-only**
|
|
here is the configuration to use:
|
|
|
|
```yaml
|
|
# config/packages/abel_keycloak_bearer_only_adapter.yaml
|
|
abel_keycloak_bearer_only_adapter:
|
|
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 ###
|
|
OAUTH_KEYCLOAK_ISSUER=keycloak:8080
|
|
OAUTH_KEYCLOAK_REALM=my_realm
|
|
OAUTH_KEYCLOAK_CLIENT_ID=my_bearer_client
|
|
OAUTH_KEYCLOAK_CLIENT_SECRET=my_bearer_client_secret
|
|
###< 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 <br>
|
|
> The new distribution introduces a number of breaking changes, including: <br>
|
|
> - `/auth` removed from the default context path <br>
|
|
> ⚠️ **If you are using a legacy version make sure to include /auth in OAUTH_KEYCLOAK_ISSUER** <br>
|
|
> 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** :
|
|
|
|
```yaml
|
|
# config/packages/security.yaml
|
|
security:
|
|
enable_authenticator_manager: true
|
|
providers:
|
|
keycloak_bearer_user_provider:
|
|
id: ABEL\Bundle\keycloakBearerOnlyAdapterBundle\Security\User\KeycloakBearerUserProvider
|
|
firewalls:
|
|
dev:
|
|
pattern: ^/(_(profiler|wdt)|css|images|js)/
|
|
security: false
|
|
api:
|
|
pattern: ^/api/
|
|
provider: keycloak_bearer_user_provider
|
|
custom_authenticators:
|
|
- ABEL\Bundle\keycloakBearerOnlyAdapterBundle\Security\Authenticator\KeycloakBearerAuthenticator
|
|
stateless: true
|
|
access_control:
|
|
- { path: ^/api/, roles: ROLE_API }
|
|
```
|
|
> :information_source: Referring to Symfony [documentation](https://symfony.com/doc/5.3/security.html#roles), roles must start with **ROLE_** (otherwise, things won't work as expected)
|
|
### Keycloak configuration
|
|
|
|
To configure keycloak to work with this bundle, [here](./Resources/docs/keycloak-config-guide.md) is a step by step documentation for a basic configuration of keycloak.
|
|
|
|
### Compatibility
|
|
|
|
|
|
| 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 |
|