Import et export des arbres d'authentification Forgerock AM

3 mai 2021

Cet article concerne l’utilisation du script amtree (amtree.sh) qui permet d’exporter et d’importer les arbres d'authentification de Forgerock AM (Forgerock AM authentication tree). Les arbres d'authentification n'existent pas à ma connaissance sur openam.

On verra ensuite comment utiliser ce script pour stocker les arbres exportés dans un repo git, les récupérer et les adapter.

Introduction

Depuis la version 5.5, Forgerock AM a introduit le concept d'arbres d'authentification (authentication tree). Les arbres d'authentification (également appelées authentification intelligente) permettent la mise en place simple, efficace et sécurisée d'un chemin d'authentification personnalisé, autorisant plusieurs parcours et points de décision tout au long du flux d'authentification.

On peut les utiliser pour créer des scénarios d'autorisation complexes, tout en offrant une expérience de connexion simplifiée aux utilisateurs. Les arborescences d'authentification sont constituées de nœuds d'authentification (Forgerock authentication node), qui définissent les actions entreprises lors de l'authentification. Chaque nœud effectue une seule tâche lors de l'authentification, par exemple, collecter un nom d'utilisateur ou prendre une décision simple basée sur un cookie.

Les nœuds peuvent avoir plusieurs résultats plutôt que simplement un succès ou un échec ; cela permet de créer des expériences d'authentification complexes mais conviviales en reliant les nœuds entre eux, en créant des boucles, en branchant l'arborescence pour différents scénarios d'authentification et en imbriquant les nœuds dans une arborescence.

Ici, on voit un arbre de connexion constitué d'une suite de nœuds.

Remarque : Ici nous avons une ou deux sorties maximum par nœud, mais il est possible d'en avoir plus.

1. Le premier node: start signifie le commencement de l'arbre.

2. Le second node permet de vérifier si requête entrante comporte des headers http qui contiennent les identifiants de l'utilisateur (https://backstage.forgerock.com/docs/am/7/authentication-guide/auth-node-configuration-hints.html#auth-node-zero-page-login-collector ) .

3. Si le node détecte les identifiants, l'arbre continuera vers le node "Data Store Decision" (cf plus bas à l'étape 6)

4. Sinon, on affiche le prochain node parcouru qui est le "User Name Collector" et qui va afficher un écran à l'utilisateur lui demandant de saisir son identifiant.

5. A la validation, un second écran est affiché via le node "Password Collector" pour demander la saisie du mot de passe.

6. A la validation, le node "Data Store Decision" va utiliser les informations login et mot de passe récupérés soit via les écrans dans les étapes 4 et 5, soit via les headers dans l'étape 2 et les tester sur le datastore configuré dans le realm (généralement le datastore est un ou plusieurs annuaires ldap, mais cela pourrait être n'importe quel autre datastore)

7. Si le datastore valide l'authentification, on arrive au node "Success" qui indique que AM va générer une session pour l'utilisateur

8. Sinon, on retourne à l'étape 4 pour demander la resaisie du login.

Ici, il n'y a pas de node "Failure" et on boucle indéfiniment en cas d'erreur.

Prérequis

• Pour pouvoir exporter et importer les arbres d’authentifications, il faut avoir un compte AM déjà configuré (Forgerock contient déjà une documentation détaillée pour installer AM). Pour commencer, nous pouvons utiliser un arbre d’authentification qu'AM a déjà créé par défaut.

• Choisir le terminal GNU/Linux avec qui nous sommes le plus à l’aise (dans mon cas, le terminal provient de l'environnement Ubuntu)

• Avoir un compte git et connaître les commandes git
  

I) Installation et configuration de git et du script amtree.sh

Pour faire le job, nous allons avoir besoin du script qui se trouve dans le repository github de vscheuber: https://github.com/vscheuber/AM-treetool

Avant de pouvoir cloner le repository, la configuration de git dans linux est primordiale.

Voici rapidement quelques lignes de commandes à écrire pour que tout fonctionne bien:

#Installation de git sur Ubuntu

$ sudo apt-get install git

#Sur CentOS

$ sudo yum install git

A partir de là, peu importe l'environnement linux, ce sera les mêmes commandes :

#Configuration de git

$ git config --global user.name "Your Name"

$ git config --global user.email "youremail@domain.com"

Git est maintenant configuré et est prêt à être utilisé.

Ensuite, pour plus de facilité, créons un répertoire :

$ mkdir amtree

Créons un nouveau dépôt GIT dans ce répertoire pour pouvoir ensuite importer plus tard les arbres dans un de nos repository git:

$ git init

Maintenant, il faut cloner le repository de vscheuber grâce à la commande :

$ git clone https://github.com/vscheuber/AM-treetool.git

Nous avons récupéré le script !

Que faisons-nous maintenant ?

II) Utilisation du script amtree.sh:

Pour commencer, c’est important de comprendre le fonctionnement du script.

En clonant le repository git, nous avons pu constater la récupération du fichier README.md. Il est important de le lire avant de continuer.

Testons le script pour exporter un arbre d’authentification d’un de nos realm.

A l’aide d’une simple commande, nous devrions pouvoir y arriver :

# export forgerock AM authentication tree

$ /path/to/amtree.sh -e -r /realm -h http://yourdomain.name/am -u amuser -p 'ampassword' -f Example.json -t Example

Regardons plus précisément les options et paramètres de cette commande :

• -e : permet d’exporter un arbre d’authentification

• -r : spécifie le nom du realm. Si on ne le spécifie pas, ce sera dirigé vers Top level Realm par défaut. Ne pas oublier de mettre un / avant le nom du Realm sinon l'URL se dirigera vers http://yourdomain.name/amrealm. L'output de la commande affichera alors l'erreur: parse error: Invalid numeric literal at line 1, column 1

• -h : l’URL qui accède à AM

• -u et –p : indiquent le nom et mot de passe de l’utilisateur

• -f : On déclare le nom du fichier dans lequel l’arbre sera exporté

• -t : On informe quel arbre nous devons exporter.

Note : Le nom du fichier peut porter le même nom que celui de l’arbre exporté pour éviter toute confusion.

Mais que se passe-t-il si nous voulons exporter tous les arbres d’un realm ?

C’est encore plus simple que la commande précédente :

$ /path/to/amtree.sh -S -r /realm -h http://yourdomain.name/am -u amuser -p 'ampassword'

Avec l’action -S tous les arbres d’authentification vont être exportés dans des fichiers json par défaut dans le répertoire courant.

Pour visualiser tous les fichiers JSON, lister avec la commande ls le répertoire où l'exportation a été réalisé:

$ mkdir export-trees

$ cd export-trees

$ /path/to/amtree.sh -S -r /realm -h http://yourdomain.name/am -u amuser -p 'ampassword'

[...]

$ ls

Agent.json

HmacOneTimePassword.json

PlatformRegistration.json

demo.json

Example.json

PersistentCookie.json

PlatformResetPassword.json

Facebook-ProvisionIDMAccount.json

PlatformForgottenUsername.json

PlatformUpdatePassword.json

myTree.json

Google-AnonymousUser.json

PlatformLogin.json

README.md

myTree2.json

Google-DynamicAccountCreation.json

PlatformProgressiveProfile.json

RetryLimit.json

On trouvera plus d'informations (en anglais) dans le post de l'auteur du script: Tree Pruning & Tuning

Via la console d'administration web d'AM, nous avons une représentation graphique de l'arbre. D'un autre côté le script amtree.sh nous permet d'avoir une vision de ces arbres au format JSON.

Début du fichier JSON de l'arbre exporté: Example :

{

"origin": "3aff568880fffb3761eaa75d9464a989 -",

"innernodes": {},

"nodes": {

"7511f629-2ae1-4d0e-879c-d0a03966127c": {

"_id": "7511f629-2ae1-4d0e-879c-d0a03966127c",

"allowWithoutReferer": true,

"referrerWhiteList": [],

"passwordHeader": "X-OpenAM-Password",

"usernameHeader": "X-OpenAM-Username",

"_type": {

"_id": "ZeroPageLoginNode",

"name": "Zero Page Login Collector",

"collection": true

},

"_outcomes": [

{

"id": "true",

"displayName": "Has Credentials"

},

{

"id": "false",

"displayName": "No Credentials"

}

]

},

"b5e2eff4-7d98-4ab1-999b-d6aa0c340507": {

"_id": "b5e2eff4-7d98-4ab1-999b-d6aa0c340507",

"_type": {

"_id": "DataStoreDecisionNode",

"name": "Data Store Decision",

"collection": true

},

Le fichier json a le format suivant:

1) "origin": ajouté par le script pour indiquer l'ID du Realm. Il est chiffré grâce à la fonction de hachage md5. Cela permettra de détecter si nous importons dans un nouvel environnement ou dans le même environnement depuis lequel l'arborescence a été exportée

2) "innernodes": certains nodes peuvent contenir d'autres nodes (par exemple la page node peut contenir plusieurs nodes pour la saisie d'infos à l'écran), on a dans cette partie ces détails d'inclusion

3) "scripts": si l'arbre fait référence à des scripts, ils seront ici, encodés en base 64

4) "emailTemplates": S'il s'agit de FIDC (Forgerock Identity Cloud) ou ForgeOps, nous pouvons exporter les modèles d'e-mail référencés par les nœuds dans ce nœud de page

5) "tree": le nom de l'arbre, et l'arborescence des nodes. Chaque node est aussi identifiée par son uid. On liste les connexion entre chaque node ainsi que le nom de chaque node dans l'arbre

Sauf petit bémol :

Si nous voulons pousser les arbres dans un repository Git, il va falloir retirer des fichiers JSON toutes les informations sensibles comme le nom des serveurs et toute autre information qu'on jugera non partageable.

Qu'en est-il des mots de passe?

Si nous avons bien lu la fin du fichier README.md tout à l’heure, l’auteur du script spécifie bien que lors de l’exportation des arbres, les mots de passe ne sont pas eux aussi exportés. Donc pas besoin de s'inquiéter de ce côté.

Prenons l'exemple d'un arbre simple qui utilise un LDAP Decision node.

Pour pouvoir communiquer avec le serveur LDAP, nous avons besoin de se connecter grâce au nom du serveur…

Par exemple ci-dessous, on verra en rouge les données qui devraient mieux être enlevées du fichier JSON:

"2c112cc9-10af-447d-90af-1dca389f844c": {

"_id": "2c112cc9-10af-447d-90af-1dca389f844c",

"heartbeatTimeUnit": "SECONDS",

"beheraEnabled": true,

"userCreationAttrs": [],

"userProfileAttribute": "uid",

"returnUserDn": true,

"minimumPasswordLength": 8,

"secondaryServers": [],

"heartbeatInterval": 10,

"adminDn": "uid=admin",

"adminPassword": null,

"accountSearchBaseDn": [

"dc=example,dc=com"

],

"searchScope": "SUBTREE",

"searchFilterAttributes": [

"uid"

],

"trustAllServerCertificates": false,

"ldapOperationsTimeout": 0,

"primaryServers": [

"localhost:2636"

],

Nous pouvons remarquer également que les mots de passe ne sont effectivement pas exportés ("adminPassword": null).

Avant d'importer les arbres de nouveau sur Forgerock AM, que ce soit sur le même serveur ou sur un autre, nous devrons rajouter manuellement les mots de passe et les informations sensibles qu'on aurait supprimées dans les fichiers JSON des arbres exportés.

On pourra faire ces modifications à la main, ou utiliser un script comme jq qu'on adaptera à nos besoins.

Conclusion :

Le fichier JSON permet de conserver des structures de données simples et nous pouvons grâce à cela modifier et supprimer les informations sensibles directement via un éditeur de texte (ou évidemment un script).

Après modification des arbres d’authentification, nous pouvons les importer dans un repository git.

Tout d’abord, il faut créer un repository git sur Github/Gitlab....

Il faut alors le cloner sur linux. (avec la clé SSH de préférence. Pour plus d’informations, rendez-vous sur ce site)

Ensuite taper les commandes:

• $ git add -all # ( ou git add Example.json pour n'ajouter qu’un seul fichier) #Ajoute des fichiers à l’index

• $ git commit -m 'amtree' -a #( ou git commit -m 'message' Example.json pour commité un seul fichier) #permet de valider les modifications apportées au HEAD

• $ git push -u origin master #Un simple push envoie les modifications locales apportées à la branche principale associée.
  

(Plus d’information sur les commandes git)

Voilà, les arbres se retrouvent sur Github/Gitlab/un autre repo git!

Cela peut apporter :

• Une sauvegarde supplémentaire.

• Une meilleure visibilité dans la modification des fichiers JSON.

• De nombreuses extensions qui peuvent aussi contribuer à notre projet.

Il faut pouvoir maintenant faire le chemin inverse, c'est-à-dire importer les arbres provenant d'un repository git dans un realm sur Forgerock AM.

Avant de les importer, n'oublions pas que nous avions supprimer les données sensibles et que les mots de passe ne sont pas exportés par défaut. Il faudra alors rajouter toutes les données dans les fichiers JSON.

Reprenons la même commande que tout à l’heure en changeant juste les options suivantes :

# import forgerock authentication tree

$ /path/to/amtree.sh -i -r /realm -h http://yourdomain.name/am -u amuser -p 'ampassword' -f Example.json -t Example #Importe un seul arbre d’authentification

$ /path/to/amtree.sh -s -r /realm -h http://yourdomain.name/am -u amuser -p 'ampassword' #Importe tous les arbres d’authentification

Récapitulatif :

Faisons un récapitulatif de ce que nous avons fait jusqu’à maintenant :

• Récupération du script amtree.sh sur github (et installation préalable du client git, si besoin)

• Introduction au script amtree.sh

  • Exportation des arbres d’authentification

  • Modification des fichiers JSON

  • Sauvegarde des arbres d’authentification dans un repository Git.

  • Import des arbres d'un repository Git dans un Realm AM

La prochaine fois, nous verrons comment, en utilisant des scripts shell, ce travail pourra être automatisé (Modification des fichiers JSON , déploiement des arbres dans différents environnements).

Mayane Maman

N'hésitez pas à laisser un commentaire ici.