Envoyer une notification — WSO2 IS, une architecture événementielle[2/2]

Published in

Smile with WSO2

5 min readJul 16, 2021

WSO2 Identity Server permet d’envoyer des notifications aux utilisateurs du produit quand ils s’enregistrent, qu’ils ont perdu leur mot de passe, etc. Mais comment peut-on envoyer ses propres notifications ?

Cette série, “WSO2 IS, une architecture événementielle” est composée de 2 parties :
1. Capturer et traiter des événements
2. Envoyer une notification

Canaux de notifications

WSO2 Identity Server possède 2 canaux de notification par défaut : Email et SMS. Ils font partie de la catégorie appelé “internal” par l’éditeur, car géré directement par le produit. Certaines fonctionnalités offres la possibilité d’user d’un canal “external” c’est-à-dire dont l’implémentation est votre, en dehors du produit, et donc non déclenché par celui-ci.

Internal channels

Historiquement l’envoi des notifications était basé sur la librairie Apache Axis2 via les packages identity-notification-email et identity-notification-json (certaines fonctionnalités l’utilisent toujours). Il a été migré vers la technologie d’Events Stream de l’éditeur, coeur de sa technologie de Complex Event Processor/Stream Processor via le package carbon-analytics-common (branches 5.X).

Le principe est que les notifications sont envoyées dans un stream dédié au mode de transmission souhaité id_gov_notify_stream pour l’Email et id_gov_sms_notify_stream pour le SMS. Un event publisher est en écoute sur chacun de ces streams. Il va formater le message grâce à un template technique puis envoyer celui-ci via un adapter de transport.

Par défaut seul l’Email Event Publisher est configuré si vous avez besoin d’envoyer des sms vous devrez ajouter un fichier smsEventPublisher.xml avec le contenu dépendant de votre provider (cf documentation) :

<?xml version="1.0" encoding="UTF-8"?>
<eventPublisher name="HTTPOutputEventAdapter" processing="enable"     statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventpublisher">
    <from streamName="id_gov_sms_notify_stream" version="1.0.0"/> 
    <mapping customMapping="enable" type="json">
        <inline>
{"api_key"="<api_key>",
"api_secret"="<api secret>",
"from"="NEXMO", 
"to"={{mobile}},
"text"={{body}}}
        </inline>
    </mapping>
    <to eventAdapterType="http">
        <property name="http.client.method">httpPost</property>
        <property name="http.url">https://rest.nexmo.com/sms/json</property>
    </to>
</eventPublisher>

Handlers de notification

Le système de notification est étroitement lié au framework événementiel pour son déclanchement. L’éditeur a ainsi mis en place 2 évènements ayant ce rôle : TRIGGER_NOTIFICATION et TRIGGER_SMS_NOTIFICATION.

Le handler default.notification.sender réceptionne par défaut, depuis la version 5.10, les évènements TRIGGER_SMS_NOTIFICATION. Et non ce handler n’envoie pas que des SMS ça serait trop simple! Il se base sur la valeur de la propriété ‘notification-channel’ qui peut prendre pour valeur EMAIL ou SMS. Si la propriété n’est pas définie il utilisera la valeur par defaut défini dans le fichier [WSO2_HOME]/repository/conf/identity/identity.xml :

<Notification>
    <DefaultNotificationChannel>EMAIL</DefaultNotificationChannel>
    <ResolveNotificationChannels>
        <Enable>false</Enable>
    </ResolveNotificationChannels>
</Notification>

le handler emailSend réceptionne quant à lui par défaut TRIGGER_NOTIFICATION. Il n’envoie que des emails.

Chacun de ces handlers est responsable de la génération des notifications à envoyer, à partir des templates que vous avez définis, des données statiques de configuration et dynamiques transmises dans les événements.

Les propriétés essentielles dans un événement sont :

send-to : adresse du destinataire, si non renseignée les claims emailaddress ou mobile seront utilisés
TEMPLATE_TYPE : identifiant du template à utiliser si non défini par configuration
send-from, subject, body, footer : surcharge optionnelle du template et configurations

A ces propriétés vous pouvez ajouter n’importe quelles autres informations qui seront nécessaires lors de la génération du message.

Préférence de canal

WSO2 met à disposition des options de gestion avancés que vous pouvez utiliser dans votre handler pour sélectionner le canal de notification à utiliser :

Vérification de la propriété du canal de communication

Vous pouvez savoir, à travers les 2 claims suivants, si la véracité du numéro de téléphone et de l’adresse mail de la personne a été vérifié :

Phone Verified: http://wso2.org/claims/identity/phoneVerified
Email Verified: http://wso2.org/claims/identity/emailVerified

Choix par l’utilisateur final de son canal préféré

Le choix du canal préféré se fait par l’utilisateur final par le renseignement d’un claim de son profile :

Preferred Channel: http://wso2.org/claims/identity/preferredChannel

Et plus concrètement vous pouvez vous inspirer du code source du UserSelfRegistrationHandler en réalisant ceci :

// check lf channel resolving logic is not enabled
// if not return the server default notification channel
if (!Boolean.parseBoolean(
IdentityUtil.getProperty(IdentityMgtConstants.PropertyConfig.RESOLVE_NOTIFICATION_CHANNELS))) {
    return IdentityGovernanceUtil.getDefaultNotificationChannel();
}// Get the user preferred notification channel.
String preferredChannel = (String) eventProperties.get(IdentityRecoveryConstants.PREFERRED_CHANNEL_CLAIM);// if preferred notification channel is empty
// get first available user channel (default server channel in priority)if (StringUtils.isEmpty(preferredChannel)) {
    NotificationChannelManager notificationChannelManager = Utils.getNotificationChannelManager();
    try {
        preferredChannel = notificationChannelManager
           .resolveCommunicationChannel(userName, tenantDomain, domainName);
    } catch (NotificationChannelManagerException e) {
            handledNotificationChannelManagerException(e, userName, domainName, tenantDomain);
    }
}return preferredChannel;

Gestion des templates

Pour définir vos templates il vous suffit de les renseigner dans votre interface carbon ou la nouvelle interface console/admin.

A noter que pour les templates des SMS il vous faudra directement les manipuler dans le registre à ce niveau /_system/config/identity/sms.

Et si vous souhaitez automatiser leur provisioning vous avez une API pour ça!

Au sein des templates vous avez plusieurs variables à votre disposition :

{{user-name}}, {{first-name}}, [{user-id}}, {{carbon.product-url}}, {{userstore-domain}}, {{tenant-domain}}, etc. : les propriétés présentent dans l’événement
{{user.claims.X}} : les claims de l’utilisateur
{{user.claims.identity.X}} : les identity claims de l’utilisateur

Besoin d’urlencodé une variable, pas de panique! Il vous suffit d’utiliser la syntaxe suivante:

{{url:myVar}}

Envoyer des notifications

Si vous souhaitez envoyer des notifications 2 cas de figures sont possibles :

Simple notification à un événement

Vous ne souhaitez qu’envoyer une notification à un utilisateur suite à un évènement qui transite dans le framework. Par exemple, vous souhaitez envoyer une notification à un utilisateur pour confirmer sa demande de suppression de compte.

Ce cas simple ne nécessite aucun développement et juste de la configuration. Il vous suffit d’ajouter dans votre fichier deployment.toml :

[identity_mgt.events.schemes.'default.notification.sender']
subscriptions=["PRE_DELETE_USER","TRIGGER_SMS_NOTIFICATION"][identity_mgt.events.schemes.'default.notification.sender'.properties]
'subscription.PRE_DELETE_USER.notification_template' = "userDelete"

Nous venons de surcharger le handler de notification par défaut en lui disant d’écouter l’événement ‘PRE_DELETE_USER’ et d’envoyer une notification construit à partir du template ‘userDelete’

Envoi d’un événement déclencheur de notification

Si vous avez un besoin plus spécifique il vous faudra passer par un développement spécifique. Vous l’aurez compris, il vous faudra faire un handler et envoyer un évènement TRIGGER_NOTIFICATION ou TRIGGER_SMS_NOTIFICATION.

Pour plus d’information sur comment configurer les différents canaux je vous recommande la lecture de ces billets :