Documentation Documentation

Basic Authentication

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.

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

Enable Basic Authentication in your API Definition with the Dashboard

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 Auth from the drop-down list
  4. Select Strip Authorization Data to strip any authorization data from your API requests.

Target Details: Basic Auth

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 Key with Basic Authentication

We have tutorials for creating an API Key via the Dashboard. To use with Basic Authentication, select the Basic Authentication option.

Keys Basic Auth

Create a Basic Authentication User

For a user session object, to enable basic authentication set the relevant fields in the session object:

{
  ...
  "basic_auth_data": {
      "password": "mickey-mouse"
  }
  ...
}

Notice the basic_auth_data section - this is all that is really required.If an API is basic authentication enabled, any keys that are retrieved will check this field for a password and compare it to the password encoded in the request. The password will be encrypted by default using bcrypt to ensure it is secure.

Note: 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.

Create a Basic Authentication User using the 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

Create a Basic Authentication User using the Dashboard API

The following command will create a basic authentication user with the Tyk Dashboard API:

curl -X POST -H "Authorization: {YOUR API KEY}"
 -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}/api/apis/keys/basic/mysupertestuser2 | python -mjson.tool

Note: The most important thing to ensure with both of these commands is that the ORG ID is set correctly and consistently.

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.