Page Comparison

...

Contents

...

class	tocc

Table of Contents

Author: Ignasi Barrera

Authentication methods

...

Abiquo has chosen to implement OAuth 1 because it is more secure and interoperable than OAuth 2. See https://hueniverse.com/oauth-2-0-and-the-road-to-hell-8eec45921529

...

Once you have the token, you can issue requests to the API by providing the following HTTP header:

Code Block
Authorization: Bearer <the access token>

And you can use the Refresh token as necessary.

See Abiquo OpenID Connect Integration

SAML

When you use SAML 2.0 you can disable basic authentication, but you can still use OAuth or a session token to access the API as before. See SAML Integration.

...

Request Headers: Accept, Content-Type.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

...

class	tinycode

Code Block

title	GET Datacenters Request

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept:application/vnd.abiquo.datacenters+xml"

> GET /api/admin/datacenters 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: exmaple.com
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, WWW-Authenticate, Date.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the unauthenticated GET over a Datacenters resource

...

tinycode

Code Block

	xml
	xml
title	GET Datacenters Response

< HTTP/1.1 401 Unauthorized
< Server: Apache-Coyote/1.1
< WWW-Authenticate: Basic realm="Abiquo"
< Content-Type: text/html;charset=utf-8
< Content-Length: 1152
< Date: Fri, 02 Jul 2010 09:40:14 GMT

Request a resource providing valid credentials

Request Headers: Accept, Content-Type, Authentication.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

...

class	tinycode

Code Block

title	GET Datacenters Request

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept:application/vnd.abiquo.datacenters+xml" \
        -H "Authorization: Basic ZXhhbXBsZTpleGFtcGxl"

> GET /api/admin/datacenters 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
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, Date, X-Abiquo-Token.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the authenticated GET over a Datacenters resource

...

Code Block

	xml
	xml
title	GET Datacenters Response

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Abiquo-Token: 1169dbbca2c1123455ab6b5a06b2b38756fb
< Content-Type: application/vnd.abiquo.datacenters+xml
< Content-Length: 420
< Date: Fri, 02 Jul 2010 09:50:52 GMT
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<datacenters>
    <datacenter>
        <link href="http://example.com/api/admin/datacenters/1" rel="edit"/>
        <link href="http://example.com/api/admin/datacenters/1/racks" rel="racks"/>
        <link href="http://example.com/api/admin/datacenters/1/remoteServices" rel="remoteServices"/>
        <id>1</id>
        <location>Redwood city</location>
        <name>myDatacenter</name>
    </datacenter>
</datacenters>

After a successful request, the response will contain the X-Abiquo-Token header with an authentication token that can be used in subsequent requests, as described in the Token Based Authentication section.

...

Request Headers: Accept, Content-Type, Authentication.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

...

tinycode

Code Block

title	GET Datacenters Request

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept: application/vnd.abiquo.datacenters+xml" \
        -H "Authorization: Basic ZXhhbXBsZTpleGFtcGxl"

> GET /api/admin/datacenters 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
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, Date.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the authenticated GET over a Datacenters resource, but without enough privileges

Div

class	tinycode

Code Block

	xml
	xml
title	GET Datacenters Response

< HTTP/1.1 403 Forbidden
< Server: Apache-Coyote/1.1
< Content-Type: text/html;charset=utf-8
< Content-Length: 1021
< Date: Fri, 02 Jul 2010 09:59:42 GMT

Token based authentication

...

Request Headers: Accept, Content-Type.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

...

tinycode

Code Block

title	GET Datacenters Request

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept:application/vnd.abiquo.datacenters+xml"

> GET /api/admin/datacenters 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: exmaple.com
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, WWW-Authenticate, Date.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the unauthenticated GET over a Datacenters resource

...

Code Block

	xml
	xml
title	GET Datacenters Response

< HTTP/1.1 401 Unauthorized
< Server: Apache-Coyote/1.1
< WWW-Authenticate: Token realm="Abiquo"
< Content-Type: text/html;charset=utf-8
< Content-Length: 1152
< Date: Fri, 02 Jul 2010 09:40:14 GMT

Request a resource providing valid credentials

Request Headers: Accept, Content-Type, Authentication.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

Div

class	tinycode

Code Block

title	GET Datacenters Request

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept:application/vnd.abiquo.datacenters+xml" \
        -H "Authorization: Token 1169dbbca2c1da4da5ab6b5a06b2b38756fb"

> GET /api/admin/datacenters 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: Token 1169dbbca2c1da4da5ab6b5a06b2b38756fb
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, Date, X-Abiquo-Token.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the authenticated GET over a Datacenters resource

Div

class	tinycode

Code Block

	xml
	xml
title	GET Datacenters Response

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Abiquo-Token: 1169dbbca2c1123455ab6b5a06b2b38756fb
< Content-Type: application/vnd.abiquo.datacenters+xml
< Content-Length: 420
< Date: Fri, 02 Jul 2010 09:50:52 GMT
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<datacenters>
    <datacenter>
        <link href="http://example.com/api/admin/datacenters/1" rel="edit"/>
        <link href="http://example.com/api/admin/datacenters/1/racks" rel="racks"/>
        <link href="http://example.com/api/admin/datacenters/1/remoteServices" rel="remoteServices"/>
        <id>1</id>
        <location>Redwood city</location>
        <name>myDatacenter</name>
    </datacenter>
</datacenters>

Two factor authentication

...

Get the information of the current user:

div

class	tinycode

Code Block

title	GET User Info

% curl -v -u admin:xabiquo http://example.com/api/login -H "Accept:application/vnd.abiquo.user+xml"

> GET /api/login HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.38.0
> Host: example.com
> Accept:application/vnd.abiquo.user+xml

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=YWRtaW46MTQ0MzcxMDM3NDgxMzphZjdjNTY1ZjJhNDgzNTc4Y2EyZGEzNTJiNTcwNmE3ZDpBQklRVU8; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly
< Set-Cookie: ABQSESSIONID=1691863788974462744; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly
< Content-Type: application/vnd.abiquo.user+xml
< Content-Length: 1422
< Date: Thu, 01 Oct 2015 14:09:35 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
 <link title="Abiquo" rel="enterprise" type="application/vnd.abiquo.enterprise+xml" href="http://example.com:80/api/admin/enterprises/1"/>
 <link title="CLOUD_ADMIN" rel="role" type="application/vnd.abiquo.role+xml" href="http://example.com:80/api/admin/roles/1"/>
 <link title="admin" rel="edit" type="application/vnd.abiquo.user+xml" href="http://example.com:80/api/admin/enterprises/1/users/1"/>
 <link title="virtual machines" rel="virtualmachines" type="application/vnd.abiquo.virtualmachines+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/action/virtualmachines"/>
 <link title="pending tasks" rel="pendingtasks" type="application/vnd.abiquo.tasks+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/action/pendingtasks"/>
 <link title="applications" rel="applications" type="application/vnd.abiquo.applications+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/applications"/>
 <link title="enable two factor authentication" rel="enable2fa" type="application/vnd.abiquo.twofactorauthcredentials+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/action/enable2fa"/>
 <id>1</id>
 <nick>admin</nick>
 <name>Cloud</name>
 <surname>Administrator</surname>
 <description>Main administrator</description>
 <email></email>
 <locale>en_US</locale>
 <authType>ABIQUO</authType>
 <active>true</active>
 <firstLogin>false</firstLogin>
 <locked>false</locked>
</user>

The user info contains a link enable two factor authentication . To enable two factor authentication, send a POST request indicating the type of two-factor authentication to enable.

div

class	tinycode

Code Block

title	Enable two factor authentication

% curl -v -u admin:xabiquo -X POST http://localhost:80/api/admin/enterprises/1/users/1/action/enable2fa \
    -H "Accept: application/vnd.abiquo.twofactorauthcredentials+json" \
    -H "Content-type: application/vnd.abiquo.twofactorauthprovider+json" \
    -d '{"type": "GOOGLE_AUTHENTICATOR"}'

> POST /api/admin/enterprises/1/users/1/action/enable2fa HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.38.0
> Host: localhost
> Accept: application/vnd.abiquo.twofactorauthcredentials+json
> Content-type: application/vnd.abiquo.twofactorauthprovider+json
> Content-Length: 32

< HTTP/1.1 201 Created
* Server Apache-Coyote/1.1 is not blacklisted
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=YWRtaW46MTQ0MzcxMTM2NTcyNzpjOWJmYzczMmRlOGU3ODBmMzFiN2JkYmZhN2RiMTYzMDpBQklRVU8; Expires=Thu, 01-Oct-2015 14:56:05 GMT; Path=/; HttpOnly
< Set-Cookie: ABQSESSIONID=3703152771382913736; Expires=Thu, 01-Oct-2015 14:56:05 GMT; Path=/; HttpOnly
< Content-Type: application/vnd.abiquo.twofactorauthcredentials+json
< Transfer-Encoding: chunked
< Date: Thu, 01 Oct 2015 14:26:05 GMT

{
   "authenticatorURL" : "otpauth://totp/Abiquo:admin?secret=UXEHFMAX7RXAJHYE&issuer=Abiquo",
   "links" : [],
   "provider" : "GOOGLE_AUTHENTICATOR",
   "scratchCodes" : [
      "88309169",
      "40838958",
      "93393020",
      "91684230",
      "17576595"
   ]
}

The value of the type field can be one of the following: EMAIL, GOOGLE_AUTHENTICATOR.
The response comes with all the two-factor authentication details:

...

When two factor authentication is enabled, normal requests using Basic Authentication will fail and the two factor verification code will be requested:

...

Code Block

title	GET user info without the verification code

% curl -v -u admin:xabiquo http://example.com/api/login -H "Accept:application/vnd.abiquo.user+xml"

> GET /api/login HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.38.0
> Host: example.com
> Accept:application/vnd.abiquo.user+xml


< HTTP/1.1 401 Unauthorized
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=""; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/api
< WWW-Authenticate: Basic realm="Abiquo"
< X-Abiquo-OTP: required; type=GOOGLE_AUTHENTICATOR

Note the header: X-Abiquo-OTP: required;

...

Once the user has the verification code, it can be provided in the X-Abiquo-OTP header, as follows:

...

class	tinycode

Code Block

title	GET User Info with the verification code

% curl -v -u admin:xabiquo http://example.com/api/login \
    -H "Accept:application/vnd.abiquo.user+xml" \
    -H "X-Abiquo-OTP: 670870"

> GET /api/login HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.38.0
> Host: example.com
> Accept:application/vnd.abiquo.user+xml
> X-Abiquo-OTP: 637614

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=YWRtaW46MTQ0MzcxMDM3NDgxMzphZjdjNTY1ZjJhNDgzNTc4Y2EyZGEzNTJiNTcwNmE3ZDpBQklRVU8; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly
< Set-Cookie: ABQSESSIONID=1691863788974462744; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly
< Content-Type: application/vnd.abiquo.user+xml
< Content-Length: 1422


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
 <link title="Abiquo" rel="enterprise" type="application/vnd.abiquo.enterprise+xml" href="http://example.com:80/api/admin/enterprises/1"/>
 <link title="CLOUD_ADMIN" rel="role" type="application/vnd.abiquo.role+xml" href="http://example.com:80/api/admin/roles/1"/>
 <link title="admin" rel="edit" type="application/vnd.abiquo.user+xml" href="http://example.com:80/api/admin/enterprises/1/users/1"/>
 <link title="virtual machines" rel="virtualmachines" type="application/vnd.abiquo.virtualmachines+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/action/virtualmachines"/>
 <link title="pending tasks" rel="pendingtasks" type="application/vnd.abiquo.tasks+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/action/pendingtasks"/>
 <link title="applications" rel="applications" type="application/vnd.abiquo.applications+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/applications"/>
 <link title="enable two factor authentication" rel="enable2fa" type="application/vnd.abiquo.twofactorauthcredentials+xml" href="http://example.com:80/api/admin/enterprises/1/users/1/action/enable2fa"/>
 <id>1</id>
 <nick>admin</nick>
 <name>Cloud</name>
 <surname>Administrator</surname>
 <description>Main administrator</description>
 <email></email>
 <locale>en_US</locale>
 <authType>ABIQUO</authType>
 <active>true</active>
 <firstLogin>false</firstLogin>
 <locked>false</locked>
</user>

Disable two factor authentication

Two factor authentication can be disabled at any time. As in the enable process, the user information will contain a link that points to the location where two factor authentication can be disabled. Users just have to perform a POST request there to disable it:

...

Code Block

title	Disable two factor authentication

% curl -v -u admin:xabiquo http://localhost:80/api/admin/enterprises/1/users/1/action/disable2fa \
    -x POST
    -H "X-Abiquo-OTP: 670870"

> POST /api/admin/enterprises/1/users/1/action/disable2fa HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.38.0
> Host: localhost
> Accept: */*
> X-Abiquo-OTP: 670870

< HTTP/1.1 204 No Content
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=YWRtaW46MTQ0MzcxMjI0MzM2Mzo5OTkxYTRlMGJmMzBlYjcwZmVjNjYwNDQyYmFkZTlkMjpBQklRVU8; Expires=Thu, 01-Oct-2015 15:10:43 GMT; Path=/; HttpOnly
< Set-Cookie: ABQSESSIONID=2563697997063896162; Expires=Thu, 01-Oct-2015 15:10:43 GMT; Path=/; HttpOnly

Version	Old Version 14	New Version 15
Changes made by	MS	MS
Saved on	Feb 20, 2020	Aug 05, 2020

Versions Compared

Key

Authentication methods

SAML

Request a resource providing valid credentials

Token based authentication

Request a resource providing valid credentials

Two factor authentication

Disable two factor authentication