Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.


Abiquo 2.4


Skip to end of metadata
Go to start of metadata

Token Authentication

The Abiquo API uses a cookie as a token that can be used in subsequent API calls to provide user identity. This token can be used to access the UI without being prompted for the credentials. The following procedure explains how to obtain the authentication token and how to provide it to the client UI.

The Abiquo authentication flow is: cookie token, URL token, login screen. The cookie token authentication method is recommended because it is more secure than the URL authentication method and for this reason it is the first method used by default.

Obtaining the Authentication Token

To obtain the authentication token, perform an API call as explained in the Authentication section of the API documentation. An example is given below.

Example API Request

% curl --verbose 'http://example.com/api' \
        -X GET \
        -H "Authorization: Basic ZXhhbXBsZTpleGFtcGxl"

> GET /api HTTP/1.1
> User-Agent: curl/7.19.5 (x86_64-pc-linux-gnu) libcurl/7.19.5 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.15
> Host: example.com
> Authorization: Basic ZXhhbXBsZTpleGFtcGxl
> Content-Type:application/xml
> Accept:application/xml

Example API Response Headers

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=YWRtaW46MTI4NjM2Mzk4MDMzMTpiOTIxODVhZThmNTRmZTRiZWY3YzU0M2Y3YzljNWQ2Mw; Expires=Wed, 06-Oct-2010 11:19:40 GMT; Path=/api
< Set-Cookie: JSESSIONID=ECBB24FCE7BA09A8C1951B3EEA77257F; Path=/api
< Content-Type: application/atomsvc+xml
< Content-Length: 886
< Date: Wed, 06 Oct 2010 10:49:40 GMT

The important part of the response is the cookie:

auth=YWRtaW46MTI4NjM2Mzk4MDMzMTpiOTIxODVhZThmNTRmZTRiZWY3YzU0M2Y3YzljNWQ2Mw

This will be passed to the client to provide user identity.

Token Expiration

By default the authentication token has a lifetime of 30 minutes. After that time, a new token must be obtained.

Accessing the client with the authentication token

Cookie Access

The token can be registered in a cookie instead of the URL. The token is registered in a temporary browser cookie and deleted when the user logs in.
The workflow is as follows:

  1. On the customer's portal, the valid token must be created calling the API and saved into a browser cookie
  2. On the same page, a link to the cloud platform must be clicked
  3. The cloud platform will check if a token exists (but with a javascript function, not by reading the URL)
  4. If the token exists, automatic login occurs and the cookie is eliminated

If the token is not found in the cookie, Abiquo checks for token in the URL. If the token is not present, the login screen is displayed. The cookie authentication method is recommended because it is more secure than the URL.

Create Cookies on a Non-Abiquo Server

You can create cookies on a non-Abiquo Server. The client domain must have access to the cookie domain so that it can delete the cookie on login. To use this functionality, enter the domain and path in the cookie_vars.js file. By default, this file is located in the directory /opt/abiquo/tomcat/webapps/client-premium/javascriptsupport. The example below is for cookies created in the "/" directory of mydomain.com.

cookie_vars.js
var AbqCookieDomain = "mydomain.com"; // insert the domain against which the 'token' cookie was created, eg. "example.com"
var AbqCookiePath = "/"; // insert the path on which the 'token' cookie was created, eg. "/"

URL Access

The token can be appended as a query parameter to the client URI as follows:

# Enterprise edition client
http://example.com/client-premium?auth=YWRtaW46MTI4NjM2Mzk4MDMzMTpiOTIxODVhZThmNTRmZTRiZWY3YzU0M2Y3YzljNWQ2Mw

How to Test Cookie-based Access

To test this feature, please follow these steps:
1. Download this file (test.html) and place it in the $_TOMCAT/webapps/client-premium folder on the Abiquo Enterprise Edition server

2. In a web browser, connect to http://example.com/client-premium/test.html

3. Click the "Add the token value in the cookie" link and add a valid token

Token Syntax

The token must be saved in a cookie named token with the following syntax:

auth=XXXXXX or auth=XXXXX&lang=XX if the language is specified.

The language code must be the same one used in the client-config.xml.jsp file. See Abiquo GUI Client Language Configuration.

4. Click the "connect to cloud platform by cookie token" link to access the platform

How to Use Token Authentication in a Custom Environment

The above example shows how to test this feature, but some points must be considered for a custom installation.

The way the token is generated by the API and retrieved into the web browser is specific to each installation, so this step must be done by the customer.

To register the token into a cookie, use the following javascript function:

function setCookie(c_name,value,exdays)
{
  var exdate=new Date();
  exdate.setDate(exdate.getDate() + exdays);
  var c_value=escape(value) + ((exdays==null) ? "" : "; expires="+exdate.toUTCString());
  document.cookie=c_name + "=" + c_value;
}

Cookie Name

The cookie name must be token, otherwise it will not work

setCookie("token",value_of_generated_token,1);

Finaly, the link to the cloud platform must refer to the "index.html" cloud page

<a href="index.html">connect to cloud platform by cookie token</a><br>