{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"11d12753-dcc6-4945-96a8-26029e708835"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"89a406b3-7b40-447b-9376-cec34e11d44c"}},{"type":"paragraph","content":[{"text":"Author:","type":"text","marks":[{"type":"strong"}]},{"text":" Ignasi Barrera","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authentication methods","type":"text"}]},{"type":"paragraph","content":[{"text":"The Abiquo API implements the following authentication to prevent unauthorized access to API resources:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OAuth v1.0 Authentication","type":"text","marks":[{"type":"strong"}]},{"text":" as defined in the ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://tools.ietf.org/html/rfc5849"}},{"text":" ","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OpenID Connect","type":"text","marks":[{"type":"strong"}]},{"text":" as described at ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://openid.net/connect/"}},{"text":" and including the ","type":"text"},{"text":"core spec","type":"text","marks":[{"type":"link","attrs":{"href":"https://openid.net/specs/openid-connect-core-1_0.html"}}]},{"text":" and optional features such as the ","type":"text"},{"text":" ","type":"text","marks":[{"type":"link","attrs":{"href":"http://openid.net/specs/openid-connect-session-1_0.html#RPLogout"}}]},{"text":"RP-Initiated-Logout","type":"text","marks":[{"type":"em"},{"type":"link","attrs":{"href":"https://openid.net/specs/openid-connect-session-1_0.html#RPLogout"}}]},{"text":" ","type":"text","marks":[{"type":"link","attrs":{"href":"http://openid.net/specs/openid-connect-session-1_0.html#RPLogout"}}]},{"text":" but not Discovery, dynamic registration, and other optional features. See ","type":"text"},{"text":"Abiquo OpenID Connect integration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/doc/pages/311375537"}}]},{"text":". ","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SAML 2.0","type":"text","marks":[{"type":"strong"}]},{"text":". See ","type":"text"},{"text":"SAML integration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/doc/pages/311376236"}}]},{"text":" ","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Basic HTTP Authentication","type":"text","marks":[{"type":"strong"}]},{"text":" as defined by ","type":"text"},{"text":"RFC 2617","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.ietf.org/rfc/rfc2617.txt"}}]},{"text":" ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Under basic auth, Abiquo UI supports two-factor authentication for added security","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"OAuth v1.0 Version A authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Users can register their own applications using","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Abiquo API, see ","type":"text"},{"text":"ApplicationsResource","type":"text","marks":[{"type":"link","attrs":{"href":"https://wiki.abiquo.com/api/latest/ApplicationsResource.html"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Abiquo UI, see ","type":"text"},{"text":"Add an application for OAuth","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/doc/pages/311375737"}}]}]}]}]},{"type":"paragraph","content":[{"text":"The Abiquo API implements the ","type":"text"},{"text":"OAuth 1.0 protocol","type":"text","marks":[{"type":"link","attrs":{"href":"https://tools.ietf.org/html/rfc5849"}}]},{"text":", 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:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The client application requests an","type":"text"},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"Unauthenticated Request Token","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The user authorizes the ","type":"text"},{"text":"Request Token","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The client application exchanges the ","type":"text"},{"text":"Request Token","type":"text","marks":[{"type":"code"}]},{"text":" for an ","type":"text"},{"text":"Access Token","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When the ","type":"text"},{"text":"Access Token","type":"text","marks":[{"type":"code"}]},{"text":" has been granted, the client application can use it to sign the requests and authenticate against the Abiquo API.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following table shows the OAuth specific endpoints that you must use when implementing the OAuth workflow.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"b531c764-738d-4589-94f2-e80162d93221"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[302.0]},"content":[{"type":"paragraph","content":[{"text":"Operation","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[457.0]},"content":[{"type":"paragraph","content":[{"text":"Endpoint","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[302.0]},"content":[{"type":"paragraph","content":[{"text":"Request unauthenticated token","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[457.0]},"content":[{"type":"paragraph","content":[{"text":"/oauth/request_token","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[302.0]},"content":[{"type":"paragraph","content":[{"text":"Authorize request token","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[457.0]},"content":[{"type":"paragraph","content":[{"text":"/oauth/authorize?oauth_token=","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[302.0]},"content":[{"type":"paragraph","content":[{"text":"Get access token","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[457.0]},"content":[{"type":"paragraph","content":[{"text":"/oauth/access_token","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"The following table describes the query parameters that are used in the OAuth authentication workflow:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"e4abe34e-5128-47be-983c-ca15ff228d62"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[142.0]},"content":[{"type":"paragraph","content":[{"text":"Query parameter","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[617.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[142.0]},"content":[{"type":"paragraph","content":[{"text":"oauth_token","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[617.0]},"content":[{"type":"paragraph","content":[{"text":"Required when authorizing a request token.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[142.0]},"content":[{"type":"paragraph","content":[{"text":"oauth_callback","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[617.0]},"content":[{"type":"paragraph","content":[{"text":"A callback URL where clients will be redirected after successful authentication","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[142.0]},"content":[{"type":"paragraph","content":[{"text":"oauth_verifier","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[617.0]},"content":[{"type":"paragraph","content":[{"text":"Verifier value used when authorizing a Request Token","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Why OAuth 1?","type":"text"}]},{"type":"paragraph","content":[{"text":"Abiquo chose to implement OAuth 1 because, at the time of implementation, it was considered more secure and interoperable than OAuth 2. ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"OAuth example applications","type":"text"}]},{"type":"paragraph","content":[{"text":"For an example of an Abiquo authentication flow, please see the following Python and Ruby applications: ","type":"text"},{"text":"https://gist.github.com/nacx/8581621","type":"text","marks":[{"type":"link","attrs":{"href":"https://gist.github.com/nacx/8581621"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"OpenID Connect","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Manually log in to the platform","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When you are redirected back to the Abiquo console, obtain the access token and refresh token from the browser.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Once you have the tokens, you can issue requests to the API by providing the following HTTP header:","type":"text"}]},{"type":"codeBlock","content":[{"text":"Authorization: Bearer ","type":"text"}]},{"type":"paragraph","content":[{"text":"And you can use the Refresh token as necessary.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Abiquo OpenID Connect integration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/doc/pages/311375537"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"SAML","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"SAML integration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/doc/pages/311376236"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Basic HTTP authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"Abiquo supports 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:","type":"text"}]},{"type":"codeBlock","content":[{"text":"Authorization: Basic base64(:)\n","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, for a with the credentials ","type":"text"},{"text":"user:user","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"Authorization: Basic dXNlcjp1c2Vy","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"The authentication workflow should be as follows:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The client requests a resource, without providing any credentials.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An HTTP response code of ","type":"text"},{"text":"401 (Unauthorized)","type":"text","marks":[{"type":"code"}]},{"text":" is returned.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The client requests the resource providing the credentials.","type":"text"},{"type":"hardBreak"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If authentication fails, the server returns an HTTP response code of ","type":"text"},{"text":"401 (Unauthorized)","type":"text","marks":[{"type":"code"}]},{"text":", indicating a ","type":"text"},{"text":"Bad Credentials","type":"text","marks":[{"type":"code"}]},{"text":" or a ","type":"text"},{"text":"User is disabled","type":"text","marks":[{"type":"code"}]},{"text":" error.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If authentication succeeds, but the user does not have enough privileges to access the requested resource, the server returns an HTTP response code of ","type":"text"},{"text":"403 (Forbidden)","type":"text","marks":[{"type":"code"}]},{"text":" indicating a ","type":"text"},{"text":"Denied Access","type":"text","marks":[{"type":"code"}]},{"text":" error.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If authentication is successful, the server returns an HTTP response code of ","type":"text"},{"text":"200 (OK)","type":"text","marks":[{"type":"code"}]},{"text":", the requested resource, and an authentication token that the client can use to authenticate future requests.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The client requests another resource, supplying the authentication token","type":"text"}]}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Basic authentication workflow example","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Request a resource without providing credentials","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Request headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Accept, Content-Type.","type":"text"},{"type":"hardBreak"},{"text":"Request parameters:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request example:","type":"text","marks":[{"type":"strong"}]},{"text":" Retrieve all the datacenters","type":"text"}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters request","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"% curl --verbose 'http://example.com/api/admin/datacenters/' \\\n -X GET \\\n -H \"Accept:application/vnd.abiquo.datacenters+xml\"\n\n> GET /api/admin/datacenters HTTP/1.1\n> 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\n> Host: exmaple.com\n> Accept: application/vnd.abiquo.datacenters+xml","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Response headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Content-Length, Content-Type, WWW-Authenticate, Date.","type":"text"},{"type":"hardBreak"},{"text":"Response message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Response status:","type":"text","marks":[{"type":"strong"}]},{"text":" 200, 401, 403.","type":"text"},{"type":"hardBreak"},{"text":"Example response:","type":"text","marks":[{"type":"strong"}]},{"text":" Response of the unauthenticated GET over a Datacenters resource","type":"text"}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters response","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"< HTTP/1.1 401 Unauthorized\n< Server: Apache-Coyote/1.1\n< WWW-Authenticate: Basic realm=\"Abiquo\"\n< Content-Type: text/html;charset=utf-8\n< Content-Length: 1152\n< Date: Fri, 02 Jul 2010 09:40:14 GMT","type":"text"}]},{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Request a resource providing valid credentials","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Request headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Accept, Content-Type, Authentication.","type":"text"},{"type":"hardBreak"},{"text":"Request parameters:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request example:","type":"text","marks":[{"type":"strong"}]},{"text":" Retrieve all the datacenters","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters request","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"% curl --verbose 'http://example.com/api/admin/datacenters/' \\\n -X GET \\\n -H \"Accept:application/vnd.abiquo.datacenters+xml\" \\\n -H \"Authorization: Basic ZXhhbXBsZTpleGFtcGxl\"\n\n> GET /api/admin/datacenters HTTP/1.1\n> 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\n> Host: example.com\n> Authorization: Basic ZXhhbXBsZTpleGFtcGxl\n> Accept: application/vnd.abiquo.datacenters+xml","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Response headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Content-Length, Content-Type, Date, X-Abiquo-Token.","type":"text"},{"type":"hardBreak"},{"text":"Response message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Response status:","type":"text","marks":[{"type":"strong"}]},{"text":" 200, 401, 403.","type":"text"},{"type":"hardBreak"},{"text":"Example response:","type":"text","marks":[{"type":"strong"}]},{"text":" Response of the authenticated GET over a Datacenters resource","type":"text"}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters response","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"< HTTP/1.1 200 OK\n< Server: Apache-Coyote/1.1\n< X-Abiquo-Token: 1169dbbca2c1123455ab6b5a06b2b38756fb\n< Content-Type: application/vnd.abiquo.datacenters+xml\n< Content-Length: 420\n< Date: Fri, 02 Jul 2010 09:50:52 GMT\n<\n\n\n \n \n \n \n 1\n Redwood city\n myDatacenter\n \n","type":"text"}]},{"type":"paragraph"}]}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"After a successful request, the response will contain the ","type":"text"},{"text":"X-Abiquo-Token","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"header with an authentication token that can be used in subsequent requests, as described in the Token Based Authentication section.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Request a resource providing valid credentials but with insufficient privileges","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Request headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Accept, Content-Type, Authentication.","type":"text"},{"type":"hardBreak"},{"text":"Request parameters:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request example:","type":"text","marks":[{"type":"strong"}]},{"text":" Retrieve all the datacenters","type":"text"}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters request","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"% curl --verbose 'http://example.com/api/admin/datacenters/' \\\n -X GET \\\n -H \"Accept: application/vnd.abiquo.datacenters+xml\" \\\n -H \"Authorization: Basic ZXhhbXBsZTpleGFtcGxl\"\n\n> GET /api/admin/datacenters HTTP/1.1\n> 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\n> Host: example.com\n> Authorization: Basic ZXhhbXBsZTpleGFtcGxl\n> Accept: application/vnd.abiquo.datacenters+xml","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Response headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Content-Length, Content-Type, Date.","type":"text"},{"type":"hardBreak"},{"text":"Response message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Response status:","type":"text","marks":[{"type":"strong"}]},{"text":" 200, 401, 403.","type":"text"},{"type":"hardBreak"},{"text":"Example response:","type":"text","marks":[{"type":"strong"}]},{"text":" Response of the authenticated GET over a Datacenters resource, but without enough privileges","type":"text"}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters response","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"< HTTP/1.1 403 Forbidden\n< Server: Apache-Coyote/1.1\n< Content-Type: text/html;charset=utf-8\n< Content-Length: 1021\n< Date: Fri, 02 Jul 2010 09:59:42 GMT","type":"text"}]},{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Token-based authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"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 to pass the credentials. Each HTTP response contains a header with an expirable token that you can use to perform requests to the API. In order to use token-based authentication, the client must send it in the ","type":"text"},{"text":"Authorization","type":"text","marks":[{"type":"code"}]},{"text":" header, as follows:","type":"text"}]},{"type":"paragraph","content":[{"text":"Authentication header format for token-based authentication","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"Authorization: Token ","type":"text"}]},{"type":"paragraph","content":[{"text":"After a successful request, the response will contain the ","type":"text"},{"text":"X-Abiquo-Token","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"header with a new token that can be used in subsequent requests.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Request a resource without providing credentials","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Request headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Accept, Content-Type.","type":"text"},{"type":"hardBreak"},{"text":"Request parameters:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request example:","type":"text","marks":[{"type":"strong"}]},{"text":" Retrieve all datacenters","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters request","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"% curl --verbose 'http://example.com/api/admin/datacenters/' \\\n -X GET \\\n -H \"Accept:application/vnd.abiquo.datacenters+xml\"\n\n> GET /api/admin/datacenters HTTP/1.1\n> 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\n> Host: exmaple.com\n> Accept: application/vnd.abiquo.datacenters+xml","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Response headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Content-Length, Content-Type, WWW-Authenticate, Date.","type":"text"},{"type":"hardBreak"},{"text":"Response message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Response status:","type":"text","marks":[{"type":"strong"}]},{"text":" 200, 401, 403.","type":"text"},{"type":"hardBreak"},{"text":"Example response:","type":"text","marks":[{"type":"strong"}]},{"text":" Response of the unauthenticated ","type":"text"},{"text":"GET","type":"text","marks":[{"type":"code"}]},{"text":" request to the ","type":"text"},{"text":"Datacenters","type":"text","marks":[{"type":"code"}]},{"text":" resource","type":"text"}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters response","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"< HTTP/1.1 401 Unauthorized\n< Server: Apache-Coyote/1.1\n< WWW-Authenticate: Token realm=\"Abiquo\"\n< Content-Type: text/html;charset=utf-8\n< Content-Length: 1152\n< Date: Fri, 02 Jul 2010 09:40:14 GMT","type":"text"}]},{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Request a resource providing valid credentials","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Request headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Accept, Content-Type, Authentication.","type":"text"},{"type":"hardBreak"},{"text":"Request parameters:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Request example:","type":"text","marks":[{"type":"strong"}]},{"text":" Retrieve all the datacenters","type":"text"}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters request","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"% curl --verbose 'http://example.com/api/admin/datacenters/' \\\n -X GET \\\n -H \"Accept:application/vnd.abiquo.datacenters+xml\" \\\n -H \"Authorization: Token 1169dbbca2c1da4da5ab6b5a06b2b38756fb\"\n\n> GET /api/admin/datacenters HTTP/1.1\n> 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\n> Host: example.com\n> Authorization: Token 1169dbbca2c1da4da5ab6b5a06b2b38756fb\n> Accept: application/vnd.abiquo.datacenters+xml","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Response headers:","type":"text","marks":[{"type":"strong"}]},{"text":" Content-Length, Content-Type, Date, ","type":"text"},{"text":"X-Abiquo-Token","type":"text","marks":[{"type":"textColor","attrs":{"color":"#032f62"}}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"Response message body:","type":"text","marks":[{"type":"strong"}]},{"text":" N/A.","type":"text"},{"type":"hardBreak"},{"text":"Response status:","type":"text","marks":[{"type":"strong"}]},{"text":" 200, 401, 403.","type":"text"},{"type":"hardBreak"},{"text":"Example response:","type":"text","marks":[{"type":"strong"}]},{"text":" Response of the authenticated GET over a Datacenters resource","type":"text"},{"type":"hardBreak"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET datacenters response","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"< HTTP/1.1 200 OK\n< Server: Apache-Coyote/1.1\n< X-Abiquo-Token: 1169dbbca2c1123455ab6b5a06b2b38756fb\n< Content-Type: application/vnd.abiquo.datacenters+xml\n< Content-Length: 420\n< Date: Fri, 02 Jul 2010 09:50:52 GMT\n<\n\n\n \n \n \n \n 1\n Redwood city\n myDatacenter\n \n","type":"text"}]},{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Two factor authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"With Basic Authentication, Abiquo can protect user accounts with a two-factor authentication code. When you enable two-factor authentication, users must provide an additional verification code to prove their identity. Abiquo will deliver that code to the user, through the configured system. Currently, there are two ways that Abiquo can deliver the code:","type":"text"}]},{"type":"table","attrs":{"layout":"wide","localId":"5ce724bd-92a1-4617-8827-81ceeb52f1e0"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[196.0]},"content":[{"type":"paragraph","content":[{"text":"Email","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[764.0]},"content":[{"type":"paragraph","content":[{"text":"The verification code will be sent to the user's by e-mail every time for each login","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f0f0f0","rowspan":1,"colwidth":[196.0]},"content":[{"type":"paragraph","content":[{"text":"Google Authenticator","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[764.0]},"content":[{"type":"paragraph","content":[{"text":"The Google Authenticator mobile app will generate the verification code for each login","type":"text"}]}]}]}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Two factor authentication is an addition to Basic Auth","type":"text","marks":[{"type":"strong"}]},{"text":". Applications using OAuth do not need to provide the two factor verification code","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Enable two factor authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"Users with access to the ","type":"text"},{"text":"User icon","type":"text","marks":[{"type":"strong"}]},{"text":" menu can enable two factor authentication from the corresponding menu option. See ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://abiquo.atlassian.net/wiki/spaces/doc/pages/311370233"}},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"The following step-by-step example shows how to enable two factor authentication for a user via the API:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Get the information of the current user:","type":"text"}]},{"type":"paragraph","content":[{"text":"GET user info","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"% curl -v -u admin:xabiquo http://example.com/api/login -H \"Accept:application/vnd.abiquo.user+xml\"\n\n> GET /api/login HTTP/1.1\n> Authorization: Basic YWRtaW46eGFiaXF1bw==\n> User-Agent: curl/7.38.0\n> Host: example.com\n> Accept:application/vnd.abiquo.user+xml\n\n< HTTP/1.1 200 OK\n< Server: Apache-Coyote/1.1\n< Set-Cookie: auth=YWRtaW46MTQ0MzcxMDM3NDgxMzphZjdjNTY1ZjJhNDgzNTc4Y2EyZGEzNTJiNTcwNmE3ZDpBQklRVU8; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly\n< Set-Cookie: ABQSESSIONID=1691863788974462744; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly\n< Content-Type: application/vnd.abiquo.user+xml\n< Content-Length: 1422\n< Date: Thu, 01 Oct 2015 14:09:35 GMT\n\n\n\n \n \n \n \n \n \n \n 1\n admin\n Cloud\n Administrator\n Main administrator\n \n en_US\n ABIQUO\n true\n false\n false\n","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The user info contains a link to","type":"text"},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"enable two factor authentication","type":"text","marks":[{"type":"code"}]},{"text":". To enable two factor authentication, send a ","type":"text"},{"text":"POST","type":"text","marks":[{"type":"code"}]},{"text":" request indicating the type of two-factor authentication to enable.","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"Enable two factor authentication","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"% curl -v -u admin:xabiquo -X POST http://localhost:80/api/admin/enterprises/1/users/1/action/enable2fa \\\n -H \"Accept: application/vnd.abiquo.twofactorauthcredentials+json\" \\\n -H \"Content-type: application/vnd.abiquo.twofactorauthprovider+json\" \\\n -d '{\"type\": \"GOOGLE_AUTHENTICATOR\"}'\n\n> POST /api/admin/enterprises/1/users/1/action/enable2fa HTTP/1.1\n> Authorization: Basic YWRtaW46eGFiaXF1bw==\n> User-Agent: curl/7.38.0\n> Host: localhost\n> Accept: application/vnd.abiquo.twofactorauthcredentials+json\n> Content-type: application/vnd.abiquo.twofactorauthprovider+json\n> Content-Length: 32\n\n< HTTP/1.1 201 Created\n* Server Apache-Coyote/1.1 is not blacklisted\n< Server: Apache-Coyote/1.1\n< Set-Cookie: auth=YWRtaW46MTQ0MzcxMTM2NTcyNzpjOWJmYzczMmRlOGU3ODBmMzFiN2JkYmZhN2RiMTYzMDpBQklRVU8; Expires=Thu, 01-Oct-2015 14:56:05 GMT; Path=/; HttpOnly\n< Set-Cookie: ABQSESSIONID=3703152771382913736; Expires=Thu, 01-Oct-2015 14:56:05 GMT; Path=/; HttpOnly\n< Content-Type: application/vnd.abiquo.twofactorauthcredentials+json\n< Transfer-Encoding: chunked\n< Date: Thu, 01 Oct 2015 14:26:05 GMT\n\n{\n \"authenticatorURL\" : \"otpauth://totp/Abiquo:admin?secret=UXEHFMAX7RXAJHYE&issuer=Abiquo\",\n \"links\" : [],\n \"provider\" : \"GOOGLE_AUTHENTICATOR\",\n \"scratchCodes\" : [\n \"88309169\",\n \"40838958\",\n \"93393020\",\n \"91684230\",\n \"17576595\"\n ]\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"The value of the ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code"}]},{"text":" attribute can be one of the following: ","type":"text"},{"text":"EMAIL","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"GOOGLE_AUTHENTICATOR","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"The response contains all the two-factor authentication details:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"authenticationURL","type":"text","marks":[{"type":"code"}]},{"text":" that can be used to enable Abiquo in the Google Authenticator mobile app. You can use it to generate a QR code that can be directly scanned using the app, or a URL that can be manually typed in it.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Interaction with the API with two factor authentication enabled","type":"text"}]},{"type":"paragraph","content":[{"text":"When two factor authentication is enabled, normal requests using Basic Authentication will fail and the two factor verification code will be requested:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET user info without the verification code","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"% curl -v -u admin:xabiquo http://example.com/api/login -H \"Accept:application/vnd.abiquo.user+xml\"\n\n> GET /api/login HTTP/1.1\n> Authorization: Basic YWRtaW46eGFiaXF1bw==\n> User-Agent: curl/7.38.0\n> Host: example.com\n> Accept:application/vnd.abiquo.user+xml\n\n\n< HTTP/1.1 401 Unauthorized\n< Server: Apache-Coyote/1.1\n< Set-Cookie: auth=\"\"; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/api\n< WWW-Authenticate: Basic realm=\"Abiquo\"\n< X-Abiquo-OTP: required; type=GOOGLE_AUTHENTICATOR","type":"text"}]},{"type":"paragraph"}]}]},{"type":"paragraph","content":[{"text":"Note the header: ","type":"text"},{"text":"X-Abiquo-OTP: required;","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"This header indicates that the verification code is missing, and the ","type":"text"},{"text":"type","type":"text","marks":[{"type":"strong"}]},{"text":" parameter indicates how the user can get it. The possible values are:","type":"text"},{"type":"hardBreak"}]},{"type":"table","attrs":{"layout":"full-width","localId":"f4707705-0cbd-498d-8e33-1fb5cf7a7bd0"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[261.0]},"content":[{"type":"paragraph","content":[{"text":"EMAIL","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1083.0]},"content":[{"type":"paragraph","content":[{"text":"The user will receive an email with the verification code.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f0f0f0","rowspan":1,"colwidth":[261.0]},"content":[{"type":"paragraph","content":[{"text":"GOOGLE_AUTHENTICATOR","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1083.0]},"content":[{"type":"paragraph","content":[{"text":"The user should use the Google Authenticator mobile app to generate the verification code.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f0f0f0","rowspan":1,"colwidth":[261.0]},"content":[{"type":"paragraph","content":[{"text":"none","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1083.0]},"content":[{"type":"paragraph","content":[{"text":"The user has not enabled two factor authentication but the enterprise requires it to access Abiquo. The user must enable 2FA using the method described above.","type":"text"}]}]}]}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"When the user has the verification code, they can provide it in the ","type":"text"},{"text":"X-Abiquo-OTP","type":"text","marks":[{"type":"strong"}]},{"text":" header, as follows:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET user info with the verification code","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"% curl -v -u admin:xabiquo http://example.com/api/login \\\n -H \"Accept:application/vnd.abiquo.user+xml\" \\\n -H \"X-Abiquo-OTP: 670870\"\n\n> GET /api/login HTTP/1.1\n> Authorization: Basic YWRtaW46eGFiaXF1bw==\n> User-Agent: curl/7.38.0\n> Host: example.com\n> Accept:application/vnd.abiquo.user+xml\n> X-Abiquo-OTP: 637614\n\n< HTTP/1.1 200 OK\n< Server: Apache-Coyote/1.1\n< Set-Cookie: auth=YWRtaW46MTQ0MzcxMDM3NDgxMzphZjdjNTY1ZjJhNDgzNTc4Y2EyZGEzNTJiNTcwNmE3ZDpBQklRVU8; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly\n< Set-Cookie: ABQSESSIONID=1691863788974462744; Expires=Thu, 01-Oct-2015 14:39:34 GMT; Path=/; HttpOnly\n< Content-Type: application/vnd.abiquo.user+xml\n< Content-Length: 1422\n\n\n\n\n \n \n \n \n \n \n \n 1\n admin\n Cloud\n Administrator\n Main administrator\n \n en_US\n ABIQUO\n true\n false\n false\n","type":"text"}]},{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Disable two factor authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"POST","type":"text","marks":[{"type":"code"}]},{"text":" request there to disable it:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Disable two factor authentication","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"% curl -v -u admin:xabiquo http://localhost:80/api/admin/enterprises/1/users/1/action/disable2fa \\\n -x POST\n -H \"X-Abiquo-OTP: 670870\"\n\n> POST /api/admin/enterprises/1/users/1/action/disable2fa HTTP/1.1\n> Authorization: Basic YWRtaW46eGFiaXF1bw==\n> User-Agent: curl/7.38.0\n> Host: localhost\n> Accept: */*\n> X-Abiquo-OTP: 670870\n\n< HTTP/1.1 204 No Content\n< Server: Apache-Coyote/1.1\n< Set-Cookie: auth=YWRtaW46MTQ0MzcxMjI0MzM2Mzo5OTkxYTRlMGJmMzBlYjcwZmVjNjYwNDQyYmFkZTlkMjpBQklRVU8; Expires=Thu, 01-Oct-2015 15:10:43 GMT; Path=/; HttpOnly\n< Set-Cookie: ABQSESSIONID=2563697997063896162; Expires=Thu, 01-Oct-2015 15:10:43 GMT; Path=/; HttpOnly","type":"text"}]},{"type":"paragraph"}]}]}],"version":1}

Browser not supported