AuthService Web API
AuthService has a simple JSON web interface. It speaks JSON-RPC 2.0, the latest version of the protocol for remote procedure calls (RPC) using JSON-encoded messages. Clients can send their requests to an AuthService instance by HTTP POST.
The following table is an overview of the AuthService web API.
| User authentication and details » | Web service information » |
|---|---|
Each JSON-RPC 2.0 request consists of the following fields:
- The requested method name, e.g. "user.auth" or "user.get".
- The method parameters (if any).
- An arbitrary request ID which is echoed back to the client.
- A string identifying the JSON-RPC protocol version as "2.0".
Example JSON-RPC 2.0 request for simple user authentication:
{
"method" : "user.auth",
"params" : { "username" : "alice", "password" : "secret" },
"id" : "0001",
"jsonrpc" : "2.0"
}
1. User authentication and details
AuthService provides two methods for user authentication: user.auth which simply verifies the supplied username and password, and user.get which, in addition to that, also retrieves a set of user attributes (such as the person's name, email address, phone numbers, photo, etc.) from the directory.
user.auth
Authenticates a user with the specified username and password. Returns
result true on success or false if the
credentials are invalid.
Parameters:
- username {string} A string that identifies the user system / organisation-wide, such as a username, employee number or email address. Must resolve to a valid user entry (DN) in the back-end LDAP directory. See the DN resolution configuration for details.
- password {string} The user password (case sensitive).
Result:
- {true|false} Boolean
trueif the username / password combination is correct, elsefalse.
Examples:
Example request to authenticate a user with email
alice@wonderland.net and password secret:
{ "method" : "user.auth",
"params" : { "username" : "alice@wonderland.net",
"password" : "secret" }
"id" : "0001",
"jsonrpc" : "2.0" }
Response indicating the credentials were valid:
{ "result" : true,
"id" : "0001",
"jsonrpc" : "2.0" }
Response indicating either the username or the password or both were invalid:
{ "result" : false,
"id" : "0001",
"jsonrpc" : "2.0" }
If for some reason the AuthService couldn't process the request (due to bad configuration, the LDAP server being down or other exception) a JSON-RPC error is returned to the client. How verbose the returned error message is depends on the authService.clients.exposeExceptions configuration setting. You may also check the full listing of AuthService error codes and messages.
{ "error" : { "message" : "Client X.509 certificate required",
"code" : -1002 },
"id" : "0001",
"jsonrpc" : "2.0" }
user.get
Authenticates a user with the specified username and password.
If the credentials are valid returns the user's directory attributes specified by the authService.userAttributes configuration setting. DN provisioning and Json2Ldap CID provisioning may also be available to clients if configured.
If the username / password combination is invalid this call returns a -1100 "Invalid credentials" error.
Parameters:
- username {string} A string that identifies the user system / organisation-wide, such as a username, employee number or email address. Must resolve to a valid user entry in the back-end LDAP directory. See the DN resolution configuration for details.
- password {string} The user password (case sensitive).
- [ returnJson2LdapCID=false ] {true|false} This is
an optional parameter. If
truerequests a Json2Ldap connection identifier (CID) bound as the authenticated user to be returned with the response (Json2Ldap CID provisioning must be enabled in the AuthService configuration).
Result:
- {object} Upon successful authentication, a JSON object with the
following properties:
- "DN" {string} If DN provisioning
is enabled, the resolved distinguished name (DN)
of the user. If the user DN could not be resolved
the value is
null. - "attributes" {object} The selected user attributes, as key / value pairs. Binary attribute values are BASE-64 encoded.
- "Json2Ldap" {object} If requested, a JSON object
with the following properties:
- "URL" {string} The URL of the Json2Ldap web service.
- "CID" {string} The Json2Ldap connection identifier (CID) bound
as the authenticated user or
nullif a CID could not be obtained.
- "DN" {string} If DN provisioning
is enabled, the resolved distinguished name (DN)
of the user. If the user DN could not be resolved
the value is
Examples:
Example request to authenticate and retrieve a user with username
alice and password secret:
{ "method" : "user.get",
"params" : { "username" : "alice",
"password" : "s3cr3t" }
"id" : "0001",
"jsonrpc" : "2.0" }
Example response indicating authentication success and returning a the user attributes according to the authService.userAttributes configuration setting. Multi-valued attributes are specified as arrays, even if they contain a single item.
{ "result" : { "attributes" : { "userID" : "alice",
"name" : "Alice Adams",
"email" : [ "alice@wonderland.net" ],
"phone" : [ "+1 685 622 6202",
"+1 010 154 3228",
"+1 225 216 5900" ] },
"id" : "0001",
"jsonrpc" : "2.0" }
If DN provisioning is enabled that distinguished name (DN) of the user in the directory is also included:
{ "result" : { "DN" : "uid=alice,ou=people,dc=wonderland,dc=net",
"attributes" : { "userID" : "alice",
"name" : "Alice Adams",
"email" : [ "alice@wonderland.net" ],
"phone" : [ "+1 685 622 6202",
"+1 010 154 3228",
"+1 225 216 5900" ] } },
"id" : "0001",
"jsonrpc" : "2.0" }
And here if a response with a Json2Ldap URL and connection identifier (CID) bound as the authenticated user:
{ "result" : { "DN" : "uid=alice,ou=people,dc=wonderland,dc=net",
"attributes" : { "userID" : "alice",
"name" : "Alice Adams",
"email" : [ "alice@wonderland.net" ],
"phone" : [ "+1 685 622 6202",
"+1 010 154 3228",
"+1 225 216 5900" ] },
"Json2Ldap" : { "URL" : "http:\/\/ldap.example.com",
"CID" : "9163a3c2-d15a-41af-9b7a-114afed7dd80" } },
"id" : "0001",
"jsonrpc" : "2.0" }
Example response error indicating bad username and / or password:
{ "error" : { "message" : "Invalid credentials",
"code" : -1100 },
"id" : "0001",
"jsonrpc" : "2.0" }
2. Web service information
AuthService also provides three JSON-RPC methods to obtain information
about the web service itself. There are the
ws.getName and
ws.getVersion methods to
identify the software and its version, as well as the
ws.getTime method that reports
the local time at the web server.
ws.getName
Reports the name of web service software.
Parameters: none
Result:
- {string} A string identifying the gateway software, set to "AuthService".
Examples:
Example request message:
{ "method" : "ws.getName",
"id" : 1,
"jsonrpc" : "2.0" }
The response message:
{ "result" : "AuthService",
"id" : 1,
"jsonrpc" : "2.0" }
ws.getVersion
Reports the version of the web service software.
Parameters: none
Result:
- {string} A string identifying the version, e.g. "1.0 (2011-03-16)".
Examples:
Example request message:
{ "method" : "ws.getVersion",
"id" : 1,
"jsonrpc" : "2.0" }
The response message:
{ "result" : "1.0 (2011-03-16)",
"id" : 1,
"jsonrpc" : "2.0" }
ws.getTime
Reports the local web service time in ISO 8601 format yyyy-MM-dd'T'HH:mm:ssZZ, for example "2010-03-31T23:59:59+03:00".
Parameters: none
Result:
- {string} The local web service time with time zone offset.
Examples:
Example request message:
{ "method" : "ws.getTime",
"id" : 1,
"jsonrpc" : "2.0" }
The response message:
{ "result" : "2010-11-15T12:14:41+02:00",
"id" : 1,
"jsonrpc" : "2.0" }
