Skip to Content

HTTP authentication API NG

Version 1.1 by christoph_lechleitner@iteg_at on 2012-09-21 11.47:16

Motivation

org.clazzes.login.http is a the HTTP based implementation of DomainPasswordLoginService.

While the old HTTP authentication request is satisfying for user/password checks, new optional features like group membership queries require new handshakes for the HTTP backend API.

This document speficies the next-gen HTTP authentication API.

Basic Request pattern

A request to an authentication URL is a HTTPS POST request like this:

POST /my/authentication/service HTTP/1.1
Host: auth.my.domain
Content-Type: application/x-www-form-urlencoded

[op=<op>&]param1=<value1>&param2=<value2>

<op> is the operation requested, usually the name of the method in DomainPasswordLoginService.java.

To provide backwards compatibility, the op parameter is optional and defaults to tryLogin.

See below for examples.

Basic Response pattern

Every respond to an authentication request is answered with a HTTP response with

Content-Type: text/plain; charset=utf-8

and on of the following status codes:

200 OK - login is ok, or other operation was completed successfully
403 Forbidden - the login is invalid or the operation is not permitted
406 Not Acceptable - too many unsuccessful authentications, or other reason to suspect a brute force attack

The response body must not be empty, it's content is specified differently for each operation.

 The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.

Authentication operation: tryLogin

Request body (new format, preferred):

op=tryLogin&user=<user>&passwd=<passwd>

Request body in old format, supported for backward compatibility reasons:

user=<user>&passwd=<passwd>

Response body:

Non-empty information text encoded in UTF-8, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.

Further operations: TBD