Comment déployer Keycloak sur Clever Cloud ?

Keycloak est un moyen moderne et efficace de gérer les identités et les accès. Il permet l’authentification unique, la fédération d’utilisateurs à travers plusieurs annuaires d’utilisateurs. Il est également compatible avec les protocoles d’authentification standard comme OpenID Connect, OAuth2 ou SAML. Tous les détails sont disponibles sur son site. Dans ce blogpost, nous verrons les étapes du déploiement de Keycloack et Grafana sur Clever Cloud.

Comment déployer Keycloak ?

Setup

Keycloak est écrit en Java, et fournit un fichier JAR dans sa version, ce qui signifie que nous allons utiliser un runtime JAVA avec un déploiement JAR. Il nécessite également une base de données PostgreSQL, ce qui signifie que nous allons déployer un addon PostgreSQL.

# Get lastest Keycloak release
wget https://github.com/keycloak/keycloak/releases/download/17.0.1/keycloak-17.0.1.zip

# Extract the archive
unzip keycloak-17.0.1.zip

# Go to the folder
cd keycloak-17.0.1

# Create the jar application
clever create --type jar keycloak-server
export KEYCLOAK_DOMAIN=$(clever domain | xargs)

# Create the PG addon
clever addon create postgresql-addon --plan s_sml --addon-version 10 keycloak-postgres

# Link the addon
clever service link-addon keycloak-postgres

Configurer

Pour l’instant, nous allons configurer Keycloak en utilisant des variables d’environnement. Notez que vous pouvez également configurer Keycloak via son CLI ou via un fichier, comme indiqué dans sa documentation.

Note : Pour la configuration via des variables d’environnement, le modèle à utiliser est KC_ et le nom en majuscule de toute clé de configuration, séparés par des caractères de soulignement.

# Export env for templating purpose
export $(clever env | sed '/^#/d;s/\"//g')

clever env set CC_JAR_PATH lib/quarkus-run.jar
clever env set CC_JAVA_VERSION 11
clever env set CC_RUN_COMMAND "bin/kc.sh start --auto-build"

clever env set KC_DB postgres
clever env set KC_DB_USERNAME $POSTGRESQL_ADDON_USER
clever env set KC_DB_PASSWORD $POSTGRESQL_ADDON_PASSWORD
clever env set KC_DB_URL "jdbc:postgresql://$POSTGRESQL_ADDON_HOST:$POSTGRESQL_ADDON_PORT/$POSTGRESQL_ADDON_DB"
clever env set KC_HOSTNAME $KEYCLOAK_DOMAIN
clever env set KC_HTTP_ENABLED true
clever env set KC_PROXY passthrough
clever env set KC_PROXY_ADDRESS_FORWARDING true

Note: Envisagez de configurer KC_DB_POOL_MAX_SIZE (Le nombre maximum de connections parallèles a la base de donnée) avec une valeur basse (la valeur par défault est de 100) en fonction de la taille de la base de donnée que vous avez commandé plus tôt. Vous pouvez trouver les limites de connection par taille de base de donnée ici. Si vous avez choisi la taille S_SML comme précisé plus tôt dans la commande fournie, vous pouvez ignorer ce message. vous pouvez aussi configurer plus finement le groupe de connection a la base de donnée en utilisant les variable DB_POOL_INITIAL_SIZE et KC_DB_POOL_MIN_SIZE

Vous devez maintenant définir KEYCLOAK_ADMIN et KEYCLOAK_ADMIN_PASSWORD :

clever env set KEYCLOAK_ADMIN <choose an admin username>
clever env set KEYCLOAK_ADMIN_PASSWORD <choose an admin password>

Déployer

Déployer Keycloak sur Clever Cloud :

# Init a git repository
git init

# Add your files
git add .

# Create the first commit
git commit -m "clever init"

# Deploy the application
clever deploy

# Open Keycloak in your browser
clever open

Valider la configuration

Vous pouvez suivre la documentation de Keycloak en commençant ici pour vous assurer que Keycloak fonctionne comme prévu. Elle vous guidera à travers la création d’un realm (tenant), la création d’un utilisateur et la création/test d’un client.

Créer une configuration initiale de Keycloak

Dans l’interface utilisateur de Keycloak, assurez-vous de créer un realm appelé “myrealm” (survolez “Master” dans le coin supérieur gauche). Assurez-vous que le realm “myrealm” est sélectionné.

Ensuite, allez dans Utilisateurs > Ajouter un utilisateur. Remplissez les champs Nom d’utilisateur, Email, Prénom et Nom de famille, puis cliquez sur Enregistrer.

Dans l’onglet “credentials” de l’utilisateur, ajoutez le mot de passe de votre choix et désélectionnez “Temporary”, le mot de passe défini.

C’est fait !

Un scénario du monde réel

Voyons comment nous pouvons utiliser Keycloak dans le monde réel : comme proxy SSO pour Grafana, en utilisant Oauth 2.

Configurer Grafana sur Clever Cloud

Si vous avez besoin d’un guide détaillé sur la façon d’utiliser ou de déployer Grafana, veuillez lire cet article.

Utilisons l’exemple Grafana sur le dépôt Github de Clever Cloud.

# Clone the repository
git clone https://github.com/CleverCloud/grafana-example.git

# Enter the directory
cd grafana-example

# Create a NodeJS Application
clever create --type node grafana
export GRAFANA_DOMAIN=$(clever domain | xargs)

# Configure Grafana
clever env set GRAFANA_VERSION 8.5.2
clever env set GRAFANA_PLUGINS "grafana-worldmap-panel"
clever env set GF_PLUGIN_DIR ./data/plugins

clever env set GF_SERVER_HTTP_PORT 8080
clever env set GF_SERVER_ROOT_URL "https://$GRAFANA_DOMAIN"

Note : Dans cette section, vous devez définir vous-même la variable GRAFANA_SHA_256. Vous pouvez trouver la SHA256SUM nécessaire ici, à côté de “Standalone Linux Binaries”.

clever env set GRAFANA_SHA_256 <SHA256SUM>

Configurer Keycloak pour OAuth 2

Note : dans cette section, vous devez remplacer $GRAFANA_DOMAIN par la valeur que vous avez exportée dans la dernière section. Vous pouvez trouver cette valeur en exécutant la commande suivante : clever domain.

Dans l’interface utilisateur de Keyloak, allez dans Configurer > Clients > Créer.

Créez un nouveau client avec ces configurations :

Client ID: $GRAFANA_DOMAIN
Client Protocol: openid-connect
Root URL: https://$GRAFANA_DOMAIN

Effectuez ensuite ces configurations :

Access Type: confidentials // The OAuth client must use a client id and secret.
Root URL: ${authBaseUrl}
Valid Redirect URIs: https://$GRAFANA_DOMAIN/login/generic_oauth
Base URL: /login/generic_oauth

Effacez Admin URL et Web Origins.

Cliquez sur enregistrer et ouvrez l’onglet Credentials. Copiez le secret dans une note séparée, nous en aurons besoin dans les deuxième et troisième parties de ce tutoriel.

Ouvrez l’onglet Rôles et cliquez sur Ajouter un rôle. Créez un nouveau rôle avec le nom admin. Ce rôle définit le niveau d’accès pour Grafana.

Allez sur l’onglet Scope et définissez Full Scope Allowed sur OFF. Nous ne voulons pas partager d’autres détails sur le royaume dans le jeton client.

Ensuite, nous allons configurer un mappeur client pour la propriété roles. Nous devons nous assurer que Grafana peut extraire le rôle d’accès à partir du jeton JWT. Ouvrez l’onglet Mappers et cliquez sur Create. Créez une entrée avec ces options :

 
Nom : Roles
Mapper Type : Rôle client utilisateur
ID du client : $GRAFANA_DOMAIN
Nom de la réclamation token : roles
Type JSON de la réclamation : string

Enfin, attribuez le rôle client à votre utilisateur Keycloak : Allez dans Utilisateurs > Afficher tous les utilisateurs et cliquez sur l’ID de votre utilisateur. Cliquez sur l’onglet Role Mapping, puis dans le sélecteur Client Roles, sélectionnez $GRAFANA_DOMAIN. Dans la section Available Roles, sélectionnez admin et cliquez sur Add selected.

Configurer Grafana pour OAuth 2

Configurez les variables d’environnement appropriées

# Configure appropriate env vars
clever env set GF_SERVER_DOMAIN $GRAFANA_DOMAIN
clever env set GF_SERVER_ROOT_URL "https://$GRAFANA_DOMAIN"
clever env set GF_AUTH_GENERIC_OAUTH_ENABLED true
clever env set GF_AUTH_GENERIC_OAUTH_NAME Keycloak
clever env set GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP true
clever env set GF_AUTH_GENERIC_OAUTH_CLIENT_ID $GRAFANA_DOMAIN

clever env set GF_AUTH_GENERIC_OAUTH_SCOPES profile
clever env set GF_AUTH_GENERIC_OAUTH_AUTH_URL "https://$KEYCLOAK_DOMAIN/realms/myrealm/protocol/openid-connect/auth"
clever env set GF_AUTH_GENERIC_OAUTH_TOKEN_URL "https://$KEYCLOAK_DOMAIN/realms/myrealm/protocol/openid-connect/token"
clever env set GF_AUTH_GENERIC_OAUTH_API_URL "https://$KEYCLOAK_DOMAIN/realms/myrealm/protocol/openid-connect/userinfo"
clever env set GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH "contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'"

Note : Dans cette section, vous devez définir vous-même GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET, en utilisant la valeur dans Keycloak UI, sous Client > $GRAFANA_URL > Credentials

clever env set GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET <KEYCLOAK_CLIENT_SECRET>

Vous pouvez maintenant déployer Grafana :

 
# Deploy grafana
clever deploy

# Open grafana and try the Login with Keycloak button !
clever open

Maintenant, cliquez sur login with Keycloak, et utilisez le nom d’utilisateur et le mot de passe que vous avez définis pour l’utilisateur que vous avez créé plus tôt dans Keycloak.

En utilisant la même procédure décrite précédemment pour créer le premier utilisateur, vous pouvez maintenant créer d’autres utilisateurs et rôles. Créez les rôles “éditeur” et/ou “visualisateur” et attribuez-les à vos nouveaux utilisateurs dans Keycloak. Essayez de vous connecter avec ceux-ci sur Grafana et vous verrez que les rôles sont propagés à Grafana.

Sources :