Difference between revisions of "Basic authentication"

From Barion Documentation
Jump to navigation Jump to search
Line 1: Line 1:
 
{{PageTitle|title=Basic Authentication}}
 
{{PageTitle|title=Basic Authentication}}
  
A client that wants to authenticate itself with the server can do so by including an Authorization request header field with the credentials. In the case of a "Basic" authentication, the exchange must happen over an HTTPS (TLS) connection. Username and password are passed over the network as a base64 encoded string with a ":" separated. The following is a correct example of the Authorization header:<br/>
+
If a client wants to authenticate itself with the server during an API call can now do so by using a standard HTTP Basic Auth request header with the necessary credentials. This eliminates the need for supplying a username and password combination in the query string, which is a far less secure method.
<code>Authorization: Basix YWxhZGRpbjpvcGVuc2VzYW1l</code>
+
 
 +
== Usage ==
 +
 
 +
In case of a "Basic" authentication, communication must take place over an HTTPS (TLS) connection. The username and password are passed over the network as strings separated by a semicolon (":"), then converted into a base64 string.  
 +
 
 +
Example authentication data:<br/>
 +
<code>MyUser:MY_Str0ng_P455w0Rd</code>
 +
 
 +
Example HTTP header:<br/>
 +
<code>Authorization: Basic TXlVc2VyOk1ZX1N0cjBuZ19QNDU1dzBSZA==</code>
 
<br/><br/>
 
<br/><br/>
If the "Authorization" header is present, username and password will be fetched form the header, the ones passed in the querystring will be ignored. Should the authentication be unsuccessful (either username and/or password could not be decoded from the header, or the authentication type is not basic) HTTP 401 (Unathorized) will be the response. Invalid username/password yields a HTTP 400 (Bad Request) response. If the "Authorization" header is not present, credentials will retrieved from the querystring.
+
 
 +
== Server response ==
 +
If the '''Authorization''' header is present, username and password will be fetched form the header. In this case, any authentication data passed in the query string will be ignored.  
 +
* If the authentication data could not be decoded from the header, or the authentication type is not ''Basic'' the response will be <code>HTTP 401 Unathorized</code>
 +
* If the username/password combination is invalid, the response will be <code>HTTP 400 Bad Request</code>.
 +
* If the '''Authorization''' header is not present, credentials will be retrieved from the query string, and if incorrect, the response will be a JSON output describing the authentication error.
 +
 
 +
== Allowed authentication data ==
 +
At the moment, only endpoints authenticated with '''username''' and '''password''' can be used with HTTP Basic Auth. Every other authentication parameters (e.g. '''POSKey''') should be sent in the query string when executing <code>GET</code> request.

Revision as of 13:01, 3 December 2019

If a client wants to authenticate itself with the server during an API call can now do so by using a standard HTTP Basic Auth request header with the necessary credentials. This eliminates the need for supplying a username and password combination in the query string, which is a far less secure method.

Usage

In case of a "Basic" authentication, communication must take place over an HTTPS (TLS) connection. The username and password are passed over the network as strings separated by a semicolon (":"), then converted into a base64 string.

Example authentication data:
MyUser:MY_Str0ng_P455w0Rd

Example HTTP header:
Authorization: Basic TXlVc2VyOk1ZX1N0cjBuZ19QNDU1dzBSZA==

Server response

If the Authorization header is present, username and password will be fetched form the header. In this case, any authentication data passed in the query string will be ignored.

  • If the authentication data could not be decoded from the header, or the authentication type is not Basic the response will be HTTP 401 Unathorized
  • If the username/password combination is invalid, the response will be HTTP 400 Bad Request.
  • If the Authorization header is not present, credentials will be retrieved from the query string, and if incorrect, the response will be a JSON output describing the authentication error.

Allowed authentication data

At the moment, only endpoints authenticated with username and password can be used with HTTP Basic Auth. Every other authentication parameters (e.g. POSKey) should be sent in the query string when executing GET request.