Basic Authentication
What is Basic Authentication?
Basic Authentication is a standard authentication mechanism implemented by HTTP servers, clients and web browsers. This makes it an excellent access control method for smaller APIs.
How does Basic Authentication work?
An API request made using Basic Authentication will have an Authorization
header that contains the API key.
The value of the Authorization
header will be in the form:
Basic base64Encode(username:password)
A real request could look something like:
GET /api/widgets/12345 HTTP/1.1
Host: localhost:8080
Authorization: Basic am9obkBzbWl0aC5jb206MTIzNDU2Nw==
Cache-Control: no-cache
In this example the username is [email protected]
and the password is 1234567
(see base64encode.org)
The problem with Basic Authentication
With Basic Authentication, the authentication credentials are transferred from client to server (in our case, the Tyk Gateway) as encoded plain text. This is not a particularly secure way to transfer the credentials as it is highly susceptible to intercept; as the security of user authentication is usually of critical importance to API owners, Tyk recommends that Basic Authentication should only ever be used in conjunction with a TLS such as SSL.
Protect your API with Basic Authentication
Authentication type is configured within your API Definition; this can be done via the Tyk Dashboard or directly within the API Definition file.
Enable Basic Authentication using the Tyk Dashboard
- Select your API from the System Management > APIs menu
- Scroll to the Authentication options
- Select Basic Authentication from the drop-down list
- Select Strip Authorization Data to strip any authorization data from your API requests.
- Tyk will by default assume you are using the
Authorization
header, but you can change this by setting the Auth Key Header name value - You can select whether to use a URL query string parameter as well as a header, and what parameter to use. If this is left blank, it will use the Auth Key Header name value.
- You can select whether to use a cookie value. If this is left blank, it will use the Header name value.
Enable Basic Authentication in your file-based API Definition
To enable Basic Authentication, the API Definition file needs to be set up to allow basic authentication rather than expecting a standard access token; this is achieved by setting use_basic_auth
to true:
{
"name": "Tyk Test API",
...
"use_basic_auth": true,
...
}
As you can see in the above example, enabling Basic Authentication is as simple as setting a flag for the feature in your API Definition object. Since Basic Authentication is a standard, Tyk will always look for the credentials as part of the Authorization
header.
Create a Basic Authentication user
When using Basic Authentication, the API key used to access the API is not generated by the Tyk system, instead you need to create at least one Basic Authentication user in the Tyk Gateway. Tyk will compare the Basic Authentication key provided in the request against the list of users you have created.
Using Tyk Dashboard
You can use the Tyk Dashboard to register a Basic Authentication key that can then be used to access your API.
When you select the API, you can see that Basic Authentication settings are automatically displayed in the Authentication tab:
Then add a username & password and save!
Now you can curl the API in two different ways:
$ curl http://localhost:8080/basicauth/get \
--header "Authorization: Basic $(echo -n 'myusername:mypassword' | base64)"
<200 response>
$ curl http://myusername:mypassword@localhost:8080/basicauth/get
<200 response from upstream>
We have full tutorials to guide you to create an API Key via the Dashboard.
Using the Tyk Gateway API
This command creates a new basic authentication user in the Tyk Gateway with the user name testuser
and password mickey-mouse
by sending a POST
command to the /tyk/keys/
endpoint of Tyk Gateway API:
curl -X POST -H "x-tyk-authorization: 352d20fe67be67f6340b4c0605b044c3" \
-s \
-H "Content-Type: application/json" \
-X POST \
-d '{
"allowance": 1000,
"rate": 1000,
"per": 1,
"expires": -1,
"quota_max": -1,
"org_id": "53ac07777cbb8c2d53000002",
"quota_renews": 1449051461,
"quota_remaining": -1,
"quota_renewal_rate": 60,
"access_rights": {
"{API-ID}": {
"api_id": "{API-ID}",
"api_name": "{API-NAME}",
"versions": ["Default"]
}
},
"meta_data": {},
"basic_auth_data": {
"password": "mickey-mouse"
}
}' http://{your-tyk-gateway-host}:{port}/tyk/keys/testuser | python -mjson.tool
Note
You use POST
to create a new user and PUT
to update an existing entry.
Be careful to ensure that the org_id
is set correctly and consistently so that the Basic Authentication user is created in the correct organisation.
Using the Tyk Dashboard API
This command creates a new basic authentication user in the Tyk Gateway with the user name testuser2
and password minnie-mouse
by sending a POST
command to the /tyk/keys/
endpoint of Tyk Dashboard API:
curl -X POST -H "Authorization: 907aed9f88514f175f1dccf8a921f741"
-s
-H "Content-Type: application/json"
-X POST
-d '{
"allowance": 1000,
"rate": 1000,
"per": 1,
"expires": -1,
"quota_max": -1,
"org_id": "53ac07777cbb8c2d53000002",
"quota_renews": 1449051461,
"quota_remaining": -1,
"quota_renewal_rate": 60,
"access_rights": {
"{API-ID}": {
"api_id": "{API-ID}",
"api_name": "{API-NAME}",
"versions": [
"Default"
]
}
},
"meta_data": {},
"basic_auth_data": {
"password": "minnie-mouse"
}
}' http://{your-tyk-dashboard-host}:{port}/api/apis/keys/basic/testuser2 | python -mjson.tool
See Basic Authentication via the Dashboard API
Note
You use POST
to create a new user and PUT
to update an existing entry.
Be careful to ensure that the org_id
is set correctly and consistently so that the Basic Authentication user is created in the correct organisation.
Extracting credentials from the request body
In some cases, for example when dealing with SOAP, user credentials can be passed within the request body. To handle this situation, you can configure basic auth plugin to extract username and password from the body, by providing regexps like this:
"basic_auth": {
"extract_from_body": true,
"body_user_regexp": "<User>(.*)</User>",
"body_password_regexp": "<Password>(.*)</Password>"
}
Note that the regexp should contain only one match group, which points to the actual value.