Authentication

Author: Ignasi Barrera

Authentication methods

The Abiquo API implements the following authentication to prevent unauthorized access to API resources:

• OAuth v1.0 Authentication as defined in the RFC 5849: The OAuth 1.0 Protocol
  
  

• OpenID Connect as described at How OpenID Connect Works - OpenID Foundation  and including the core spec and optional features such as the  RP-Initiated-Logout  but not Discovery, dynamic registration, and other optional features. See Abiquo OpenID Connect integration. 
  
  

• SAML 2.0. See SAML integration
  
  

• Basic HTTP Authentication as defined by RFC 2617

  • Under basic auth, Abiquo UI supports two-factor authentication for added security

OAuth v1.0 Version A authentication

You can use OAuth to authenticate against the Abiquo API. With OAuth, users can create their own applications and connect them to the Abiquo API in a controlled and standard way.

Users can register their own applications using

• Abiquo API, see ApplicationsResource

• Abiquo UI, see Add an application for OAuth

The Abiquo API implements the OAuth 1.0 protocol, so any application that implements it can be used to consume the Abiquo API. The basic authentication workflow for an already registered application, as defined by the protocol, consists of the following steps:

1. The client application requests an Unauthenticated Request Token.

2. The user authorizes the Request Token.

3. The client application exchanges the Request Token for an Access Token.

When the Access Token has been granted, the client application can use it to sign the requests and authenticate against the Abiquo API.

The following table shows the OAuth specific endpoints that must be used when implementing the OAuth workflow.

The following table describes the query parameters that are used in the OAuth authentication workflow:

Why OAuth 1?

Abiquo chose to implement OAuth 1 because at the time it was considered more secure and interoperable than OAuth 2.
See https://hueniverse.com/oauth-2-0-and-the-road-to-hell-8eec45921529

OAuth example applications

For an example of an Abiquo authentication flow, please see the following Python and Ruby applications: https://gist.github.com/nacx/8581621

OpenID Connect

When you use OpenID Connect, Abiquo disables basic authentication, but you can still use OAuth or a session token to access the API as before. Or you can obtain OpenID Connect tokens by doing these steps:

1. Manually log in to the platform

2. When you are redirected back to the Abiquo console, obtain the access token and refresh token from the browser.

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

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.

Basic HTTP authentication

Authentication following the Basic HTTP Authentication standard. The client must provide its credentials in base64 format, sending them in a request header in the form:

Authentication header format

For example, for (user:user):

Authentication header format

The authentication workflow should be as follows:

1. The client requests a resource, without providing any credentials.

2. An HTTP response code 401 (Unauthorized) is returned.

3. The client requests the resource providing the credentials.
   
   

   1. If authentication fails, the server returns an HTTP response code 401 (Unauthorized), indicating a Bad Credentials or a User is disabled error.

   2. If authentication succeeds but the user does not have enough privileges to access the requested resource, an HTTP response code 403 (Forbidden) indicating a Denied Access error is returned.

   3. If authentication is successful, the server returns an HTTP reponse code 200 (OK), the requested resource, and an authentication token that the client can use to authenticate future requests.

4. The client requests another resource, providing the authentication token

Basic authentication workflow example

Request a resource without providing credentials

Request headers: Accept, Content-Type.
Request parameters: N/A.
Request message body: N/A.
Request example: Retrieve all the datacenters

GET datacenters request

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

GET datacenters response

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

GET datacenters request

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

GET datacenters response

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 a resource providing valid credentials but with insufficient privileges

Request headers: Accept, Content-Type, Authentication.
Request parameters: N/A.
Request message body: N/A.
Request example: Retrieve all the datacenters

GET datacenters request

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

GET datacenters response

Token-based authentication

To avoid exposing user credentials, Abiquo provides token-based authentication. For each authenticated request, Abiquo generates an authentication token that can be used to make requests to the API without the need of passing the credentials. Each HTTP response contains a header with an expirable token that can be used to perform requests to the API. In order to use  token-based authentication, the client must send it in the "Authorization" header, as follows:

Authentication header format for token-based authentication

After a successful request, the response will contain the X-Abiquo-Token header with a new token that can be used in subsequent requests.

Request a resource without providing credentials

Request headers: Accept, Content-Type.
Request parameters: N/A.
Request message body: N/A.
Request example: Retrieve all the datacenters

GET datacenters request

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

GET datacenters response

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

GET datacenters request

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

GET datacenters response

Two factor authentication

With Basic Authentication, Abiquo can protect user accounts with a two factor authentication code. When two factor authentication is enabled, users will be required to provide an additional verification code to prove their identity. That token will be delivered to the user by Abiquo, using the configured mechanism. Currently there are two supported ways of getting the verification code:

Enable two factor authentication

The following step-by-step example shows how to enable two factor authentication for a user:

1. Get the information of the current user:

   GET user info

    

2. 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.

   
   Enable two factor authentication

   
   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:

•  

  • The list of "scratch codes" that can be used for recovery in case the verification code is lost, or there is an issue with the Google Authenticator mobile app.

  • The "authenticationURL" that can be used to enable Abiquo in the Google Authenticator mobile app: it can be used to generate a QR code that can be directly scanned using the app, or the URL can be manually typed in it.

Interaction with the API with two factor authentication enabled

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

GET user info without the verification code

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

That header indicates that the verification code is missing, and the type parameter indicates how the user can get it. The possible values are:

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

GET user info with the verification code

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:

Disable two factor authentication