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.
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>¶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.
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 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
,
'-
' for "empty list"/"no data"--
' 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.
A backend may support to return the response in the form of small JSON documents.
To trigger json response, add the parameter json=1
to the request, like this:
POST /my/authentication/service HTTP/1.1 Host: auth.my.domain Content-Type: application/x-www-form-urlencoded op=<op>&json=1¶m1=<value1>¶m2=<value2> |
To explicitly disable JSON response, use json=0
instead.
Backends might choose to support only one variant, only with or only without JSON response.
With JSON reponses on, the repsonse is either
a short info message, like
{ "info" : "Some message to use in log files" } |
or an error message for "not supported by backend" or similar problems, like
{ "error" : "Operation not supported by backend for specified domain" } |
op=tryLogin&user=<user>&domain=<domain>&passwd=<passwd> |
The domain
parameter is optional.
user=<user>&passwd=<passwd> |
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
Successful:
{ "user" : "jdoe", "prettyName" : "John Doe", "eMailAddress" : "jdoe@foo.bar" } |
Not found or problem: See documentation of "searchUser".
op=getSupportedFeatures |
List of suppored operations, separated by ',
'.
Example showing minimal feature set:
getSupportedOperations,tryLogin |
Example specifying maximum feature set:
getSupportedOperations,tryLogin,changePassword,deactivateUser,getDefaultDomain,getGroups,sendPassword,searchUser |
[ "getSupportedOperations", "tryLogin" ] |
Changes the password of the user.
op=changePassword&user=<user>&domain=<domain>&oldPassword=<oldPassword>&newPassword=<newPassword>&newPasswordConfirmed=<newPassword> |
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.
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
Deactivates a user, prevents him for logging in again.
op=deactivateUser&user=<user>&domain=<domain> |
The domain
parameter is optional.
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
Returns the default domain, if there is any.
op=getDefaultDomain |
Default authentication domain, or '-
' if there is no default domain, or '--
' if there is no domain support at all.
[ "SOMEDOMAIN" ] |
Returns the groups the user is a member of.
op=getGroups&user=<user>&domain=<domain> |
The domain
parameter is optional.
List of group names, separated by ',
' or just '-
' if the user is not member of any group, or '--
' if there is no group support.
The following example shows a list of 2 groups, one with maximum details, one wiht miniimal details:
[ { "group" : "users", "prettyName" : "Human users of this system", "domain" : "MYDOMAIN" } , { "group" : "dialout" } ] |
Returns the users the are a member of the specified group.
op=getGroupMembers&group=<group>&domain=<domain> |
The domain
parameter is optional.
List of group names, separated by ',
' or just '-
' if the user is not member of any group, or '--
' if there is no group support.
[ { "user" : "leonard", "prettyName" : "Leonard Hofstaetter", "eMailAddress" : "lh@tbbt.foo.bar" } , { "user" : "penny" } , { "user" : "sheldon" } ] |
Generates a new password or send a "new password" link to the user.
op=sendPassword&user=<user>&domain=<domain> |
The domain
parameter is optional.
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
Searches a user in the database, sets response code to 200 if the user is there, 404 if the user could not be found.
op=searchUser&user=<user>&domain=<domain> |
The domain
parameter is optional.
Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
Successful, with response code 200:
{ "user" : "jdoe", "prettyName" : "John Doe", "eMailAddress" : "jdoe@foo.bar" } |
Not found, with response code 404:
{ "error" : "user not found" } |
Problem, with repsonse code 500:
{ "error" : "Operation not supported by backend for specified domain" } |