Skip to main content

users/authenticate (POST) (TCS)

Overview

Authenticate a user given http header Credentials or an auth token. When using external authentication, this will automatically create an account and synchronize groups. Response status 200 implies valid credentials and contains a new auth token.

  • REST Method: POST
  • Method Access: public

Query Parameters

Name Type Description
callback string? If specified, return response as a jsonp call using the provided callback.
ssotoken string? Token from remote auth service to be used for internal SSO authentication.
authprovider int? Identifier for the external service to use for authentication.
redirect uri? Redirect to the given URI upon authentication

Return Codes

Name Value Description
OK 200 The request completed successfully
Bad Request 400 Invalid input parameter or request body
Unauthorized 401 Login has failed
Conflict 409 Username conflicts with an existing username

Message Format

Output:
Content-type=text/plain

Implementation Notes

If the login credentials are valid, this feature returns an authentication token in the response text and an 'authtoken' cookie. This cookie can be used with subsequent requests to execute using the  login credentials.

This feature is identical to GET:users/authenticate, except that it automatically creates new users when using external authentication.

C# Sample: Authenticate User

The following code example authenticates the the "admin" user using the local authentication service:

Sample Code 

Plug p = Plug.New("http://deki-hayes/@api/deki"); 
DreamMessage msg = p.At("users", "authenticate").WithCredentials("admin", "password").Post(); 
String cookieText = msg.Cookies[0].ToString(); 

Sample Response from executing Code

 $Version=1; authtoken=1_633245325345625000_12276545af9bf1f3c24c382c7211760a; $Path=/; $Domain=deki-hayes  

Curl Sample: Authenticate User

The following command authenticates a user and retrieves an authentication token:

Sample Code

curl -u username:password -H "Content-Type: text/plain" -d "" http://192.168.59.128/@api/deki/users/authenticate

HTTP Response Headers

HTTP/1.1 200 OK
Date: Tue, 19 Jan 2010 20:04:57 GMT
Server: Dream-HTTPAPI/2.0.0.17629 Microsoft-HTTPAPI/2.0
Content-Length: 53
Content-Type: text/plain; charset=utf-8
P3P: CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"
X-Data-Stats: request-time-ms=6; mysql-queries=5; mysql-time-ms=5;
X-Deki-Site: id="default"
Set-Cookie: authtoken="1_633995282975283345_9370c2b345bdf559ad2e996dca5adf37"; Domain=192.168.59.128; Expires=Tue, 26-Jan-2010 20:04:57 GMT; Version=1; Path=/
Via: 1.1 dekiwiki
Vary: Accept-Encoding

Sample Response from executing Code

Content-Type: text/plain

1_633995282975283345_9370c2b345bdf559ad2e996dca5adf37

Implementation notes 

curl flags

-u
Basic HTTP authentication. Sends a username and password to server so it can verify whether a user is of privilege to perform specific operation.
-d
Specifies a POST request. The quotations ("") are used to imply no data is to be sent.
-H
Replaces or appends an HTTP header. The "Content-Type" header specifies the MIME type of the value attached to the property. In this case, it doesn't really matter, but use text/plain as a precaution.
-i
Includes the HTTP response header in the output. Useful for debugging.
  • Was this article helpful?