Créer un module d'authentification (legacy)

Mécanisme legacy

Ce tutoriel décrit le mécanisme d’authentification antérieur aux graphes d’authentification (AuthGraph) : un module Java étendant AMLoginModule, configuré par des fichiers XML. Pour un projet TOSIAM récent, préférez le tutoriel Nœud d’authentification personnalisé, basé sur le système de graphes.

Introduction

TOSIAM permet de créer des chaines d’authentification orchestrant le processus d’authentification d’un utilisateur. Une chaine d’authentification est constituée de modules ou unités d’authentification, eux-mêmes constitués d’étapes élémentaires appelées stage.

TOSIAM fournit des modules d’authentification configurables, mais il est possible de créer son propre module d’authentification. C’est l’objet de cet article.

Vous trouverez des informations complémentaires dans la documentation OpenAM 13.5.2, paragraphe 3.3

Contexte

Un projet client A a exprimé récemment le besoin de créer un module d’authentification de type DataStore, mais contrairement au module prédéfini dans TOSIAM, ce projet souhaite définir une étape de rejeu. Un utilisateur s’authentifie en fournissant un username/password. En cas d’échec, l’utilisateur peut se réauthentifier jusqu’à N fois.

Prérequis

Sur votre machine Windows 10/11 ou Linux, installer TOSIAM (voir Installation). Nous supposons le serveur TOSIAM démarré.
Récupérer le projet GITHUB Tosiam Samples. Nous appellerons le répertoire de travail local <TOSIAM_SAMPLES>
Disposer d’un JDK 11+ (La variable JAVA_HOME est définie correctement)
Disposer de maven 3.X, avec un fichier settings.xml configuré comme indiqué ici

Installation

Le module se trouve dans le répertoire <TOSIAM_SAMPLES>/tosiam-auth-retrydatastore, que nous appellerons <MODULE>.

La compilation du code source, l’installation du binaire résultant dans TOSIAM et la configuration du serveur TOSIAM est automatisée. Nous allons d’abord tester la solution proposée, puis nous reviendrons sur les éléments importants.

Ouvrez une fenêtre console dans le répertoire <MODULE>, et taper :

Test du module

Cas passant

Appeler l’url : http://localhost:8080/tosiam/XUI/#login/ref&service=retry

Formulaire d'authentification du module RetryDataStore

Entrer :

Nom : demo
Mot de passe : changeit

L’utilisateur aboutit par défaut sur son dashboard :

Dashboard après authentification réussie

Cas avec rejeu

Appeler l’url : http://localhost:8080/tosiam/XUI/#login/ref&service=retry

Entrer :

Nom : demo
Mot de passe : toto

Le mot de passe est erroné, le module d’authentification passe en mode rejeu.

Écran de rejeu après échec d'authentification

Le module autorise 2 essais supplémentaires. Si au bout de ces 2 essais, l’authentification échoue, c’est la chaine d’authentification nommée retry (service=retry) qui échoue :

Échec de la chaîne d'authentification après épuisement des rejeux

Analyse du code

Le fichier pom.xml

Un module d’authentification custom s’appuie sur le code de TOSIAM. Celui-ci est packagé sous la forme d’une librairie définie par les éléments suivants dans le fichier pom.xml :

    <repositories>
        <repository>
            <id>tosiam_github</id>
            <url>https://maven.pkg.github.com/theopensourceitrust/tosiam</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.tst.tosiam</groupId>
            <artifactId>tosiam-server-lib</artifactId>
            <version>2.26.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

TOSIAM est compatible JDK 11+, donc nous avons configuré le fichier pom.xml pour produire du code compatible JDK 11. Cela n’est pas obligatoire. Vous pouvez compiler pour le JDK 17 ou 21.

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

La classe RetryDataStore

Un module custom est matérialisé par une classe étendant la classe AMLoginModule. 3 méthodes doivent être implémentées.

public void init(Subject subject, Map sharedState, Map options) : Cette méthode est appelée à l’entrée du module. Le paramètre sharedState contient des valeurs issues d’un précédent module dans la chaine. De cette façon, un module amont de la chaine trasmet des informations au modules aval. Le paramètre options contient les données de configuration du module. Ces données dans le cas présent sont définies dans le fichier amAuthRetryDataStore.xml, et visible/modifiable dans la console d’admin (voir plus bas).
public int process(Callback[] callbacks, int state) throws LoginException : Cette méthode contient la logique d’exécution au sein du module. Le paramètre callbacks contient des objets typés décrits dans le fichier xml des callbacks (ici RetryDataStore.xml) et utilisé dans le template HTML de l’étape courante du module (ici RetryDataStore1.html). Notez bien que l’essentiel des classes de callback sont des classes du JDK, ce ne sont pas des classes de TOSIAM. Le paramètre state contient la valeur de l’étape associée aux callbacks (attribut order de l’élément XML Callbacks dans RetryDataStore.xml)
public Principal getPrincipal()

Voici une analyse du contenu de la méthode process. Notre module ne contient qu’une étape (valeur 1).

Analyse de la méthode process du module RetryDataStore

Notes

On teste le numéro de l’étape courante. Ici, c’est la valeur 1.
La classe de base AMLoginModule permet de récupérer le DataStore associé au realm. On passe alors le tableau de callbacks à la méthode authenticate.
Si le username/password est reconnu en base, alors, le process d’authentification est terminé, on retourne la valeur -1.
La méthode authenticate génère un InvalidPasswordException. En phase de rejeu, on incrémente un compteur.
Si le compteur excède la limite configurée (ici 2), l’erreur initiale est propagée. On sort du module.
La section header est formattée en tenant compte du numéro de rejeu courant.
On retourne le même code étape, 1. L’utilisateur est invité à s’authentifer à nouveau.

Le fichier de callbacks (RetryDataStore.xml)

<ModuleProperties moduleName="RetryDataStore" version="1.0" >
    <Callbacks length="2" order="1" header="Connexion à TOSIAM" >
        <NameCallback>
            <Prompt>Nom:</Prompt>
        </NameCallback>
        <PasswordCallback echoPassword="false" >
            <Prompt>Mot de passe:</Prompt>
        </PasswordCallback>
    </Callbacks>
</ModuleProperties>

Il s’agit d’un document XML contenant une liste de groupe de callbacks, chaque groupe étant identifié par l’attribut order qui représente le numéro d’étape. L’attribut moduleName définit un nom de module. Ce nom est notamment utilisé pour retrouver les templates html associés. L’attribut header est une propriété qui peut être utilisée dans le template.

Le fichier RetryDataStore1.html

Il s’agit d’un template dont le nom indique qu’il est associé au module RetryDataStore, étape 1. Voici le code du template :

<div class="container">
    <div class="page-header">
        <h1 class="text-center">{{reqs.header}}</h1>
    </div>
    <form action="" method="post" class="form login col-sm-6 col-sm-offset-3" data-stage="{{reqs.stage}}">
        <fieldset class="row">
            {{#each reqs.callbacks}}
            <div class="form-group">
                {{callbackRender}}
            </div>
            {{/each}}
        </fieldset>
    </form>
</div>

Un template html de module s’appuie sur le moteur de template javascript handlebars. Notez la présence de l’objet reqs. Il contient les informations issues de l’élément <Callbacks>. Chaque callback est typé (NameCallback, PasswordCallback, …). Handlebars peut évoquer une méthode de rendu de callback : callbackRender, fournie dans le module Javascript TOSIAM RESTLoginView.js. Cette méthode utilise elle-même un template JavaScript, il y en a un par type de callback. NameCallback utilise _Default.html, et PasswordCallBack utilise _Password.html.

Le fichier amAuthRetryDataStore.xml

Il s’agit du fichier définissant les propriétés qui peuvent être configurées via la console web d’admin ou l’outil en ligne de commande ssoadm. Ce fichier s’appuie sur une syntaxe plus générale permettant de décrire tout service dans TOSIAM. Voici un extrait des éléments qui nous intéressent :

    <SubSchema name="serverconfig" inheritance="multiple" resourceName="USE-PARENT">
     <AttributeSchema order="1" name="retryCount" type="single" syntax="number_range" rangeStart="0" rangeEnd="100" i18nKey="a100" resourceName="retryCount">
      <DefaultValues>
       <Value>2</Value>
      </DefaultValues>
     </AttributeSchema>
    </SubSchema>

Nous introduisons une donnée de configuration définissant le nombre de rejeux autorisés. Son nom est : retryCount, dont la valeur par défaut est 2. La valeur retryCount est récupérée par le module java RetryDataStore dans la méthode init et est stockée sous forme de propriété.

Le fichier configure.(bat|sh) se charge de mettre le contenu du fichier dans la base de configuration de TOSIAM.

Pour modifier la configuration du module dans la console TOSIAM (http://localhost:8080/tosiam/), connectez-vous avec le user amadmin, sélectionnez le royaume ref, puis Authentification -> Modules -> RetryDataStoreModule.

Vous obtenez l’écran suivant :

Configuration du module RetryDataStore dans la console d'administration