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/](http://localhost:9083/).
2. Once the page loads, ensure you are in the correct realm. The realm name is specified in the `.env` file:

   ![Change Realm](./images/client_secret/keycloak_change_realm.png)

3. To enable authentication:

   - Go to the `admin-cli` configuration:

     ![Admin CLI Access](./images/client_secret/keycloak_admin_cli.png)

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

     ![Set Authentication](./images/client_secret/keycloak_set_authentication.png)

   - 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).

     ![Get Client Secret](./images/client_secret/keycloak_get_client_secret.png)

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

![Client ID in Docker Compose](./images/client_secret/docker_compose_client_id.png)

## 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.

   ![Service Account Roles](./images/add_roles/keycloak_service_account_assign_role.png)

3. To simplify selection:

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

     ![Show 100 Roles](./images/add_roles/keycloak_assign_role_100_pages.png)

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

     ![Select All Roles](./images/add_roles/keycloak_service_accont_role_select_all.png)

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

   ![Role Account List](./images/add_roles/keycloak_service_account_list.png)

## 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.

![Navigate to app client ID](./images/redirect_uri/keycloak_add_redirect_uri.png)

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

![Add redirect URI](./images/redirect_uri/keycloak_add_new_redirect_uri.png)

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:

![Add redirect URI](./images/change_frontend_url.png)

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.

![Go to mail tab](./images/email_config/go_to_email_tab.png)

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

![Configure your SMTP](./images/email_config/configure_smtp.png)

## 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:

```yaml
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:

```bash
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:

```bash
psql -U <POSTGRES_USER> keycloak
```

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

```sql
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.