Pour le bon déroulement de ce tutoriel (et des suivants), la partie #1 doit être terminée.

Si vous souhaitez passer cette partie du tutoriel, téléchargez & importez la configuration du domaine ineat-realm

A ce stade du tutoriel, nous avons une instance de Keycloak fonctionnelle avec un domaine master (domaine administrateur par défaut)

L’objectif de cet article est de créer un domaine dédié à notre futur projet Java (API qui sera développée en Spring si vous avez été attentif)

Si vous n’êtes pas totalement familier avec la spécification OAuth2, je vous conseille fortement de lire cet article.

C’est parti !

Création d’un domaine ineat-realm

RéférenceDocumentation officielle

  • Connectez vous à l’interface d’administration de Keycloak (accès en local) avec vos identifiants administrateur (Créés ici normalement)
  • Créez un domaine nommé ineat-realm (ou un nom de domaine répondant à votre besoin)
Création du domaine ineat-realm

Une fois le domaine créé, vous avez accès à la configuration complète de ce dernier.

Créer un domaine par périmètre métier permet de contextualiser les politiques de sécurités de vos applications.

Configuration du domaine ineat-realm

La configuration par défaut de la rubrique Realm Settings de Keycloak est suffisante pour nos besoins.  (consultez la documentation de référence si vous avez besoin de personnaliser la configuration)

Les actions à prévoir pour préparer la sécurisation de notre backend :

  • Création d’un client ineat-api, qui sera utilisé par notre projet JAVA (api) pour contacter le backend Keycloak en tant que serveur de ressources (Resource Server) 
  • Création d’un client ineat-web, qui sera utilisé par les clients de notre API pour demander un token d’authentification à Keycloak
  • Création de rôles ADMIN et USER que nous utiliserons pour sécuriser nos URIs d’API (dans la partie 3 de cette série).
  • Création des utilisateurs possédant ces rôles, afin de pouvoir tester nos configurations

Création du client ineat-api

RéférenceDocumentation officielle

  • Rendez vous sur la rubrique Clients sur le menu de gauche
  • Cliquez sur le bouton Create à droite du tableau qui s’affiche

NOTERemarquez que Keycloak fournit par défaut des clients pour différents cas d’usages 

  • Saisissez dans le champ Client ID le nom du client qui sera utilisé par votre projet back (ineat-api pour les besoins de ce tutoriel)
  • Cliquez sur le bouton Save afin d’accéder à la configuration du client

Configuration du client ineat-api

Le client ineat-api sera utilisé par notre projet JAVA (api) pour contacter le backend Keycloak en tant que serveur de ressources (Resource Server) 

  • Définissez le champ Access Type à bearer-only puis valider cette configuration (bouton Save)

bearer-only

Bearer-only access type means that the application only allows bearer token requests. If this is turned on, this application cannot participate in browser logins.

Référence

Configuration du client ineat-api
  • Basculez ensuite sur l’onglet Credentials
    • le Secret affiché sera utilisé dans notre application backend (pour l’authentifier  auprès de Keycloak en tant que client ineat-api)

Création & configuration du client ineat-web

Le client ineat-web va permettre à l’ensemble des clients de notre API (postman, cUrl, etc) de pouvoir demander un token d’accès à Keycloak.

Il permettra aux clients (web) une autorisation via mot de passe pour accéder à nos ressources d’API.

Notre API sera accessible uniquement via une authentification bearer, ce qui signifie qu’avant de pouvoir la contacter, nous devons demander un bearer token à Keycloak, grâce à un client-id ayant la possibilité de faire des demandes de token.

  • En vous basant sur la procédure précédente, créez un nouveau client nommé ineat-web
  • Une fois sur l’onglet Settings (après avoir créer le client)
    • définir l’Access Type en public
    • activez l’option Standard Flow Enabled
    • activez l’option Direct Access Grands Enabled qui permet à ce client de pouvoir demander des tokens (nous verrons dans les articles suivants comment utiliser ce client).
Configuration du client ineat-web

Création des roles

Pour finir, nous allons créer deux rôles (associés au domaine) qui seront utilisés par notre backend pour catégoriser un utilisateur lors de son authentification.

RéférenceDocumentation officielle

  • Basculez sur l’onglet Roles  de l’interface d’administration
  • Utilisez le bouton Add Role à droite du tableau
  • Pour les besoins du tutoriel, nous avons besoin de créer
    • un role ADMIN
    • un role USER

Création des utilisateurs de tests

Afin de pouvoir tester l’accès à nos futurs URIs (sécurisées), nous allons créer deux utilisateurs possédant chacun un des deux rôles précédemment créé.

RéférenceDocumentation officielle

  • Basculez sur l’onglet Users
  • Cliquez sur le bouton Add user à droite de l’écran
    • Création d’un utilisateur ineat-admin
Création de l’utilisateur ineat-admin

NOTE : Activez Email Verified afin de rendre le compte actif par défaut

  • Après avoir cliqué sur le bouton Save, accédez à l’onglet Credentials
  • Définissez le mot de passe avec la valeur password (pour les besoins du tutoriel)
    • Désactivez l’option Temporary pour que notre utilisateur n’ai pas à changer son mot de passe à sa première connexion
    • Cliquez sur le bouton Reset Password  (puis confirmer sur la modale) pour définir le mot de passe

  • Basculez sur l’onglet Role Mappings afin d’assigner le rôle ADMIN à notre utilisateur
  • Ajouter ADMIN aux “Assigned Roles
  • Répétez l’opération avec un compte ineat-user ayant le rôle USER
Liste des utilisateurs à ce stade de la configuration

That’s it. Notre configuration est prête à être utilisée par nos futurs applicatifs.

One more thing

Pour éviter de ré-itérer l’opération sur différents environnements, Keycloak propose des fonctions d’import / export. Vous pouvez facilement exporter la configuration du domaine que nous venons de créer en accédant à l’onglet Export sur le menu de gauche.

ATTENTION, l’export ne concerne pas les utilisateurs créés

NOTE : Pensez à cocher l’ensemble des options afin d’exporter la configuration complète du domaine :

Astuce : Vous allez pouvoir attacher le fichier realm-export.json aux sources de votre projet afin de pouvoir rapidement (re)monter l’environnement Keycloak. 

En guise de compléments

  • Les informations de votre domaine sont disponibles sous /auth/realms/ineat-realm/.well-known/openid-configuration (lien localhost)
    • Ou en cliquant sur OpenID Endpoint Configuration de l’onglet General du domaine
  • La liste des endpoints exposés par Keycloak pour l’authentification des clients est détaillée ici  (elle nous servira dans l’article suivant pour tester les accès de nos utilisateurs à l’API)

Dans la prochaine étape, nous verrons comment lier notre configuration Keycloak à un backend Spring afin de sécuriser l’accès à nos URIs d’API REST.

Série d’articles Keycloak :

Édité le 24/02/2020 pour un passage en Keycloak 9.0.0