Un module de vérification SMS (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.

Chaîne d'authentification SMS TOSIAM

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 renforcer son processus d’authentification. Initialement, une simple authentification par mot de passe était suffisante pour satisfaire les besoins d’une application exposée sur internet. Avec la recrudescence des vols de mot de passe, il a été décidé qu’à chaque authentification, un SMS est envoyé sur le mobile de l’utilisateur avec un code à 6 chiffres à usage unique. Ce code doit être utilisé dans les 5 minutes qui suivent l’authentification par mot de passe.

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
  • Disposer d’un compte chez AWS

Nous allons utiliser le Service AWS SNS (Simple Notification Service), pour l’envoi de SMS. TOSIAM fournit un module d’authentification HOTP qui s’appuie sur une infrastructure SMTP proposée par un fournisseur Télécom. Dans ce tutoriel, nous nous appuyons sur un provider de cloud public pour lequel nous vous présentons un adaptateur.

Installation

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

Editez le fichier <MODULE>/SmsSnsModule.properties, et renseignez les champs suivants :

aws_access_key_id=<YOUR_ACCESS_KEY_ID>
aws_secret_access_key=<YOUR_ACCESS_KEY_PASSWORD>

La clé d’accès s’obtient via le service IAM de AWS.

Dans la console AWS, il faut associer au user qui possède la clé d’accès la politique suivante :

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Action": [
				"sns:Publish"
			],
			"Effect": "Allow",
			"Resource": "*"
		}
	]
}

Editez le fichier <MODULE>/users.ldif :

dn: uid=dduck,ou=people,dc=tosit,dc=org
ou: people
uid: dduck
cn: Donald DUCK
sn: DUCK
givenName: Donald
mail: donald_duck@tosiam.io
userPassword: password
inetUserStatus: active
telephoneNumber: <MOBILE_PHONE>
objectClass: inetOrgPerson
objectClass: inetuser
objectClass: sunAMAuthAccountLockout

Remplacez <MOBILE_PHONE> par votre numéro de mobile au format (+33XXXXXXXXX). Ce numéro doit être aussi référencé sur AWS au niveau du service SNS, partie Mobile/SMS.

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

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

Formulaire d'authentification du module SmsSns

Entrer :

  • Nom : dduck
  • Mot de passe : password

Au bout de quelques secondes, vous devriez recevoir un SMS avec le message : TOSIAM vous envoie un code à usage unique : XXXXXX

Formulaire de saisie du code OTP

Entrez ce code dans le formulaire ci-dessus, et cliquez sur “SUBMIT OTP”.

Notez que ce formulaire fourni par défaut dans TOSIAM peut être remplacé par un formulaire personnalisé.

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.

La classe SmsSns

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 amSmsSns.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 SmsSns.xml) et utilisé dans le template HTML de l’étape courante du module (ici on utilise un template par défaut). 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 SmsSns.xml)
  • public Principal getPrincipal()

Voici une analyse du contenu de la méthode process. Notre module contient 2 étapes. L’étape 1 est automatique, l’étape 2 nécessite de remplir un formulaire.

Analyse de la méthode process du module SmsSns
Notes
  1. La méthode getIdentity() récupère le user à partir de la propriété username initialisée dans la méthode init via l’objet sharedState.
  2. La méthode generateCode de la classe utilitaire OTPGenerator génère un code OTP à 6 chiffres. Ce code est envoyé par la classe utilitaire SmsSender qui gère la partie AWS.
  3. L’étape 1 n’a pas de callbacks (voir le fichier de callbacks SmsSns.xml ci-dessous). Dès que la méthode init a été appelée, la méthode process est tout de suite appelée pour le stage 1. Ici on retourne le stage 2, qui lui a des callbacks. Un formulaire va donc s’afficher dans le browser de l’utilisateur.
  4. L’utilisateur a cliqué sur SUBMIT OTP. On récupère le code OTP entré par l’utilisateur, et on le compare avec celui qui a été généré. On renvoie alors le code -1 (LOGIN_SUCCEDED). Le module est passé avec succès. La chaine d’authentification est terminée.
  5. Le code OTP est incorrect, on retourne à l’étape 2. Il est possible de générer un nouveau code.

Le fichier de callbacks (SmsSns.xml)

<ModuleProperties moduleName="SmsSns" version="1.0" >
  <Callbacks length="0" order="1" timeout="120" header="#WILL NOT BE SHOWN#" />
  <Callbacks length="2" order="2" timeout="120" header="Please enter your One Time Password, or request a new one" >
    <PasswordCallback echoPassword="false" >
      <Prompt>Enter OTP</Prompt>
    </PasswordCallback>
    <ConfirmationCallback>
      <OptionValues>
        <OptionValue>
          <Value>Submit OTP</Value>
        </OptionValue>
        <OptionValue>
          <Value>Request OTP</Value>
        </OptionValue>
      </OptionValues>
    </ConfirmationCallback>
  </Callbacks>
</ModuleProperties>

Il s’agit d’un document XML contenant une liste de groupes 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.

Notez la présence de 2 groupes de callbacks. Le premier (order=1) est vide, il s’agit d’une étape automatique.

Le fichier amSmsSns.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 :

<AttributeSchema order="5" name="passwordLength"
                                 type="single_choice" syntax="string" i18nKey="a104" resourceName="passwordLength">
  <ChoiceValues>
    <ChoiceValue i18nKey="6digits">6</ChoiceValue>
    <ChoiceValue i18nKey="8digits">8</ChoiceValue>
  </ChoiceValues>
  <DefaultValues>
    <Value>6</Value>
  </DefaultValues>
</AttributeSchema>

Nous introduisons une donnée de configuration définissant le nombre de chiffres du code OTP, qui peut être 6 ou 8. Son nom est : passwordLength, dont la valeur par défaut est 6. La valeur passwordLength est récupérée par le module java SmsSns.java dans la méthode init et est utilisée pour initialiser le générateur de code.

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 -> SmsSnsModule.

Vous obtenez l’écran suivant :

Configuration du module SmsSns dans la console d'administration
Modifier cette page sur GitHub