AuthentificationCollecte et décisions

Nœuds : décisions

Sur cette page

Nœuds qui évaluent une condition et branchent le graphe d’authentification en conséquence. Beaucoup ne se limitent pas à true/false : ils renvoient des sorties métier explicites, à connecter individuellement.

Graphe d'exemple : datastore, limite de tentatives et verrouillage Graphe d'exemple : datastore, limite de tentatives et verrouillage 1 2 3
Exemple : le datastore (1) vérifie les identifiants ; en cas d’échec, la limite de tentatives (2) redemande la saisie, puis le verrouillage (3) bloque le compte.

Exemple : une boucle de nouvelle tentative avec RetryLimitNode#

Le graphe le plus simple qui illustre un mécanisme non trivial : une boucle qui redemande le mot de passe en cas d’échec, jusqu’à une limite de tentatives.

Éditeur de graphes : la sortie false de la décision datastore mène à la limite de tentatives, qui renvoie au mot de passe (true) ou à l'échec (false) Éditeur de graphes : la sortie false de la décision datastore mène à la limite de tentatives, qui renvoie au mot de passe (true) ou à l'échec (false)
La boucle dans l’éditeur : un refus du datastore passe par la limite de tentatives, qui renvoie à la saisie du mot de passe tant que la limite n’est pas dépassée.
json
{
  "startNodeId": "username",
  "steps": {
    "username": { "type": "UsernameCollectorNode", "config": {}, "outcomes": { "outcome": "password" } },
    "password": { "type": "PasswordCollectorNode", "config": {}, "outcomes": { "outcome": "check" } },
    "check": {
      "type": "DataStoreNode",
      "config": { "authLevel": 0 },
      "outcomes": { "true": "success", "false": "retry" }
    },
    "retry": {
      "type": "RetryLimitNode",
      "config": { "retryLimit": 3 },
      "outcomes": { "true": "password", "false": "failure" }
    },
    "success": { "type": "SuccessNode", "config": {}, "outcomes": {} },
    "failure": { "type": "FailureNode", "config": {}, "outcomes": {} }
  }
}

RetryLimitNode compte chaque passage en échec, puis sort par true (nouvel essai) tant que le compte ne dépasse pas retryLimit, et par false au-delà. retryLimit compte donc les nouveaux essais : avec 3, l’utilisateur a droit à quatre mots de passe en tout, et le quatrième refus mène à FailureNode. C’est le nœud qui coupe la boucle password → check → retry → password : il borne les essais d’une connexion.

Le compteur n’appartient pas à la connexion en cours : il est tenu par utilisateur et par royaume (sans tenir compte des majuscules), et chaque échec y compte pendant 15 minutes. En conséquence :

  • recommencer la connexion depuis le début ne rend pas les essais ;
  • une authentification réussie par DataStoreNode remet le compteur à zéro ;
  • le compteur est gardé dans le CTS, que tous les serveurs TOSIAM partagent : la limite vaut pour le cluster entier, quel que soit le serveur qui reçoit chaque essai, et un redémarrage ne l’efface pas ;
  • il est commun à tous les graphes du royaume pour cet utilisateur.

Au-delà de la limite, le mot de passe est bloqué. Quand RetryLimitNode suit un refus de DataStoreNode et que la limite est dépassée, le mot de passe de cet utilisateur est bloqué 15 minutes : DataStoreNode sort par false sans le vérifier, même s’il est juste, et même sur une nouvelle connexion. La réponse est celle d’un mot de passe faux. Les essais faits pendant le blocage ne le prolongent pas.

Placé après un autre nœud (un nouveau mot de passe refusé par la politique, un code envoyé par SMS, un enrôlement), RetryLimitNode limite la boucle sans rien bloquer.

Lever un blocage. Réactiver le compte ou changer le mot de passe ne lève pas le blocage. Un administrateur du royaume le lève :

  • dans la console, sur la fiche de l’utilisateur (Identités, onglet Profil) : un bandeau montre les essais ratés et la fin du blocage de chaque facteur, et le bouton Lever le blocage efface les essais et lève les blocages ;
  • par l’API : GET /api/realms/{royaume}/users/{utilisateur}/authgraph-attempts lit les essais et les blocages, DELETE sur le même chemin les efface.

L’utilisateur est désigné par le nom qu’il saisit à la connexion, en général son uid. La levée vaut aussitôt sur tous les serveurs, pour le mot de passe et le code TOTP.

Le refus est signalé. Quand RetryLimitNode renvoie vers l’étape du mot de passe après un refus de DataStoreNode, il lui transmet le nombre d’essais restants. PasswordCollectorNode le présente dans une valeur password.attemptsLeft (voir Nœuds : collecte), que les deux pages de connexion affichent : « Mot de passe incorrect. Essais restants : 2. » Au dernier refus, la connexion échoue sans message particulier : la réponse est celle de tout échec. Pour bloquer un compte après des échecs répétés, voir LockoutNode ci-dessous, et sa mise en garde.

Les nœuds#

DataStoreNode : authentifie username/password contre le User Store LDAP ; en cas de succès écrit authenticatedUser et authLevel en shared state et réinitialise le compteur de tentatives.

Faites défiler le tableau
PropriétéTypeDéfaut
authLevelint0

Outcomes : true / false.

AccountLockStatusNode : vérifie si le compte est verrouillé via LockoutService.isLocked(). Aucune propriété configurable. Outcomes : true / false.

LockoutNode : agit sur le verrouillage (à la différence d’AccountLockStatusNode, qui ne fait que le lire) : verrouille ou déverrouille le compte selon action.

Faites défiler le tableau
PropriétéTypeDéfaut
actionstring (lockout / unlockout)lockout

Outcome : outcome.

Verrouiller rend l’identité inactive : l’utilisateur ne peut plus se connecter, même avec le bon mot de passe, jusqu’à ce qu’un administrateur la rende de nouveau active (ou qu’un graphe passe par LockoutNode avec unlockout).

L’éditeur de graphes le signale : il affiche un avertissement sur un LockoutNode qui verrouille quand un chemin y mène sans qu’aucune vérification ait réussi avant lui (mot de passe, code, clé d’accès, certificat, assertion). Le câblage habituel « mot de passe refusé, limite de tentatives, verrouillage » est dans ce cas. L’avertissement n’empêche pas d’enregistrer le graphe. Il ne s’affiche pas quand le verrouillage suit une vérification réussie, par exemple après un second facteur en échec : il faut alors connaître le mot de passe pour verrouiller le compte.

Déverrouiller un compte. Le verrouillage rend l’identité inactive, sans durée : rien ne le lève tout seul. Avec un dépôt d’identités LDAP dans sa configuration par défaut, c’est l’attribut inetUserStatus de l’utilisateur qui passe à Inactive. Pour rendre l’accès :

  • un administrateur remet inetUserStatus à Active, par l’API REST des utilisateurs (PUT /json/<royaume>/users/<identifiant>) ;
  • ou un graphe passe par un LockoutNode dont action vaut unlockout, par exemple au terme d’un parcours de récupération qui a vérifié l’identité autrement.

Si le graphe a verrouillé le compte après un dépassement de RetryLimitNode, le mot de passe de l’utilisateur reste par ailleurs refusé jusqu’à la fin de la fenêtre de 15 minutes, même une fois le compte réactivé (voir plus haut « Un blocage ne se lève pas à la main »).

AuthLevelNode : compare le niveau d’authentification courant du shared state au minimum requis.

Faites défiler le tableau
PropriétéTypeDéfaut
authLevelRequirementint (obligatoire)Aucun

Outcomes : true / false.

RetryLimitNode : voir l’exemple ci-dessus.

Faites défiler le tableau
PropriétéTypeDéfaut
retryLimitint, nombre de nouveaux essais après le premier échec (supérieur à 0)3

Outcomes : true / false.

BearerTokenNode : ouvre la session de l’utilisateur pour lequel un jeton d’accès OAuth2 a été émis. Le jeton est lu dans l’en-tête Authorization: Bearer, ou dans la clé de shared state bearerToken en repli. Il est accepté si toutes ces conditions sont remplies, sinon le nœud sort par false, sans dire pourquoi à l’appelant (la raison est journalisée au niveau ERROR) :

  • jeton d’accès actif du fournisseur OAuth2 du royaume du graphe, avec ou sans état (signature, révocation et expiration vérifiées) ;
  • jeton émis pour un utilisateur : un jeton client_credentials est toujours refusé ;
  • portée du nœud (scope) présente dans le jeton ;
  • client du jeton présent dans la liste du nœud (clients).

Le nœud écrit username en cas de succès. La session porte les propriétés BearerTokenClient (le client du jeton) et BearerTokenTrackingId, et ne donne rien sur /oauth2/authorize : le jeton d’une application ne devient pas une autorisation pour une autre.

Faites défiler le tableau
PropriétéTypeDéfaut
authLevelint0
clientsstring (identifiants séparés par des virgules)vide : aucun client
scopestringvide : aucun jeton

Outcomes : true / false.

ClientCredentialsSessionNode : échange un jeton d’accès obtenu par client_credentials contre la session d’un compte de service désigné par le nœud. C’est l’authentification de tosiam-config sans mot de passe (TOS-1791, ADR-0005). Le jeton est lu dans l’en-tête Authorization: Bearer seulement. Il est accepté si toutes ces conditions sont remplies, sinon le nœud sort par false, sans dire pourquoi à l’appelant (la raison est journalisée) :

  • jeton d’accès actif du fournisseur OAuth2 du royaume du graphe, émis par client_credentials ;
  • portée du nœud présente (tosiam:config par défaut) ;
  • client présent dans la liste du nœud (aucun par défaut), enregistré avec private_key_jwt, tls_client_auth ou self_signed_tls_client_auth : un client authentifié par secret est refusé ;
  • jeton lié à un certificat (cnf, RFC 8705) : la requête présente ce certificat.

La session est ouverte pour le compte du nœud, jamais pour un compte que nommerait le jeton ou le client. Ce compte doit être un utilisateur actif du royaume, pas un super-utilisateur, et ses droits sont ceux que lui donne la délégation (par exemple RealmAdmin). La session dure au plus maxSessionTime, porte la propriété ClientCredentialsClient (le client) et ne donne rien sur /oauth2/authorize.

Faites défiler le tableau
PropriétéTypeDéfaut
clientsstring (identifiants séparés par des virgules)vide : aucun client
serviceAccountstringAucun
scopestringtosiam:config
maxSessionTimeint (minutes)15

Outcomes : true / false.

StepUpAuthNode : déclenche une ré-authentification si le niveau courant est insuffisant ; le niveau requis peut être surchargé dynamiquement via une clé de shared state (utile pour protéger une transaction spécifique).

Faites défiler le tableau
PropriétéTypeDéfaut
requiredAuthLevelint2
requiredAuthLevelKeystring_resource_required_auth_level

Outcomes : true / false.

ScriptNode : exécute un script serveur identifié par scriptId, avec accès en binding à sharedState, username, logger, idRepository, et aux constantes SUCCESS/FAILED.

Faites défiler le tableau
PropriétéTypeDéfaut
scriptIdstring (obligatoire)Aucun

Outcomes : true / false.

ScriptedDecisionNode : décision écrite en JavaScript directement dans le graphe, sans passer par la bibliothèque de scripts. Le script branche avec action.goTo('<outcome>') et peut demander une saisie avec action.send(...). Il dispose de sharedState (lecture et écriture), requestHeaders, callbacks (valeurs soumises), callbacksBuilder (créer des callbacks), logger et idRepository.

Faites défiler le tableau
PropriétéTypeDéfaut
scriptstring (obligatoire) : JavaScript du nœudAucun
outcomesstring : outcomes possibles, séparés par des virgules ; chacun devient une sortie du nœud dans l’éditeurtrue,false
scriptNamestring : nom affiché dans les journauxScriptedDecisionNode
scriptRefstring : identifiant d’un script de la bibliothèque à exécuter à la place du script intégré""

Outcomes : ceux déclarés dans outcomes.

sharedState se lit et s’écrit par ses méthodes (sharedState.get('cle'), sharedState.put('cle', valeur), sharedState.remove('cle'), sharedState.containsKey('cle')) ou avec les crochets (sharedState['cle'] = valeur, delete sharedState['cle']).

Un script interactif suit ce modèle : il pose sa question quand rien n’a été répondu, puis choisit sa sortie d’après la réponse.

javascript
if (callbacks.isEmpty()) {
  action.send(callbacksBuilder.choiceCallback('Espace de travail', ['Personnel', 'Professionnel'], 0));
} else {
  action.goTo(callbacks.getChoice() == 1 ? 'professionnel' : 'personnel');
}

Quand le script choisit sa sortie, les réponses de la requête sont consommées, comme le font les nœuds Java. Un second script interactif placé juste après pose donc sa propre question : il ne reçoit pas la réponse donnée au premier. Exemple complet : Construire un graphe dans l’éditeur.

Mis à jour le