txs-keycloak/README.md

# TXS - Keycloak

Sistema de autenticación basado en Keycloak, que permite a los usuarios de TXS / EDUCATIC cambiar de servicio sin necesidad de volver a autenticarse, facilitando la integración.

## Instalación y ejecución

El proyecto solamente necesita un motor de contenedores (actualmente Docker) y que se habiliten las `units` de `systemd` para que se ejecute periódicamente el servicio de renovación de certificados de _Let's Encrypt_.

### Crear el espacio de trabajo

Copia el contenido de este repositorio sobre el directorio de instalación de tu preferencia.

> Los scripts están preparados para trabajar desde `/opt`, por lo que si escoges instalar en otra ubicación, deberás modificar los ficheros `docker-compose.yaml`, `certbot/certbot-keycloak.service` y `certbot/certbot-keycloak.sh` a conveniencia.

### Configuración

#### Keycloak

El servicio de _Keycloak_ se inicia con `docker-compose`, pero hay configurar algunos parámetros.

Antes de la ejecución, rellena las variables de configuración necesarias. Hay una plantilla de ejemplo en `.env-sample`. Utiliza esa plantilla como base y guárdala con el nombre `.env`. Dentro encontrarás las variables de configuración que se utilizan en el fichero de `docker-compose`. Ajústalas como corresponda.

#### Certbot

_Keycloak_ se ejecuta en un contenedor no accesible desde internet y sin usar cifrado, para permitir que las personas que administran el servicio puedan capturar tráfico y depurar problemas del servicio, en caso necesario.

De cara a internet, el servicio se ofrece tras un proxy NGINX, que hace de terminador TLS. El certificado que se requiere para ello se genera con _Let's Encrypt_ y tiene que renovarse con cierta frecuencia. Se utiliza el contenedor de _Certbot_ para gestionar las renovaciones y el sistema se apoya en un script que copia los certificados nuevos sobre el espacio de trabajo de NGINX para que se utilicen en cuanto se reciben.

En el directorio de `certbot` hay un subdirectorio `renewal` que contiene un fichero de ejemplo con la configuración que se necesita para la renovación automática. El fichero de ejemplo se llama `acceso.txs.es.conf-sample` y puede servir de plantilla para que configures el real, que deberá llamarse `acceso.txs.es.conf`

#### Scripts de inicio

El servicio _Keycloak_ se inicia ejecutando:

```bash
root@server:/opt$ docker-compose up -d
```

Además, hay que instalar y activar las `units` de `systemd` para que el servicio de `certbot` se ejecute periódicamente:

```bash
root@server:/etc/systemd/system$ ln -s /opt/certbot/certbot-keycloak.service
root@server:/etc/systemd/system$ ln -s /opt/certbot/certbot-keycloak.timer
root@server:/etc/systemd/system$ systemctl daemon-reload
root@server:/etc/systemd/system$ systemctl enable certbot-keycloak.service cerbot-keycloak.timer
root@server:/etc/systemd/system$ systemctl start cerbot-keycloak.timer
```
Crear estructura del README principal, con instrucciones de instalación 2022-09-12 22:25:14 +02:00			`# TXS - Keycloak`
Initial commit 2022-09-12 21:57:17 +02:00
[U] . 2022-09-20 10:38:19 +02:00			`Sistema de autenticación basado en Keycloak, que permite a los usuarios de TXS / EDUCATIC cambiar de servicio sin necesidad de volver a autenticarse, facilitando la integración.`
Crear estructura del README principal, con instrucciones de instalación 2022-09-12 22:25:14 +02:00
			`## Instalación y ejecución`

Documentar la instalación y arranque de los servicios 2022-09-13 02:06:57 +02:00			El proyecto solamente necesita un motor de contenedores (actualmente Docker) y que se habiliten las `units` de `systemd` para que se ejecute periódicamente el servicio de renovación de certificados de _Let's Encrypt_.

Crear estructura del README principal, con instrucciones de instalación 2022-09-12 22:25:14 +02:00			`### Crear el espacio de trabajo`

[U] . 2022-09-20 10:38:19 +02:00			`Copia el contenido de este repositorio sobre el directorio de instalación de tu preferencia.`

			> Los scripts están preparados para trabajar desde `/opt`, por lo que si escoges instalar en otra ubicación, deberás modificar los ficheros `docker-compose.yaml`, `certbot/certbot-keycloak.service` y `certbot/certbot-keycloak.sh` a conveniencia.
Documentar la instalación y arranque de los servicios 2022-09-13 02:06:57 +02:00
Crear estructura del README principal, con instrucciones de instalación 2022-09-12 22:25:14 +02:00			`### Configuración`

			`#### Keycloak`

[U] . 2022-09-20 10:38:19 +02:00			El servicio de _Keycloak_ se inicia con `docker-compose`, pero hay configurar algunos parámetros.
[U] . 2022-09-20 10:25:36 +02:00
			Antes de la ejecución, rellena las variables de configuración necesarias. Hay una plantilla de ejemplo en `.env-sample`. Utiliza esa plantilla como base y guárdala con el nombre `.env`. Dentro encontrarás las variables de configuración que se utilizan en el fichero de `docker-compose`. Ajústalas como corresponda.
Documentar la instalación y arranque de los servicios 2022-09-13 02:06:57 +02:00
Crear estructura del README principal, con instrucciones de instalación 2022-09-12 22:25:14 +02:00			`#### Certbot`

[U] . 2022-09-20 10:27:51 +02:00			`_Keycloak_ se ejecuta en un contenedor no accesible desde internet y sin usar cifrado, para permitir que las personas que administran el servicio puedan capturar tráfico y depurar problemas del servicio, en caso necesario.`
Documentar la instalación y arranque de los servicios 2022-09-13 02:06:57 +02:00
			`De cara a internet, el servicio se ofrece tras un proxy NGINX, que hace de terminador TLS. El certificado que se requiere para ello se genera con _Let's Encrypt_ y tiene que renovarse con cierta frecuencia. Se utiliza el contenedor de _Certbot_ para gestionar las renovaciones y el sistema se apoya en un script que copia los certificados nuevos sobre el espacio de trabajo de NGINX para que se utilicen en cuanto se reciben.`

			En el directorio de `certbot` hay un subdirectorio `renewal` que contiene un fichero de ejemplo con la configuración que se necesita para la renovación automática. El fichero de ejemplo se llama `acceso.txs.es.conf-sample` y puede servir de plantilla para que configures el real, que deberá llamarse `acceso.txs.es.conf`

			`#### Scripts de inicio`

			`El servicio _Keycloak_ se inicia ejecutando:`

			```bash
			`root@server:/opt$ docker-compose up -d`
			```

			Además, hay que instalar y activar las `units` de `systemd` para que el servicio de `certbot` se ejecute periódicamente:

			```bash
			`root@server:/etc/systemd/system$ ln -s /opt/certbot/certbot-keycloak.service`
			`root@server:/etc/systemd/system$ ln -s /opt/certbot/certbot-keycloak.timer`
			`root@server:/etc/systemd/system$ systemctl daemon-reload`
			`root@server:/etc/systemd/system$ systemctl enable certbot-keycloak.service cerbot-keycloak.timer`
			`root@server:/etc/systemd/system$ systemctl start cerbot-keycloak.timer`
			```