Kong is a service that sits between a client and a server, such as a web server, an application server, an FTP server.
Let's say you have a web server. Requests for HTML web pages can be sent through Kong. The following is the bare minimum that would need to be done to route requests through Kong.
- Install Kong
- Start Kong
- Create a service
- Create a route
curl is typically used to interact with Kong, such as getting all of the services.
curl --header apikey:abc123 --request GET "http://kong.example.com:8000/admin-api/services"
Create a Service
Let's say you want to route requests for www.example.com through Kong. In this scenario, you could create a service named "example-service".
Create a Route
Then you could create a route that routes requests for "example-service" to www.example.com.
GET www.example.com through Kong
You should now be able to get an HTML web pages from the www.example.com web server through Kong.
curl -v -X GET "http://localhost:8001/" --header "Host: www.example.com"
If the request is successful, you should get something like this. The -v option shows the request for www.example.com was responded by Kong.
> Host: www.example.com
< Via: kong/2.0.1
<body>
<div>
<h1>Example Domain</h1>
<p>This domain is for use in illustrative examples in documents. You may use this
domain in literature without prior coordination or asking for permission.</p>
<p><a href="https://www.iana.org/domains/example">More information...</a></p>
</div>
</body>
</html>
Configure a Plugin
Plugins are used to allow or deny a request. One or more plugins can be associated with a service . . .
Like this.
curl -X POST "http://localhost:8001/services/example-service/plugins" . . .
. . . or with a route.
Like this.
curl -X POST "http://localhost:8001/routes/route-id/plugins" . . .
Two commonly used plugins are:
In this example, the ACL plugin and key-auth plugin are associated with "example-service".
curl -X POST "http://localhost:8001/services/example-service/plugins" --data "name=acl" --data "config.whitelist=example-group"
curl -X POST "http://localhost:8001/services/example-service/plugins" --data "name=key-auth"
With this setup, a request will only be allowed when:
- The consumer is in "example-group"
- The consumer presents the appropriate key-auth key for authentication
Attempting to get www.example.com through Kong from a consumer not in "example-group" and without the appropriate key for authentication . . .
curl -v -X GET "http://localhost:8001/" --header "Host: www.example.com"
. . . should return this header.
< HTTP/1.1 403 Forbidden
And this message.
{
"message":"No API key found in request"
}
An examination of the header will show no API key in the request.
> GET / HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.44 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Accept: */*
> Host: www.example.com
Let's say you try the request with some random API key.
curl -v -X GET "http://localhost:8001/" --header "Host: www.example.com" --header "apikey: abc123"
Now the request includes an API key.
> GET / HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.44 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Accept: */*
> Host: www.example.com
> apikey:abc123
But the following is returned, because no consumers have been setup with the apikey.
{
"message":"You cannot consume this service"
}
Consumer
In this scenario, a consumer will need to be a member of the acl group that has been whitelisted and the consumer will need to include the key-auth key when submitting a request to example-service.
Let's create a consumer named john.doe.
curl -X POST "http://localhost:8001/consumers/" --data "username=john.doe"
Make john.doe a member of example-group.
curl -X POST "http://localhost:8001/consumers/john.doe/acls" --data "group=example-group"
provision john.doe with an API Key
curl -X POST "http://localhost:8001/consumers/john.doe/key-auth" --data "key=abc123"
Now, you should be able to get an HTML web pages from the www.example.com web server through Kong by providing the API Key. In this example, the the API Key is "abc123".
curl -v -X GET "http://localhost:8001/" --header "Host: www.example.com" --header "apikey:abc123"
The -v option will show that API Key was sent in the request.
> apikey:abc123
> Host: www.example.com
If the GET request is successful, the HTML page should be display. On the other hand, if an invalid API Key is used in the request, the following should be displayed.
{
"message":"Invalid authentication credentials"
}
Did you find this article helpful?
If so, consider buying me a coffee over at 