PH4H-app-backend/docs/keycloak-setup.md

Keycloak Setup

This guide explains how to configure the backend service to work with Keycloak. Throughout these instructions, we assume you are already logged in with the admin account.

Activate Authentication

Before using the API service, you must enable authentication and set the client ID so the backend can perform operations on Keycloak, such as registering users.

1. Open the Keycloak service at http://localhost:9083/.

2. Once the page loads, ensure you are in the correct realm. The realm name is specified in the .env file:

   

3. To enable authentication:

   • Go to the admin-cli configuration:

     

   • Scroll down to the Capability Config section and enable the two switches as shown below:

     

   • Click Save to apply the changes.

4. To retrieve the client credentials:

   • Navigate to the Credentials tab.

   • Copy the client secret value (it may be hidden by default).

     

This client secret is required in the Docker Compose file to configure the backend service. Add it to the appropriate section:

Set Roles for Backend Interaction

To allow the backend service to perform all necessary operations, the admin role must have all service account roles assigned.

1. Go to the Service Account Roles tab.

2. Click Apply Roles to assign roles.

   

3. To simplify selection:

   • Change the page size to show 100 roles per page:

     

   • Select all roles by clicking the checkbox in the table header:

     

4. After selecting all roles, click Assign. You should now see all roles listed as assigned:

   

Set Custom Redirect URI (Optional)

If you are not using the provided P4H4 application and plan to integrate with the Keycloak service directly, you must configure your own redirect URIs.

To do this:

1. Navigate to the Clients tab in Keycloak.
2. Select the app client ID.

3. Go to the Access Settings section.
4. Under Valid Redirect URIs, add your desired redirect URI.

5. Click Save to apply your changes.

This ensures your application can successfully handle authentication responses from Keycloak.

Set Frontend URL (for local development)

To test all Keycloak features in your local environment or when using IP addresses as domains, you need to configure the Frontend URL in your realm settings. You can do this by going to Realm Settings → General, as shown in the image below:

When working locally, do not use localhost. Instead, use 10.0.2.2.
This should point to the URL where Keycloak is running, so don’t forget to include the port.

Set Authenticationl email

For recover password and similar services, a SMTP email account must be set to send emails to users. To do this:

1. Ensure you are in lacpass realm.
2. Go to Realm settings tab on the botton left.
3. Go to Email tab.

4. On the bottom set your STMP credentials in the Connection & Authentication section and save.

Enable HTTP access

Warning

Do not use HTTP in Production, since this will expose users data. We recomended always use a secure HTTPS endpoint.

By default Keycloak supports to be hosted only in a HTTPS endpoint. If you host it in a HTTP endpoint, a error message will be displayed when trying to login into the webclient, and when trying yo authenticate an user.

To disable the required HTTPS, please add to docker/compose.yaml this environment variables for auth service, under the environments section:

environment:
  #...
  KC_HOSTNAME_STRICT: false
  KC_HOSTNAME_STRICT_HTTPS: false

This will tell keycloak to not require a HTTPS connection. But if you already build and started your keycloak service, this parameter is already saved into keycloak's database. To override it we need to go into the auth-db container.

To get inside the auth-db container, please run the next command in the project root folder:

docker compose exec -it auth-db sh

This will start initialize a shell console inside the container. Then to connect to the database run the following command, where <POSTGRES_USER> is the enviroment variable in your .env file:

psql -U <POSTGRES_USER> keycloak

This will connect you into a Postgres console inside the keycloak database. Finally run

UPDATE realm SET ssl_required='NONE' WHERE name='master';
UPDATE realm SET ssl_required='NONE' WHERE name='lacpass';

This will update the keycloak parameters to not required HTTPS.

To exit just run exit twice, one to get out of Postgres and a second time to get out of the container.