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:
Data | Description |
---|---|
username | An ID of some form - SMPP system_id , the HTTP basic auth username, etc. |
password | The private secret for the user - SMPP password , the HTTP basic auth password, etc. |
remote address | The N-Squared JSLEE is a services platform. All connections are from remote IP to a local IP. Often the remote IPs that can connect are white listed and so the remote IP is always provided. |
remote port | The N-Squared JSLEE is a services platform. As with the IP, the port being used for connection is provided. |
local address | Similarly to the remote IP/port, the local IP the service is attempting to connect to is passed in. |
local port | Similarly to the remote IP/port, the local port the service is attempting to connect to is passed in. |
service | Often a connection request will be requested for the purposes of a service. This service can be passed through and used for additional authentication. This is important for SMPP whose system_type may need to be verified. |
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:
Data | Description |
---|---|
username | The canonical username. Usually this is the same username as provided for login purposes. |
groups | The list of groups granted to the user. Groups are simple strings (e.g. “RX”) |
attributes | An opaque JSON object describing the user’s attributes as granted. Attributes are more complex information for the user’s authorization. E.g. max transactions per second allowed. User attributes are often domain specific. |
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:
Field | Description |
---|---|
username |
A fixed username string. Either username or username-regex can be used, but not both. |
username-regex |
A regular expression to match against the username. Either username or username-regex can be used, but not both. |
password |
A fixed password string. There is no regex option for this field. |
service |
A fixed service string. Either service or service-regex can be used, but not both. |
service-regex |
A regular expression to match against the service. Either service or service-regex can be used, but not both. |
remote |
Matching details on remote IP addresses and ports which may connect as this username/service. This is an array of objects, with each object. |
local |
Matching details on local IP addresses and ports which may be connected to as this username/service. This is an array of objects, with each object. |
grant |
If a string, the name of the grant that authentication requests which match this rule will be given. If an object, the object may contain a groups and/or an attributes key. |
Within the remote
and local
list, each object must consist of a subset of the following fields:
Field | Description |
---|---|
remote.address |
The IP address of the server connecting/being connected to. Defining the IP address is optional. If not defined, all IP addresses are valid. |
remote.mask |
The bitmask in a.b.c.d format to apply to the address. If not defined, the bitmask will be set to 255.255.255.255 , fixing the given address to a single IP. The mask can only be specified if address is. |
remote.port |
The port from which the remote end is connecting, or to which the remote end is connecting. Either port or port-regex may be used, but not both. Defining ports is optional, and if not defined, all ports will be valid. |
remote.port-regex |
A regular expression matching ports. Either port or port-regex may be used, but not both. |
remote.subnet-cidr |
A CDIR formatted IP address and mask description. If subnet_cidr is specified, address and mask should not be specified. |
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.