Commit 65647f60 authored by ale's avatar ale
Browse files

Add documentation for the protocol

parent ddba7d73
......@@ -40,10 +40,8 @@ The authentication server data model is based on the concept of a
in LDAP, but it has to be told the specific details of how to find
them and how to map the information there to what it needs.
# Configuration
The behavior of auth-server can be configured with a YAML file.
The YAML file should contain a dictionary with the following attributes:
......@@ -121,6 +119,15 @@ method, U2F support is currently missing.
## LDAP Backend
The *ldap* backend will look up user information in a LDAP database.
It needs some parameters to be passed in the top-level *ldap_config*
* `uri` of the LDAP server (like *ldapi:///var/run/ldap/ldapi*)
* `bind_dn` is the DN to bind with
* `bind_pw_file` points at a file containing the bind password
The *ldap* backend will currently always attempt to bind on every
### Query definition
......@@ -173,14 +180,85 @@ App-specific passwords should be encoded as colon-separated strings:
The password should be encrypted. The comment is a free-form string
set by the user to tell the various credentials apart.
## OTP implementation
The authentication server uses a very simple implementation of
time-based OTP (TOTP), supporting a single secret per user and without
any fancy features such as emergency tokens etc. The reason for this
is that TOTP authentication requires just plain read-only access to
the user database, while counter-based authentication with proper
token revocation is a read-write, locked operation which is more
difficult to perform on a LDAP backend.
# Usage
The *auth-server* runs on a local UNIX socket. You can use UNIX
permissions to control who has access to this socket. The Debian
package makes it group-readable to the *auth-server* group, so you can
add specific users to it easily.
The daemon can run either standalone or be socket-activated by
systemd, which is what the Debian package does.
## Wire protocol
The rationale behind the wire protocol ("why not http?") is twofold:
first, we wanted strict access control, and that's more easily done
with UNIX permissions, so UNIX sockets were chosen. Then, the protocol
should be able to transfer data maps, and it must be trivial to
implement (and verify) in C, Go and Python. Furthermore, it should
minimize external dependencies.
The protocol is line-based: multiple authentication requests can be
sent over the same connection, but every request must wait for a
response (i.e. no pipelining). Commands are single words, and can be
followed by a space and an attribute/value map. The responses are
simply attribute/value maps.
Attribute maps should have the following characteristics:
* maps can't be nested, they are simple key/value sets where both keys
and values are strings
* keys can't contain '=' characters
They are encoded using the following algorithm:
* if this is not the first attribute/value pair, add a space character
* add the key string
* add the '=' character
* if the value contains a non-printable character or a double quote:
* add the base64-encoded value
* if it does not:
* add a '"' character, then the value, then another '"' character.
## API
There is only one command: `auth`, which must be followed by the
authentication request. Parameters for an authentication request are:
* `service`: the service requesting the authentication
* `username`: name of the user to authenticate
* `password`: password (cleartext) provided by the user
* `otp` (optional): TOTP-based 2FA token
* `u2f_app_id` (optional): U2F AppID
* `u2f_response` (optional): U2F response object
* `key_handle`
* `signature_data`
* `client_data`
* `device` (optional): information about the client device
* `id`: a unique ID, specific to this device
* `remote_addr`: remote IP address (will be minimized)
* `remote_zone`: remote zone (country-level IP aggregation)
* `browser`: browser name
* `os`: client OS
* `user_agent`: client User-Agent string
* `mobile`: boolean variable indicating a mobile device
Responses will contain the following attributes:
* `status`: status of the request, one of *ok*,
*insufficient_credentials* or *error*
* `2fa_method`: if *status* is *insufficient_credentials*, one of
*otp* or *u2f* indicating which 2FA method should be used for the
next request
* `u2f_req`: when *2fa_method* is *u2f*, this field will contain a U2F
SignResponse object:
* `version`
* `challenge`
* `registered_keys`: a list of registered keys
* `user`: when *status* is *ok* (the authentication has been
successful), this dictionary will contain user information:
* `email`: email of this user
* `groups`: groups the user is a member of.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment