HTTP authentication API NG
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.
Contents
Basic Handshake Pattern
Basic Request Pattern
A request to an authentication URL is a HTTPS POST request like this:
Host: auth.my.domain
Content-Type: application/x-www-form-urlencoded
op=<op>¶m1=<value1>¶m2=<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 detailed examples.
Basic Response pattern
Every respond to an authentication request is answered with a HTTP response with
and on of the following status codes:
403 Forbidden - the login is invalid or the operation is not permitted
404 Not found - if a user could not be found during a search operation
406 Not Acceptable - too many unsuccessful authentications, or other reason to suspect a brute force attack
The response body must not be empty and must be UTF-8 encoded, it's content is specified differently for each operation.
For most operations the reponse is either
- a short message for logging (not more than 1024 bytes)
- or a list of values separated by ','
- or '-' for "empty list"/"no data"
- or '–-' for "not supported by backend"
The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.
Required operations
tryLogin
Request body (new format, preferred):
The domain parameter is optional.
Request body in old format, supported for backward compatibility reasons:
Response body:
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
getSupportedOperations
Request body (new format, preferred):
Response body:
List of suppored operations, separated by ','.
Example showing minimal feature set:
Example specifying maximum feature set:
Optional Operations
changePassword
Changes the password of the user.
Request body:
The domain parameter is optional.
The newPasswordConfirmed parameter is optional and available only to simplify writing web interfaces. If it is specified and does not match newPassword, the password is not changed.
Response body:
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
deactivateUser
Deactivates a user, prevents him for logging in again.
Request body:
The domain parameter is optional.
Response body:
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
getDefaultDomain
Returns the default domain, if there is any.
Request body (new format, preferred):
Response body:
Default authentication domain, or '-' if there is no default domain, or '--' if there is no domain support at all.
getGroups
Returns the groups the user is a member of.
Request body:
The domain parameter is optional.
Response body:
List of group names, separated by ',' or just '-' if the user is not member of any group, or '--' if there is no group support.
getGroupMembers
Returns the users the are a member of the specified group.
Request body:
The domain parameter is optional.
Response body:
List of group names, separated by ',' or just '-' if the user is not member of any group, or '--' if there is no group support.
sendPassword
Generates a new password or send a "new password" link to the user.
Request body:
The domain parameter is optional.
Response body:
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
searchUser
Searches a user in the database, sets response code to 200 if the user is there, 404 if the user could not be found.
Request body:
The domain parameter is optional.
Response body:
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.