Elko: Gatekeeper Protocols

The Elko Gatekeeper Protocols

The Gatekeeper

The Gatekeeper is an Elko server that provides login reservation and authentication services for other Elko servers such as the Director. If you wish to use user accounts or some other authentication or access control abstraction to regulate access to a collection of Elko servers, you typically place a Gatekeeper between a user and a Director rather than having the user communicate with the Director directly.

A Gatekeeper understands two different JSON message protocols. These correspond to the two kinds of actors who may wish to communicate with a Gatekeeper: users seeking to login or manage their accounts, and administrators. Each of the ports that a Gatekeeper listens for connections on can be configured to support either or both of these protocols.

Each of these protocols is associated with a particular object ref to which messages should be addressed:

Note that since a Gatekeeper makes its own outbound connection to a Director per its configuration, it also speaks the director protocol However, the Gatekeeper speaks the client side of this protocol; you cannot yourself establish a connection to a Gatekeeper port that uses this protocol.

User Protocol

The Gatekeeper user protocol is used by clients who wish to make an authenticated entry into a context.

reserve

→ { to:"gatekeeper", op:"reserve", protocol:STR, context:CONTEXTREF_STR, id:?STR, name:?STR, password:?STR }

This message requests a reservation for entry into a context.

If the reservation is successful, the reply will take the form:

← { to:"gatekeeper", op:"reserve", context:CONTEXTREF_STR, id:?STR, actor:?STR, name:?STR, auth:?STR, hostport:STR }

where:

If the reservation fails, the reply will take the form:

← { to:"gatekeeper", op:"reserve", context:CONTEXTREF_STR, id:?STR, deny:STR }

where:

setpassword

→ { to:"gatekeeper", op:"setpassword", id:STR, oldpassword:?STR, newpassword:?STR }

This message makes a request to the Gatekeeper to change a user's password.

where:

Admin Protocol

The Gatekeeper admin protocol is used to administer the Gatekeeper server.

director

→ { to:"admin", op:"director", hostport:?STR, auth:?AUTHDESC }

This message requests that the Director this Gatekeeper is talking to to be changed or reported.

where:

The Gatekeeper will normally reply with a message of the form:

← { to:"gatekeeper", op:"director", hostport:STR }

where:

In the event of a failure to update the Director setting, the Gatekeeper will reply with:

← { to:"gatekeeper", op:"director", failure:STR }

where:

reinit

→ { to:"admin", op:"reinit" }

This message instructs the Gatekeeper to reinitialize itself.

shutdown

→ { to:"admin", op:"shutdown" kill:?BOOL }

This message instructs the Gatekeeper to shut itself down.

where: