# Keycloak

## Overview

The source code and default configuration of the Building Block is available in our [code.syseleven.de](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/keycloakx>). Infos on release notes and new features please follow [Release notes Keycloak](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/keycloakx/-/blob/main/RELEASE-NOTES.md>)

## Building Block For Keycloak

With this Building Block we provide Keycloak, an open-source identity and access management solution designed to streamline user authentication and authorization for applications and services. Kubernetes resources are defined using the [Helm chart](<https://github.com/codecentric/helm-charts/tree/master/charts/keycloakx>) by [codecentric AG](<https://www.codecentric.de/>)

### Prerequisites

For the Keycloak setup to work out of the box a **PostgreSQL environment is required**.

#### Recommended setup

For the basic Keycloak deployed by the Building Block a resource overview is listed in the table below.

| CPU/vCPU | Memory |
| --- | --- |
| 1 | 2 GiB |

Adjust available resources based on the resource requirements of the Keycloak nodes.

## Adding The Building Block

Add the directory `keycloak` to your control repository. Add a `.gitlab-ci.yml` to the directory with the following content:

```yaml
include:
  - project: syseleven/building-blocks/helmfiles/keycloakx
    file: JobDevelopment.yaml
    ref: { { site.building_blocks.keycloakx.version|e } }
  - project: syseleven/building-blocks/helmfiles/keycloakx
    file: JobStaging.yaml
    ref: { { site.building_blocks.keycloakx.version|e } }
  - project: syseleven/building-blocks/helmfiles/keycloakx
    file: JobProduction.yaml
    ref: { { site.building_blocks.keycloakx.version|e } }
```

Remove environments you are not using by removing their include.

## Required Configuration

The Building Block expects the following environment variables

```bash
KEYCLOAKX_PG_DATABASE=keycloak
KEYCLOAKX_PG_HOSTNAME=syseleven-cnpg-cluster-rw.syseleven-cloudnative-pg
KEYCLOAKX_PG_USERNAME=keycloak
KEYCLOAKX_PG_PASSWORD=postgresql-password
KCX_HOSTNAME=kcx.example.com
KEYCLOAKX_ADMIN_PASSWORD=password
```

### Database Preparation

```sql
# Create role with name set in KEYCLOAKX_PG_USERNAME
postgres=# CREATE ROLE keycloak WITH LOGIN PASSWORD '<KEYCLOAKX_PG_PASSWORD>';

# Create database with name set in KEYCLOAKX_PG_DATABASE
postgres=# CREATE DATABASE keycloak WITH OWNER keycloak;
```

## Enable Ingress Incl. Let's Encrypt Certificate Via Certmanager

```yaml
# values-keycloakx.yaml

ingress:
  enabled: true
  rules:
    - host: "kcx.example.com"
      paths:
        - pathType: "Prefix"
          path: "/"
  ingressClassName: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-production"
  tls:
    - hosts: ["kcx.example.com"]
      secretName: "kcx.example.com-tls"
```
