Notifications system

LemonLDAP::NG can be used to notify some messages to users. If a user has got some messages, they will be displayed when he access to the portal. If a message contains some check boxes, the user has to check all of them else he can not access to the portal and retrieves his session cookie.

A notification explorer is available in Manager, and notifications can be set for all users, with possibility to use display conditions. When the user accept the notification, notification reference is stored in his persistent session.

You just have to activate Notifications in the Manager (General Parameters > Advanced Parameters > Notifications > Activation)

or in lemonldap-ng.ini [portal] section:

[portal]
notification = 1

Notifications explorer allows users to see and display theirs accepted notifications. Disable by default, you just have to activate it in the Manager (General Parameters > Advanced Parameters > Notifications > Explorer)

or in lemonldap-ng.ini [portal] section:

[portal]
notificationsExplorer = 1

By default, just the three last notifications are displayed. You can modify this by editing lemonldap-ng.ini [portal] section:

[portal]
notificationsMaxRetrieve = 3

When enabled, /mynotifications URL path is handled by this plugin.

An XML document can contain several notifications messages. Just the first one can be searched and displayed!

By default, notifications will be stored in the same database as configuration:

• if you use "File" system and your "dirName" is set to /usr/local/lemonldap-ng/conf/, the notifications will be stored in /usr/local/lemonldap-ng/notifications/
• if you use "CDBI" or "RDBI" system, the notifications will be stored in the same database as configuration and in a table named "notifications".
• if you use "LDAP" system, the notifications will be stored in the same directory as configuration and in a branch named "notifications".

You can change default parameters using the "notificationStorage" and "notificationStorageOptions" parameters with the same syntax as configuration storage parameters. To do this in Manager, go in General Parameters > Advanced Parameters > Notifications.

Parameters for File backend are the same as File configuration backend.

mkdir /usr/local/lemonldap-ng/notifications/
chown www-data /usr/local/lemonldap-ng/notifications/

To summary available options:

• dirName: directory where notifications are stored.
• fileNameSeparator: file name separator.

Parameters for DBI backend are the same as DBI configuration backend.

CREATE TABLE notifications (
  DATE datetime NOT NULL,
  uid VARCHAR(255) NOT NULL,
  REF VARCHAR(255) NOT NULL,
  cond VARCHAR(255) DEFAULT NULL,
  xml longblob NOT NULL,
  done datetime DEFAULT NULL,
  PRIMARY KEY (DATE, uid,REF)
)

To summary available options:

• dbiChain: DBI connection.
• dbiUser: DBI user.
• dbiPassword: DBI password.
• dbiTable: Notifications table name.

Parameters for LDAP backend are the same as LDAP configuration backend.

To summary available options:

• ldapServer: LDAP URL.
• ldapBindDN: LDAP user.
• ldapBindPassword: LDAP password.
• ldapConfBase: Notifications branch DN.

The notifications module uses a wildcard to manage notifications for all users. The default value of this wildcard is allusers, but you can change it if allusers is a known identifier in your system.

To change it, go in General Parameters > Advanced Parameters > Notifications > Wildcard for all users, and set for example alluserscustom.

Then creating a notification for alluserscustom will display the notification for all users.

Notifications are JSON (default) or XML files containing:

• <notification> element(s) :
  • Required attributes:
    • date: creation date (format YYYY-MM-DD WITHOUT time!)
    • ref: a reference that can be used later to know what has been notified and when
    • uid: the user login (it must correspond to the attribute set in whatToTrace parameter, uid by default), or the wildcard string (by default: allusers) if the notification should be displayed for every user.
  • Optional attributes:
    • condition: condition to display the notification, can use all session variables.
  • Sub elements:
    • <title>: title to display: will be inserted in HTML page enclosed in <h2 class="notifText">...</h2>
    • <subtitle>: subtitle to display: will be inserted in HTML page enclosed in <h2 class="notifText">...</h2>
    • <text>: paragraph to display: will be inserted in HTML page enclosed in <p class="notifText">...</p>
    • <check>: paragraph to display with a checkbox: will be inserted in HTML page enclosed in <p class="notifCheck"><input type="checkbox" />...</p>

[{
"uid": "foo",
"date": "2009-01-27",
"reference": "ABC",
"title": "You have new authorizations",
"subtitle": "Application 1",
"text": "You have been granted to access to appli-1",
# An array is required to set multi checkboxes
"check": [
  "I agree",
  "Yes, I'm sure"
]
},
{
"uid": "bar",
"date": "2009-01-27",
"reference": "ABC",
"title": "You have new authorizations",
"subtitle": "Application 1",
"text": "You have been granted to access to appli-1",
"check": "I agree"
}] # No comma at the end

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<root>
<notification uid="foo.bar" date="2009-01-27" reference="ABC">
<title>You have new authorizations</title>
<subtitle>Application 1</subtitle>
<text>You have been granted to access to appli-1</text>
<subtitle>Application 2</subtitle>
<text>You have been granted to access to appli-2</text>
<subtitle>Acceptation</subtitle>
<check>I know that I can access to appli-1 </check>
<check>I know that I can access to appli-2 </check>
</notification>
<notification uid="allusers" date="2009-01-27" reference="disclaimer" condition="$ipAddr =~ /^192/">
<title>This is your first access on this system</title>
<text>Be a nice user and do not break it please.</text>
<check>Of course I am not evil!</check>
</notification>
</root>

In Manager, click on Notifications and then on the Create button.

Then fill all inputs to create the notification. Only the condition is not mandatory.

When all is ok, click on Save.

LemonLDAP::NG provides two notification servers : SOAP and REST depending on format.

If enabled, the server URL is https://auth.your.domain/notifications.

Notification server provides three API to insert (POST), delete (DELETE) or list (GET) notification(s).

Available options:

• Server: Enable/Disable notification server
• Default condition: Condition appended to ALL notifications inserted by notification server (JSON format only)
• Notification parameters to send: Notifications parameters returned by GET method
• HTTP methods: Enable/Disable HTTP methods

Example:

# REST/SOAP functions for insert/delete/list notifications (disabled by default)
<LocationMatch ^/(index\.fcgi/)?notifications>
    <IfVersion >= 2.3>
        Require ip 192.168.2.0/24
    </IfVersion>
    <IfVersion < 2.3>
        Order Deny,Allow
        Deny from all
        Allow from 192.168.2.0/24
    </IfVersion>
</LocationMatch>

If you use old XML format, new notifications can be inserted or deleted by using SOAP request, once SOAP is activated:

#!/usr/bin/perl
 
use SOAP::Lite;
use utf8;
 
my $lite = SOAP::Lite
        ->uri('urn:Lemonldap::NG::Common::PSGI::SOAPService')
        ->proxy('http://auth.example.com/notifications');
 
 
$r = $lite->newNotification(
'<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<root>
<notification uid="foo.bar" date="2009-01-27" reference="ABC">
<text> You have been granted to access to appli-1 </text>
<text> You have been granted to access to appli-2 </text>
<check> I know that I can access to appli-1 </check>
<check> I know that I can access to appli-2 </check>
</notification>
</root>
');
 
if ( $r->fault ) {
    print STDERR "SOAP Error: " . $r->fault->{faultstring};
}
else {
    my $res = $r->result();
    print "$res notification(s) have been inserted\n";
}

#!/usr/bin/perl
 
use SOAP::Lite;
use utf8;
 
my $lite = SOAP::Lite
        ->uri('urn:Lemonldap::NG::Common::CGI::SOAPService')
        ->proxy('http://auth.example.com/index.pl/notification');
 
 
$r = $lite->deleteNotification('foo.bar', 'ABC');
 
if ( $r->fault ) {
    print STDERR "SOAP Error: " . $r->fault->{faultstring};
}
else {
    my $res = $r->result();
    print "$res notification(s) have been deleted\n";
}

Using JSON, you just have to POST json files.

For example with curl:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d @notif.json http://auth.example.com/notifications

DELETE API is available with LLNG ≥ 2.0.6

For example with curl:

curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" http://auth.example.com/notifications/<uid>/<reference>

GET API is available with LLNG ≥ 2.0.6

For example with curl:

# Retrieve 'wildcard' notifications
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" http://auth.example.com/notifications

# Retrieve all pending notifications
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" http://auth.example.com/notifications/_allPending_

# Retrieve all existing notifications
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" http://auth.example.com/notifications/_allExisting_

# Retrieve all <uid>'s notifications 
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" http://auth.example.com/notifications/<uid>

# Retrieve <uid>/<reference> notification parameters
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" http://auth.example.com/notifications/<uid>/<reference>

You've just to insert a notification and connect to the portal using the same UID. You will be prompted.

Try also to create a global notification (to the uid "allusers"), and connect with any user, the message will be prompted.