wiki/HowtoKeycloak.md

# Contexte

- Keycloak est un serveur d'authentification et d'autorisation écrit en Java, c'est un "Identity Access Manager" *IAM* open-source permettant de faire du Single-Sign-On et Single-Sign-Out *SS0*, c'est à dire d'utiliser un seul compte pour se (dé-)connecter à différents services.

- Keycloak supporte principalement 2 protocoles d'authentification

	- *SAML 2.0* (Security Assertion Markup Language)

		- authentification de l'utilisateur

			- SAML assertion (XML signé numeriquement par le royaume) contenant les information sur les accés de l'utilisateur

		- accés au service

			- via un SAML assertion

	- *OIDC* (OpenID Connect)

		- authentification de l'utilisateur

			- -> identity token : infos utilisateur qui l'indentifie

			- -> access token :  information sur les accés de l'utilisateur, signé numeriquement par le royaume

		- accés au service

			- via un access token

- [featureset et presentation](video https://www.youtube.com/watch?v=FyVHNJNriUQ?=8m30s)

# Installation

## En dur

- ressources

- [doc officielle](https://www.keycloak.org/getting-started/getting-started-zip)

- [git de keycloak](https://github.com/keycloak/keycloak/releases)

- Installer OpenJDK

-
  ```bash
  apt install openjdk-11-jre
  ```

- Lister les release

-
  ```bash
  git ls-remote --tags https://github.com/keycloak/keycloak
  ```

- Récupérer et extraire le zip de la release souhaité

-
  ```bash
  keycloak_release=21.1.1
  keycloak_zip=keycloak-${keycloak_release}.zip
  wget https://github.com/keycloak/keycloak/releases/download/${keycloak_release}/keycloak-${keycloak_release}.zip
  unzip $keycloak_zip
  ```

- Lancer keycloak depuis son dossier

-
  ```bash
  keycloak_folder=${keycloak_zip%".zip"}
  cd $keycloak_folder
  bin/kc.sh start-dev
  ```

## Brancher une base de donnée de prod

- [doc officielle configuration db](https://www.keycloak.org/server/db)

- Par defaut le schema `keyclaok` est utilisé

- **Mariadb**

- pour l'installation et plus de détails coir la [doc evolix installation de mariadb](https://wiki.evolix.org/HowtoMySQL)

- (Recommandé )créer une base de donnée et utilisateur associé pour keycloak voir

	-
	  ```bash
	  db_name=keycloak
	  user=evocloak
	  # mysqladmin create $db_name
	  # mysql
	  mysql> GRANT ALL PRIVILEGES ON $db_name.* TO '$user'@'%' IDENTIFIED BY '$password';
	  ```

- Démarrer le serveur keycloak et (re-)définit les options de configuration (depuis le dossier keycloak)

	-
	  ```bash
	  bin/kc.sh start --db mariadb --db-url-host mymariadb --db-username evocloak --db-password change_me
	  ```

## Haute disponibilité

- keycloak est conçu pour fonctionner en haute disponibilitée avec [infinispan](https://infinispan.org/) ( In-Memory Distributed Data Store)

- TODO https://www.keycloak.org/server/configuration-production -> https://www.keycloak.org/server/caching

# Utilisation

## Administration de Keycloak

- On supposera que nous nous trouvons dans le dossier d'installation keycloack

	-
	  ```bash
	  cd $keycloak_folder
	  ```

- Voir les option de démarrage / aide

	-
	  ```bash
	  bin/kc.sh start-dev --help
	  ```

- **Lancer Keycloak**

	- Lancer Keycloak en *dev* sur le port 8080

		-
		  ```bash
		  $keycloak_http_port=8080
		  bin/kc.sh start-dev --http-port ${keycloak_http_port}
		  ```

- **Créer un administrateur**

	- Au lancement du serveur

		-
		  ```bash
		  export KEYCLOAK_ADMIN=<username>
		  export KEYCLOAK_ADMIN_PASSWORD=<password>
		  bin/kc.sh start-dev
		  ```

	- En mode "click"

		- Se connecter à http://localhost:8080/

			- Créer un username et password admin

		- Se connecter à http://localhost:8080/admin avec les identifiant admin
		  id:: 6491bb83-8229-4bcd-a535-5c8da9f0e556

			- TODO suite avec capture d'ecran ? sinon voir [doc officielle](https://www.keycloak.org/getting-started/getting-started-zip)

## Gestion des royaumes "realm"

- Se connecter à http://localhost:8080/admin avec les identifiant admin

- Un royaume est un ensemble isolé d'utilisateurs et d'applications géré par un administrateur

- Le royaume **master** est seulement utilisé pour gérer Keycloak et ne doit pas être utiliser pour gérer d'autres applications

- **Tester le fonctionnement des royaume** voir [getting-started-zip](https://www.keycloak.org/getting-started/getting-started-zip)

	- suivre bettement les étapes juqu'a arriver au message "hello, myuser" sur [https://www.keycloak.org/app/](https://www.keycloak.org/app/)

- **Créer un royaume**

	- Dans le menu déroulant tout en haut à gauche choisir "Create Realm"

		- Choisir un nom de royaume "Realm name" puis le créer avec "Create"

- **Créer un utilisateur**

	- ATTENTION : nous allons créer un utilisateur dans le royaume sélectionné dans le menu déroulant tout en haut à gauche, sauf cas particulier, il faudra éviter le royaume **master**

- **Créer client**

	- TODO ajouter nextcloud https://stackoverflow.com/questions/48400812/sso-with-saml-keycloak-and-nextcloud

- **User Federation**
  permet d'avoir acces à LDAP et Active Directory  
	- TODO Connection au à OpenLDAP https://rob-ferguson.me/keycloak-flowable-and-openldap/

- TODO **Identity providers**

## TODO Gestion via la cli

- [doc](https://www.keycloak.org/docs/latest/server_admin/#admin-cli)

# Ressources

- https://github.com/thomasdarimont/awesome-keycloak

- https://rob-ferguson.me/