Datamite BO

This repository contains a back office for content management and an API to be consumed by an external service. Access to the back office is protected by Keycloak SSO authentication.

Technology

• Laravel 11
• PHP 8.2
• PHP GD Extension
• MySQL Database

Installed Packages

The following packages have been installed:

• laravel/socialite and socialiteproviders/keycloak, responsible for handling authentication.
• zircote/swagger-php and darkaonline/l5-swagger for generating API documentation.
• intervention/image for converting images to webp format.

Installation

Run composer install to install dependencies.

Create a MySQL database.

Create the .env file based on .env.example or from a provided one, and edit the necessary configurations, especially database settings.

Add/edit the configurations in .env related to Keycloak authentication.

#Keycloak
KEYCLOAK_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxx
KEYCLOAK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxx
KEYCLOAK_REDIRECT_URI=YOUR_APP_URL/login/callback
KEYCLOAK_BASE_URL=https://keycloak.datamite.com/
KEYCLOAK_REALM=xxxxxxxxxxxxxxxxxxxxxxxxxxx
KEYCLOAK_BACKOFFICE_ROLE=xxxxxxxxxxxxxxxxx
KEYCLOAK_FRONTAPP_ROLE=xxxxxxxxxxxxxxxxx
KEYCLOAK_FRONTLOGIN_CALLBACK=YOUR_APP_URL/app/login/callback
FRONT_APP_URL=URL_DO_FRONT

KEYCLOAK_BASE_URL= must be filled with the keycloak instalation url and may require /auth/ depending on the Keycloak version. In the latest version, this is not required.

KEYCLOAK_BACKOFFICE_ROLE= and KEYCLOAK_FRONTAPP_ROLE= should be client roles, not realm roles. Otherwise, code and documentation refactoring may be necessary. This information should be available in the Keycloak client scopes returned information.

In the previous example, YOUR_APP_URL is the URL of this project installation.

Keycloak Configuration

After creating the client for the back office in Keycloak, it is necessary to assign the backoffice client role you created to the users who should have access.

Additionally, you must create a mapper in the Keycloak client with the following configuration (use exactly as written):

resource_access.{client_id}.roles

This ensures that the user's roles are included in the token and can be validated by the application.

Create client role “backoffice”

Clients -> edit -> roles -> add role “backoffice”
 
Clients -> edit -> client scopes -> (first item, description = Dedicated scope and mappers for this client) -> mapper -> 
Token Claim Name: resource_access.{client_id}.roles
Add to ID token -> check
Add to access token -> check
Add to userinfo -> check

Database instalation

If a database is provided, the following steps are not necessary.

Otherwise, run the following commands to create the database tables and prepopulate some data: php artisan migrate php artisan db:seed to create languages and modules.

Features

User Stories related to backoffice

US1: As a Content Administrator, I want to log in to the back office, so I can manage relevant content for the application.

US2: As a Content Administrator, I want to manage FAQs, so they can be shown in the application.

US3: As a Content Administrator, I want to manage translations, so they can be used in the application.

US4: As a Content Administrator, I want to manage banners/ads, so they can be shown in the application.

US5: As a Content Administrator, I want to change module statuses, so that the active ones can be shown in the application.

Frontend Service Authentication

The URL for authentication of the application consuming the API is URL/app/login/

The authentication flow is as follows:

API

API documentation is available at URL/api/documentation

The OpenAPI configuration file can be downloaded from URL/docs/api-docs.json

Relevant Links

• https://socialiteproviders.com/Keycloak/
• https://medium.com/@mark.tabletpc/set-up-laravel-with-swagger-for-comprehensive-api-documentation-step-by-step-instructions-d30552ca8051

License

License can be found here.