The Authentication Service

Authentication

Introduction

The N-Squared JSLEE supports authentication of incoming sessions through the authentication module. A simple configuration for authentication is:

{
    "myauth": {
      "handler": "nz.co.nsquared.slee.authentication.UniversalAuthenticatorVerticle"
    }
}

This authentication will accept any authentication request, and response with a success result. The authentication application supports both local and non-local endpoints. To reference an authentication endpoint, use the application name. In this example the name would be myauth.

Authentication Methodology

JSLEE applications which require authentication for a connection (user, service endpoint etc) will send an AuthenticationRequest to the authentication application. When requesting authentication the following information is provided:

Based on this information, the authentication module will respond with a success or failure message to the requestor application. On failure, the response is simply “not authorized”. On success, the following details are provided back to the requestor:

Authentication Methods

The Universal Authenticator

If all authentication requests regardless of credentials provided should succeed, use the universal authenticator:

{
    "auth-app": {
      "handler": "nz.co.nsquared.slee.authentication.UniversalAuthenticatorVerticle",
      "groups": [  ],
      "attributes": {  }
    }
}

A single set of groups and attributes can be provided as part of the universal authenticator. All users get the same set of attributes and groups. Including groups and/or attributes is optional.

The Local Configuration Authenticator

If authentication is to be based on rules either in a local configuration file, or embedded in the JSLEE configuration file, use the local configuration authenticator:

{
    "auth-app": {
      "handler": "nz.co.nsquared.slee.authentication.LocalConfigurationAuthenticatorVerticle",
      "configuration": {
        "rules": [ 
          
        ],
        "grants": {
          
        }
      }
    }
}

This authentication method will authenticate based on matching credentials between the authentication request and the information stored in the configuration on disk in the rules array. Since authentication configuration can become rather large, it is possible to have the local configuration authenticator read authentication rules from a separate file. to do so, specify an include file using the __include directive.

Local Configuration Rules

Each rule must define whitelist information for matching against incoming authentication requests, and the (optional) grant that will be granted if the rule matches. An example rule is:

{
  "username": "nsquared",
  "password": "z3QFL4k7RPz2asUNYRAb",
  "service-regex": "^(sms|gw)$",
  "remote": [
    {
      "address": "125.236.232.186"
    }
  ],
  "local": [
    {
      "subnet-cidr": "10.0.0.0/24"
    }
  ],
  
  "grant": "nsquared-administrator"
}

All rule items are optional (e.g. the password rule field can be not included, if password is irrelevant). The full list of options for rules are:

Within the remote and local list, each object must consist of a subset of the following fields:

If remote is empty, or not provided, all remote addresses are acceptable to the authentication system. However, if at least one entry is provided, the list of remote addresses/ports is considered a whitelist and a connection must match to at least one of the listed addresses, otherwise the authentication request will be rejected.

The same logic applies to the local list.

The Jenkov Tutorial provides a full explaination of these regular expressions, howver note that all matches are “full string” matches. For example, the regular expression esme[0-9] will only match strings esme0 to esme9. It will not match strings with suffixes or prefixes (e.g. myesme8).

Since the rules list is an array, rules are processed in the order of definition. Of two more more rules would match an authentication request, the rule earliest in the list will be the one that matches at run-time.

Local Configuration Grants

Each grant defined for the location configuration authentication consists of an object with one or both of the groups and attributes keys, with appropriate value:

{
  "groups": [  ],
  "attributes": {  }
}

A grants object might look like:

{
  "nsquared-administrator": {
    "groups": [ "query-readonly", "statistics-readonly", "smsgw-control", "redis-control" ],
  },
  "esme-general": {
    "groups": [ "TX" ],
    "attributes": {
      "max-tps": 100,
      "max-window-size": 1000  
    }
  }
}

In this example, two grants exist and can be referenced using their names nsquared-administrator and esme-general. When defining rules for authentication, these grants can be associated using these names. In the case of the esme-general grant, it is given the single group TX, and a set of attributes relating to SMPP transaction limits.

Both groups and attributes may not be defined, and an empty group or attribute list is also valid. Applications using the grant information are ultimately responsible for how any provided grant information is processed and used.