Basic authentication: Difference between revisions
No edit summary |
mNo edit summary |
||
| (8 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
__NOTOC__ | |||
{{PageTitle|title=Basic Authentication}} | {{PageTitle|title=Basic Authentication}} | ||
If a client wants to authenticate itself with the server during an API call can | If a client wants to authenticate itself with the server during an API call can 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. Logging in with Basic Authentication is the preferred mode. The querystring method is not secure. | ||
== Usage == | == Usage == | ||
In case of a | 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/> | Example authentication data:<br/> | ||
| Line 12: | Line 13: | ||
Example HTTP header:<br/> | Example HTTP header:<br/> | ||
<code>Authorization: Basic TXlVc2VyOk1ZX1N0cjBuZ19QNDU1dzBSZA==</code> | <code>Authorization: Basic TXlVc2VyOk1ZX1N0cjBuZ19QNDU1dzBSZA==</code> | ||
<br/ | |||
<br> | |||
Detailed information about basic authentication can be found in RFC 7617: | |||
https://tools.ietf.org/html/rfc7617 | |||
== Server response == | == 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 '''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 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 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. | * 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 == | == 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> | 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> requests. | ||
Latest revision as of 12:44, 5 December 2019
Basic Authentication
If a client wants to authenticate itself with the server during an API call can 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. Logging in with Basic Authentication is the preferred mode. The querystring method is not secure.
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==
Detailed information about basic authentication can be found in RFC 7617:
https://tools.ietf.org/html/rfc7617
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 requests.