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:
gatekeeper
for user messages requesting access.admin
for 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.
protocol
is 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"
.context
is the ref of the context into which entry is sought.id
is 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.name
is an optional displayable name string for the user who is seeking entry. If omitted, it will be empty.password
is 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:
context
is the ref of the context, which will match the corresponding parameter from the request.id
is 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).actor
is 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.name
is a displayable string labelling the user in the context, if relevant.auth
is the authorization code (typically a reservation token) to present to the Context Server in theentercontext
request to enter the context.hostport
is 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:
context
andid
have the same meanings as in the success case.deny
is 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:
id
is 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.oldpassword
is 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.newpassword
is 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:
hostport
is 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.auth
is 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'sauth
message.
← { to:"gatekeeper", op:"director", hostport:STR }
where:
hostport
is 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:
failure
is 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:
kill
is 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 thekill
flag is true, it will exit immediately without stopping to clean things up. The value defaults to false if the parameter is omitted.