Services

These are services ELAN Agent relies on but are not implemented, so they can be defined to match closely your needs. Services are RPC services that listen to a topic for a request and send an answer.

  • They can be implemented using python:
from elan.neuron import Dendrite, RequestError

def my_service(request, service):
  # .. process request...

  return {'json': 'serializable', 'object': ''}

  # or

  raise RequestError(errors={'json': 'serializable', 'error': 'object'}, error_str='an error string')

dendrite = Dendrite()

dendrite.provide('my-service', cb=my_service)

Todo

  • or directly using MQTT requests:

Registration

service:

registration
purpose:

Used to register agent to a control center for example.

With no request data, used to check if registration service is implemented.
request format:
{
  'login':    <string: *Mandatory*>,
  'password': <string: *Mandatory*>
}
returns:

returns on success (return value ignored)

raises RequestError on failure

Connectivity

service:

check-connectivity
purpose:

Used to check connectivity of registration service
request format:

None
returns:

returns on success (return value ignored)

raises RequestError on failure

External Authentications

You can implement extra authentication schemes by implementing the following:

service:

authentication/external/authorize
purpose:

return authentication information about user to be able to authenticate him
request format:
{
  "provider": // authentication ID to use
  "source":   // 'radius-dot1x' or 'captive-portal-web'
  "login":
  "password" // not always available, depending on authentication scheme.
}
returns:

Nothing if authentication information could not be found.

or

{
  "Cleartext-Password": <string>,
  // or
  "NT-Password": <string>,
  // or
  "LM-Password": <string>,
  // or
  "Password-With-Header": <string>,

  "provider": <int> // real provider that gave this auth information if different of one from request (for example an external group).
}

Even if password was sent in request, it is important to return it in Cleartext-Password to confirm it is the correct password.

Guest Request

You can implement guest access authorization using:

service:

guest-request
purpose:

Send guest request for validation (other that field validation). It is then the responsibility of the implemented service to grant access to the guest
request format:
{
  "guest_access":                   // id of the guest access
  "guest_access_modification_time": // modification time of the guest access when it was displayed to guest.
  "mac":                            // MAC address of the device requesting guest access
  "fields": [                       // fields sent by guest request form.
    {
      "display_name": // name of the field as configured in Guest Access Configuration.
      "type":         // type of the field as configured in Guest Access Configuration.
      "value":        // value of the field, validated against `type`.
      "field_id":     // id of the field as configured in Guest Access Configuration.
    },
    ...
  ],
  "vlan_id":    // VLAN Identifier of the received request.
  "interface":  // Interface the request was received on.
}
returns:

Nothing if request accepted. raise RequestError to send back errors to guest requesting access.

Device Authorization

service:

device-authorization
purpose:

Get device authorization (allowed VLANs to be one, allowed VLANs to access).
request format:
{
  "mac":             // device we want to get authorizations for.
  "auth_sessions": [ // list of authentication sessions (802.1x, captive portal or guest authorization)
    {
      "source": <string>,               // captive-portal-web, radius-dot1x, ...
      "till": <epoch>,                  // till when this authorization is valid
      "till_disconnect": <bool>,        // invalidate authorization on disconnect if true.
      "authentication_provider": <int>, // authentication provider id that performed authentication
      ...
    },
    ...
  ],
  "port": {
    "local_id":  // switch local id.
    "interface": // interface name.
    "ssid":      // ssid mac is connected to, if any
  }
}
returns:
{
  "assign_vlan": <int>,      // VLAN Identifier the device should be assigned during 802.1x, mac-auth, or by SNMP.
  "allowed_on":[]            // list of interface names like eth0.100 where eth0 is interface and 100 is vlan identifier (none if untagged vlan) on which the device is allowed to be.
  "bridge_to": []            // list of interface names like eth0.100 where eth0 is interface and 100 is vlan identifier (none if untagged vlan) to which device has access.
  "till": <epoch>,           // till when this authorization is valid
  "till_disconnect": <bool>, // invalidate authorization on disconnect if true.
}