Basic Authentication

Tyk supports using basic authentication as an access key in the same way as any other access method.

What is Basic Authentication?

Protect your API with Basic Authentication

To enable Basic Authentication on your API 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.

Create a Basic Auth Key For the API

We have tutorials for creating an API Key via the Dashboard. To use with Basic Authentication, select your API that you selected Basic Authentication for. From the Authentication tab, you can see that Basic Authentication settings are automatically displayed.

And then add a username & password:

Then save! Now we 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>

Enable Basic Authentication in your API Definition with file-based

To enable Basic Authentication, the API Definition file needs to be set up to allow basic authentication and not a standard access token:

{
  "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 BA is a standard, Tyk will always look for the credentials as part of the Authorization header.

Create a Basic Authentication User using the API

Basic authentication keys are not created the same way as other keys. Since the key ID is not generated by the system a basic authentication key cannot use the /tyk/keys/create endpoint, and instead should POST to /tyk/keys/{username} of the Tyk Gateway API. This will ADD a key to the system. Subsequent requests will overwrite this entry, sending a PUT request will update the entry.

Using Gateway API

The below command will use the Tyk Gateway API to create a new basic authentication user in the Tyk Gateway:

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 Dashboard API

The following command will create a basic authentication user with the 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": "mickey-mouse"
    }
 }' http://{your-tyk-dashboard-host}:{port}/api/apis/keys/basic/mysupertestuser2 | python -mjson.tool

See Basic Authentication via the Dashboard API

Extracting credentials from the body

In some cases, like dealing with SOAP, user credentials can be passed via request body. In this case you can configure basic auth plugin to extract username and password from body, by providing regexps like this:

"basic_auth": {
    "extract_from_body": true,
    "body_user_regexp": "<User>(.*)</User>",
    "body_password_regexp": "<Password>(.*)</Password>"
}

Note that regexp should contain only one match group, which points to the actual value.

What is Basic Authentication?

In the context of an HTTP transaction, basic access authentication is a method for an HTTP user agent to provide a user name and password when making a request. HTTP Basic authentication (BA) implementation is the simplest technique for enforcing access controls to web resources because it doesn’t require cookies, session identifiers, or login pages; rather, HTTP Basic authentication uses standard fields in the HTTP header, obviating the need for handshakes. (Source: wikipedia)

Basic Authentication is a standard authentication mechanism supported by every standards-compliant HTTP server, it is also supported by almost every single web browser, which makes it an excellent access control method for smaller APIs.

However, a serious drawback of Basic Authentication is that credentials are transferred in encoded plain text over the wire, this can be a serious concern for API owners and should therefore only ever be used in conjunction with TLS such as SSL.

A basic authentication request will have an Authorization header where the value will be in the form of:

Basic base64Encode(username:password)

This means a real request would look something like:

GET /api/widgets/12345 HTTP/1.1
Host: localhost:8080
Authorization: Basic am9obkBzbWl0aC5jb206MTIzNDU2Nw==
Cache-Control: no-cache

In the above example the username is [email protected] and the password is 1234567.