Documentation Documentation

Basic Auth

What is Basic Auth ?

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 plaintext 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 auth request will have an Authorization header where the value will be of the form:

	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 Auth in your API Definition with the Dashboard

To enable Basic Auth on your API using the dashboard GUI:

  1. Navigate to your API via “System Management” -> “APIs” -> Select your API
  2. Scroll to the bottom where it says “Target details”
  3. Select the “Basic Auth” option

Target Details: Basic Auth

Enable Basic Auth in your API Definition with file-based

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

	{
	  "name": "Tyk Test API",
	  ...
	  "use_basic_auth": true,
	  ...
	}

As you can see in the above example, enabling basic auth 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 Auth User

For a user session object, to enable basic auth, 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 auth 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 auth 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 user using Gateway API

The below command will use the gateway API to generate a new basic auth user in 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 user using Dashboard API

The following command will create a basic auth user with the 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.