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

1. Select your API from the System Management > APIs menu
2. Scroll to the Authentication options
3. Select Basic Authentication from the drop-down list
4. Select Strip Authorization Data to strip any authorization data from your API requests.
5. Tyk will by default assume you are using the Authorization header, but you can change this by setting the Auth Key Header name value
6. 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.
7. 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.

Enable basic authentication using Tyk Operator

Please consult the Tyk Operator supporting documentation for an example of how to enable basic authentication with Tyk Operator.

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

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

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.