Logging Service

Fit in NEANIAS Ecosystem

The NEANIAS Notification service acts as a generic notification provider for services that want to incorporate some sort of notification mechanism in their workflows. It allows generic configuration and parametrization of notification templates, ad-hoc message authoring, give configuration options for selected notification channels to users and allow easy integration with other services that want to use its functionality.

Features

The NEANIAS Notification service offers its functionality as a backend service, accepting notification events from other services. These events are interpreted through a set of pre-configured notification flows and will be delivered to its recipients based on the respective profile enabled.

A descriptive list of the available or planned features as well as corresponding technical implications, are listed below:

It should be noted, that based on the requirements, expect5ed flows and integration process with service clients, some of these features are under investigation for the inclusion, feasibility and relevance.

  • Notification Channels
    • Mail
    • In-App Notification
    • SMS
  • Notification Policies
    • Global policies matching notification flows to acceptable notifier channels
    • User level policies based on ordered user preferences assuming user registration with the service
    • Fall through available options depending on whether respective profile information is available
    • Ad-hoc, pass through configuration of notification policies bypassing existing or missing configuration
  • Notification Tracking
    • Depending on channel features
    • Track delivery status of notification
  • Retries
    • Configuration number of retries per notification flow
    • Probabilistic retry intervals with progressive configurable delays
    • Options to omit retries after long period of time
  • Notification Templates
    • Different templates per notification channel
    • Support multiple locale
    • Configurable and easily upgradable
    • Ad-hoc, pass through configuration of message templates bypassing existing or missing configuration
  • Interface
    • Web API integration endpoints
    • Asynchronous / Queue messages
    • Administration Web App
    • User Interface widget to display in-app notifications

AAI Integration

Authentication

Integration with NEANIAS AAI is achived at the access token level. Authenticated end users, through the OIDC Token Grant Flow or integrating services through OIDC Client Credential Grant Flow are authenticated and can contact the Notification Service.

Authorization

Since the integration of the Notification Service is expected to take place at the service level, the authorization of respective actions happen at the calling service / client level. Specific grants are given at a per client level. A dedicated notification service client has been created in order for the roles required to be cranted to its callers to be scoped within the notification client. Two roles can be distinguished:

  • admin - Perform administative operations and has full access to all service features and data
  • user - Perform notification submission actions

Integrating services are granted the “user” role. The “admin” role is reserved for service maintainers

API

Retrieving a service access token

Firstly an access token for a service that is registered within the NEANIAS AAI service needs to be retrieved. The following cURL script generates such a token:

curl --request POST \
--url 'https://sso.neanias.eu/auth/realms/neanias-development/protocol/openid-connect/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data client_id=[SERVICE NAME] \
--data client_secret=[SERVICE SECRET]

Validating

A user can inspect the retrieved access token and an example of such a token is shown bellow:

{
  "iss": "https://sso.neanias.eu/auth/realms/neanias-development",
  "aud": [
    "notification-client-id"
  ],
  "sub": "the subject id",
  "typ": "Bearer",
  "realm_access": {
    "roles": [
    ]
  },
  "resource_access": {
    "notification-client-id": {
      "roles": [
        "user"
      ]
    }
  },
  "clientId": "the client id"
}

Some information has been truncated but it is shown that resource access roles have been granted for the notification service

Using the following cURL script one can see how the notification service percieves their invocation:

curl -i --location --request GET 'https://notification.dev.neanias.eu/api/notification/principal/me' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [ACCESS TOKEN]'
HTTP/1.1 200 OK
Content-Length: 322
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
X-Powered-By: ASP.NET
Date: Wed, 25 Nov 2020 17:18:21 GMT
{
	"isAuthenticated": true,
	"principal": {
		"subject": "the subject id",
		"scope": [
		],
		"client": "the client id",
		"notBefore": "the date",
		"authenticatedAt": "the date",
		"expiresAt": "the date"
	},
	"permissions": [
		"SubmitNotification",
		"SubmitNotificationAdHoc"
	],
	"profile": {}
}

Sending an email

curl --location --request POST 'https://notification.dev.neanias.eu/api/notification/notification/persist' \
--header 'Authorization: Bearer [ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data '[
    {
        "Notification": "F5EFC7B9-E891-4D76-A0AA-FA743D260611",
        "ContactTypeHint": 0,
        "ContactHint": "{\"Contacts\":[{\"Type\":0,\"Contact\":\"the@ema.il\"}]}",
        "Data": {
            "Fields": [
                {
                    "Key": "subject_template",
                    "Type": "String",
                    "Value": "Hello {user-name}! Welcome to NEANIAS"
                },
                {
                    "Key": "body_template",
                    "Type": "String",
                    "Value": "<!DOCTYPE html><html><head><meta charset='\''utf-8'\'' /></head><body><h2>NEANIAS</h2><p>Hi {user-name}</p><p>Welcome to the world of <i>NEANIAS</i></p><p>You choosen wisely and <b>{service-name}</b> will help you bring your dreams to life!</p><br /><p>This email was generated automaticaly. Please do not reply to this email</p></body></html>"
                },
                {
                    "Key": "{user-name}",
                    "Type": "String",
                    "Value": "Giorgos"
                },
                {
                    "Key": "{service-name}",
                    "Type": "String",
                    "Value": "Cool Service"
                }
            ]
        },
        "ProvenanceRef": "reference-text"
    }
]'
  • The Notification element is a constant that needs to be always set to the displayed value.
  • In the ContactHint element you can add the email of the recipient substituting the example value “the@ema.il”
  • The “subject_template” and “body_template” keys contain the respective text
  • Any additional keys added, will be used as is to be substituted in both the subject and body templates
    • It is not mandatory to have text substitution but is offered as a convenience for clients
  • The “ProvenanceRef” field is a tagging field, free text for the client to use optionaly for provenance purposes
    • There is a limit of 50 characters to the field