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:
gatekeeperfor user messages requesting access.adminfor administrator messages.
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.
protocolis the communications protocol by which the requestor wishes to communicate with the Context Server into which the requested context will be loaded. Valid values currently are"http"or"tcp".contextis the ref of the context into which entry is sought.idis an identifier for the entity who is seeking entry. This is interpreted in the scope of whatever authentication regime the Gatekeeper is configured to be using. It may be omitted if the context in question does not support a user abstraction or if it supports anonymous users.nameis an optional displayable name string for the user who is seeking entry. If omitted, it will be empty.passwordis the password (or similar authentication string) to authenticate the access of the indicated user, as is appropriate for whatever authentication regime the Gatekeeper is configured to be using.
← { to:"gatekeeper", op:"reserve", context:CONTEXTREF_STR,
id:?STR, actor:?STR, name:?STR,
auth:?STR, hostport:STR }
where:
contextis the ref of the context, which will match the corresponding parameter from the request.idis an identifier for the entity that sought entry, which will match the corresponding parameter from the request (and will be omitted if it was omitted from the request).actoris an object ref for the object representing the user in the context, which may be omitted if this is not a relevant abstraction for the context in question.nameis a displayable string labelling the user in the context, if relevant.authis the authorization code (typically a reservation token) to present to the Context Server in theentercontextrequest to enter the context.hostportis a string of the form"hostname:portnumber"indicating the host name and port number of the Context Server on which the reservation has been made.
← { to:"gatekeeper", op:"reserve", context:CONTEXTREF_STR,
id:?STR, deny:STR }
where:
contextandidhave the same meanings as in the success case.denyis an error message string indicating why the reservation could not be made.
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:
idis an identifier for the user seeking to change tneir password. This is interpreted in the scope of whatever authentication regime the Gatekeeper is configured to be using.oldpasswordis the password (or similar authentication string) to authenticate the access of the indicated user, as is appropriate for whatever authentication regime the Gatekeeper is configured to be using.newpasswordis the new password string for the user. to authenticate the access of the indicated user, as is appropriate for whatever authentication regime the Gatekeeper is configured to be using.
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:
hostportis a string of the form"hostname:portnumber"indicating the host name and port number of the Director that the Gatekeeper should now use. If omitted, the request merely asks that the Director be reported in the reply without being changed.authis an optional bundle of authorization information for the Gatekeeper to use in establishing its connection to the Director. This is exactly the authorization descriptor documented in the description of the Director'sauthmessage.
← { to:"gatekeeper", op:"director", hostport:STR }
where:
hostportis a string of the form"hostname:portnumber"indicating the host name and port number of the Director that the Gatekeeper is using.
← { to:"gatekeeper", op:"director", failure:STR }
where:
failureis an error message string attempting to describe what went wrong.
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:
killis an optional flag that if true orders an abrupt termination of the server. Normally, a server will empty its message queues, checkpoint any active state, and perform an orderly shutdown. However, if thekillflag is true, it will exit immediately without stopping to clean things up. The value defaults to false if the parameter is omitted.