diff options
Diffstat (limited to 'doc/protocol.txt')
| -rw-r--r-- | doc/protocol.txt | 95 |
1 files changed, 76 insertions, 19 deletions
diff --git a/doc/protocol.txt b/doc/protocol.txt index 05e32f2..b6bc0ba 100644 --- a/doc/protocol.txt +++ b/doc/protocol.txt @@ -1,22 +1,39 @@ - HTTP/AUTH PROTOCOL + HTTPAUTH PROTOCOL The protocol used between the stateful authenticator and the web servers that wish to authenticate is described below. It's a simple text protocol, -similar to HTTP. The web servers send commands and headers to the daemon, +similar to HTTP. The web server sends commands and headers to the daemon, which replies with HTTP codes and headers. Multiple authentication requests can be processed on the same connection, -although the connection is not stateful. A authentication request initially -processed through one connection to the daemon can later be completed -through another. The commands are described below. +although the connection is not necessarily stateful. A authentication +request initially processed through one connection to the daemon can +later be completed through another. The commands are described below. -AUTH method uri +After connecting to the daemon, you'll need to retrieve the initial +'ready' response before sending requests. See below. If the server +responds with a 5xx message then something's gone wrong and no requests +will be accepted on the connection. + + +REQUESTS ------------------------------------------------------------------- + +AUTH authmethod connid method uri The AUTH command asks the daemon to perform authentication - for a given set of headers. + for a given set of header from the client. None of the + arguments should contain spaces. + + authmethod: is the authentication method. Methods are + defined by the daemon in it's config file. + + connid: a unique string identifying the connection from + the client. This is only important when NTLM is + being used. If not, pass a random string. + + method: The HTTP method employed. 'GET' or 'POST' etc... - method: is the authentication type. It might be 'NTLM'. uri: the URI being authenticated. The AUTH command is followed by HTTP headers, one per line @@ -24,23 +41,63 @@ AUTH method uri authentication headers for the authentication protocol being used. Extraneous headers are ignored. - If multiple HTTP headers with the same name are received, then - the last one is used. Note that this is somewhat different than - the HTTP protocol. + Headers should be specified on one line, not 'wrapped' as is + permissible in HTTP. QUIT This closes the connection to the daemon. -The response from the daemon consists of an HTTP code, followed by headers -one per line. Note that only the headers to be added for authentication are -returned. For example: - 401 - Header: value - Header2: value +RESPONSES ------------------------------------------------------------------- + +The response from the daemon consists of a code, followed by a detail +message value or set of values. This is separated from the code by a +space. The content of the detail message is described below. + +The codes are similar to HTTP: + + 100 Ready + (detail is the list of available authmethods) + + 200 Successful Request + (detail is described below) + + 4xx Request Error + (detail is an error message) + + 5xx Server Error + (detail is an error message) + + +READY + +After opening a connection to the daemon, you should receive a response +(outlined below) of 100 indicating ready. The 'detail' value is set +to the list of authmethods that the daemon is configured to provide. +These are separated by spaces: + + 100 Domain Simple Test LDAP + + +SUCCESS + +Successful processing of a request returns a 200. The detail constists of, +an HTTP code to send to the client and the user name (when authentication is +successful). These are separated by spaces. + +In addition the daemon might send a set of headers that must be sent to +the client. These are ended by a blank line. + +A response after client authentication failed might look like this: + + 200 401 + WWW-Authenticate: realm="blah" + +... or a client authentication success response like this: + + 200 200 testo + Authorization-Info: Digest rspauth="2034980294820398" nonce="2049823094328" ... -Success returns a 200, just like normal HTTP. Note that success can contain -headers that must also be sent to the client. |